hk-creating-checkslisted
Install: claude install-skill technicalpickles/pickled-claude-plugins
# Creating hk checks
A check is an hk **step**: a name, the files it applies to, and `check` / `fix` commands, defined in `hk.pkl` (hk's config, written in the Pkl language). This skill is about writing one that works on the hk version the project actually runs.
## First: which hk?
Syntax and agent-safety features changed a lot between 1.x and 2.x. Find out before writing anything:
```bash
hk --version # the runtime
grep -m1 'hk@' hk.pkl # the schema the config amends (hk@X.Y.Z)
grep -n 'hk' mise.toml .mise.toml 2>/dev/null # what the project pins
```
The `amends` URL decides what syntax is valid; the binary decides what runs. They can disagree. Check [references/versions.md](references/versions.md) for what each version supports. The short version:
| hk | What you can use |
|----|------------------|
| before 1.55 | String commands only. No `effect`, no `--safe`, no `hk agent`. |
| 1.55 and later | `CommandSpec` with `effect`, `--safe`, `hk agent`, `hk mcp`. |
| 2.0 and later | Top-level `steps` (implicit `check`, `fix`, `pre-commit` hooks), flat builtins with options, Pkl-only config. |
## Workflow
1. **Look for a builtin first.** `hk builtins | grep -i <tool>`. Use `Builtins.<name>` and override only what differs: `(Builtins.ruff) { glob = List("src/**/*.py") }`. Builtins already declare effects (1.55 and later).
2. **Otherwise write a step.** See [references/step-anatomy.md](references/step-anatomy.md) for fi