Skip to main content

How do I capture every skill in a Claude Code plugin?

Last updated 5 min read

Ship your skills as a Claude Code plugin and give it one Stop hook running `coolhand capture-turn --agent claude --skill 'acme-*'`. Every skill matching the pattern is then captured when a user invokes it with a slash command. It needs coolhand-cli 0.13.2 and your public API key.

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-cli 0.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 as acme-. 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.

  1. Put the skills in the plugin's skills/ folder. Name each skill's folder after its name:, with the shared prefix.
  2. Add a hooks file, for example .claude/hooks/hooks.json (or the default hooks/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"
              }
            ]
          }
        ]
      }
    }
    
  3. Replace YOUR_PUBLIC_API_KEY with 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?.
  4. Publish the plugin in a marketplace. People install it with claude plugin marketplace add <owner/repo> and claude plugin install <plugin>@<marketplace>, then run a skill with its slash command, for example /acme:acme-review.
  5. Check it worked. After running a skill, a file named ~/.coolhand/capture-turns/claude-<session>-*.json should 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 coolhand when it knows capture-turn, and falls back to npx -y coolhand-cli otherwise. An old global install is bypassed rather than silently doing nothing, at the cost of an npx download 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 || true makes it exit 0 and print nothing whatever happens, so it cannot interrupt your session. The command is POSIX sh syntax; 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"
  1. Replace YOUR_PUBLIC_API_KEY, SKILL_NAME, and X.Y.Z (the skill's frontmatter version:). Drop --skill-version if the skill has no version.
  2. 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.
  3. Run the skill once and confirm ~/.coolhand/capture-turns/claude-<session>-*.json appears.

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 articles