Capability builder

A capability is worth building when the same ask comes back: a third "take screenshots for the PR", the same check before every commit, the same setup explained to every newcomer. Build it in the user's own ~/.claude first, where it is used and tested for real, then offer to share a generic copy in a kit (the public claude-code-kit, a team kit, or one the user keeps).

1. Spot it and say it

Name the repeated ask in one line, with two real examples from this conversation or the memory, and propose the kind that fits (step 2) with the reason. Build nothing before the user's yes.

2. Pick the kind

Prefer the lightest that works. A rule Claude forgets is a hook; a hook that needs judgement is a skill; a skill that only runs one command is a script. Tool-agnostic first: the logic in a plain script any agent or a person can run, the skill or hook a thin layer over it.

3. Interview

Ask only what the examples don't already answer, in one message:

• Trigger: the words the user says, or the event (before a commit, at session start, after a reply).
• Input and output: what it reads, what it writes or shows, where.
• What must never happen (the failure that would hurt most), and what to do on error.
• What is personal (names, emails, hosts, paths, tokens, brands, dates). Each becomes a setting or a question the setup asks, never a value in the files.

4. Scaffold

Follow the layout of the kit it may go to (claude-code-kit shown):

• Skill: SKILL.md with name and a description that says what it does AND the phrases that should trigger it. Scripts beside it, referred to as "this skill's base directory" ($SK), never by an absolute path.
• Hook: reads the event JSON on stdin with jq; denies with {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "<what to do instead>"}}; prints nothing and exits 0 otherwise. Fast (it runs on every event), and silent on its own errors (2>/dev/null || true in the settings) so it never blocks the user. The settings fragment uses __HOME__ for the home folder.
• Setup: when it needs configuration, setup.sh in the part (hooks: hooks/setup/<name>.sh), sourcing hooks/lib/ask.sh: reply KEY PROMPT [DEFAULT] and ask KEY PROMPT [y|n], each with a default, so the install test can run it unattended. Explain in two lines what the question is for before asking it.
• Catalog: an entry in parts.json: what, why, when, who in one short sentence each, its group, and needs, tools, os, setup, sync when they apply. The installer shows those four lines to whoever installs it.
• README: one row in the right table.

5. Test

• A test script in tests/ with real cases: the ones that must pass, the ones that must be refused, and an edge case or two (paths with spaces, no git remote, an empty config). Hooks: pipe JSON into the script and check its output. Mods: claude plugin test <mod>, on the latest Claude Code and on the oldest the kit supports (OLDEST_CLAUDE in the kit's tests workflow: npx -y @anthropic-ai/claude-code@<version> plugin test <mod>).
• A mod with a pane follows the kit's Rules for mods (CONTRIBUTING.md): folded by default, always grouped (even a lone group), a click on a folded line's text unfolds it unless that part has its own action, long text wraps instead of being cut, and each row fits on one line. Anything a newer build brings gets a fallback for the older ones.
• tests/install-sandbox.sh --auto: installs everything in a throwaway home folder and checks paths, settings and setups. 0 problems before going further.
• Use it for real on the user's machine once, and show the result.

6. Cross-platform checklist

Everything must work on macOS (bash 3.2, BSD tools), Linux (GNU tools) and Windows (Git Bash, native jq.exe, git.exe):

• No sed -i, sed -E with GNU-only escapes, grep -P, readlink -f, date -d, stat -c, timeout, mapfile, associative arrays (bash 3.2). Use awk, jq, POSIX options, or a checked fallback.
• Paths: quote every one (spaces), $HOME not ~ inside quotes, cygpath -m (kit_path) before handing a path to a Windows program (git config, jq, Claude Code settings). No /proc/self/fd (<(...) given to jq.exe), no hard-coded tool locations.
• Source hooks/lib/jq.sh: it handles jq.exe's CRLF and slow mise shims.
• LF line endings, executable bit set (git update-index --chmod=+x when committing from Windows).
• Machine-only things behind a platform check (uname -s: Darwin, Linux, MINGW*/MSYS*).

7. Share it

Ask once, when it works: "Publish a generic copy to <kit>?". On yes:

1. Pull the kit (git pull --ff-only), copy the part, and replace whatever is personal (step 3) by a setting or a setup question. Search the copy for the user's name, emails, hosts, home path and company names before going on.
2. Run the tests and the install sandbox; show the user the diff.
3. Commit with the email the user uses for that host, and push only on their yes. A kit with a team mirror (see the kit's README): push the part there too, on its own yes.