← ClaudeAtlas

hk-creating-checkslisted

Use when adding, writing, or fixing a check (step) in an hk.pkl, picking a builtin or writing a custom command, declaring an effect for `--safe`, or when hk reports "effect is unknown", "unexpected argument '--safe'", or "Hook 'check' not found". Also use when a step's syntax differs between hk 1.x and 2.x. For installing hk, hook basics, or the builtin list, use `dev-tools:hk` instead; this skill is about writing steps.
technicalpickles/pickled-claude-plugins · ★ 13 · Code & Development · score 73
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