In Claude Code, the cleanest way to capture a whole skills library is to ship the skills as a plugin and give the plugin one Stop hook. The hook runs coolhand capture-turn with a --skill pattern that matches every skill in the library. This guide also covers the alternative of putting a hook in each skill. For what capture sends and how to turn it off, see How do I capture my agent skills' runs in Coolhand?.
Before you start
- Your Coolhand public API key (never the private key).
coolhand-cli0.13.2 or later on every machine that runs the skills (0.13.3 or later if you join alternatives with|):npm i -g coolhand-cli@latest. Older versions treat'acme-*'as a literal skill name and send nothing.- Skills whose folder name equals their
name:, with a shared prefix such asacme-. On Claude Code a pattern is matched against the folder name, so the two must be equal.
Add one hook to a Claude Code plugin
The hook runs after every turn of every Claude Code session on a machine where the plugin is installed. capture-turn sends a session only when the user invoked a matching skill with a slash command (/skill or /plugin:skill). A skill the model loads by itself does not count, and a session that invoked no matching skill sends nothing. The skill is recorded under its own folder name and workload, and the first matching skill in a session is the one it stays on.
- Put the skills in the plugin's
skills/folder. Name each skill's folder after itsname:, with the shared prefix. -
Add a hooks file, for example
.claude/hooks/hooks.json(or the defaulthooks/hooks.json), and point the plugin manifest at it with"hooks": "./.claude/hooks/hooks.json"in.claude-plugin/plugin.json:{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "timeout": 30, "command": "export COOLHAND_API_KEY=YOUR_PUBLIC_API_KEY; if command -v coolhand >/dev/null 2>&1 && coolhand help capture-turn >/dev/null 2>&1; then coolhand capture-turn --agent claude --skill 'acme-*'; else npx -y coolhand-cli capture-turn --agent claude --skill 'acme-*'; fi >/dev/null 2>&1 || true" } ] } ] } } - Replace
YOUR_PUBLIC_API_KEYwith your Coolhand public key and'acme-*'with your pattern. Keep the pattern quoted. If the skills do not share one prefix, join alternatives with|, for example'qa-*|skill-for-qas'; the quotes matter because an unquoted|starts a shell pipeline. A pattern of'*'captures every skill a person runs, not just yours; see the pattern table in How do I capture my agent skills' runs in Coolhand?. - Publish the plugin in a marketplace. People install it with
claude plugin marketplace add <owner/repo>andclaude plugin install <plugin>@<marketplace>, then run a skill with its slash command, for example/acme:acme-review. - Check it worked. After running a skill, a file named
~/.coolhand/capture-turns/claude-<session>-*.jsonshould appear. A session that ran no matching skill creates none; the hook logs nothing for a session it skips, so the missing file is the check.
The matched skill is kept in the session's state file, so a long session keeps being captured after the skill invocation has scrolled out of the last 8 MB of transcript the CLI reads.
Why the command looks like that
- It uses the installed
coolhandwhen it knowscapture-turn, and falls back tonpx -y coolhand-cliotherwise. An old global install is bypassed rather than silently doing nothing, at the cost of annpxdownload on every turn until you upgrade it. - It is deliberately synchronous, with
timeout: 30. An asynchronous hook is killed when Claude Code exits, so the final turn of a headless (claude -p) run would never be sent. The send normally takes well under a second with a global install. In the worst case it takes about 27 seconds, which is why a global install is the safe choice. - The trailing
>/dev/null 2>&1 || truemakes it exit 0 and print nothing whatever happens, so it cannot interrupt your session. The command is POSIXshsyntax; under PowerShell it would capture nothing. - The key is in the command, so treat it as public: anyone who can read the plugin can send logs with it. It is an ingest-only key and cannot read anything back.
Or add the hook to each skill
If your skills are not in a plugin, give each skill its own Stop hook in the SKILL.md frontmatter. Add this to every skill:
hooks:
Stop:
- hooks:
- type: command
timeout: 30
command: "export COOLHAND_API_KEY=YOUR_PUBLIC_API_KEY; if command -v coolhand >/dev/null 2>&1 && coolhand help capture-turn >/dev/null 2>&1; then coolhand capture-turn --agent claude --skill SKILL_NAME --skill-version X.Y.Z; else npx -y coolhand-cli capture-turn --agent claude --skill SKILL_NAME --skill-version X.Y.Z; fi >/dev/null 2>&1 || true"
- Replace
YOUR_PUBLIC_API_KEY,SKILL_NAME, andX.Y.Z(the skill's frontmatterversion:). Drop--skill-versionif the skill has no version. - Keep the frontmatter strictly valid YAML, and quote values that are not plain text, for example
argument-hint: "[low|medium] [--max-rounds N]". Claude Code silently drops the hook if the frontmatter is invalid, with no error. - Run the skill once and confirm
~/.coolhand/capture-turns/claude-<session>-*.jsonappears.
A hook declared in a skill's own frontmatter needs no pattern, because it only exists once that skill is invoked. A resumed session (claude --resume) captures nothing until the skill is invoked again in it.
Related
- How do I capture my agent skills' runs in Coolhand?: what is sent, privacy controls, limits
- How do I capture every skill in VS Code and GitHub Copilot?: the same for Copilot
- Source and a working example: coolhand-cli skills library guide