---
title: "How do I capture every skill in a Claude Code plugin?"
answer: "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."
category: "Coding agents"
tags: ["coolhand-cli","capture","hooks","skills","claude-code"]
published: 2026-11-04T18:34:53Z
updated: 2026-11-08T15:23:04Z
canonical_url: https://coolhandlabs.com/help/capture-every-skill-in-a-claude-code-plugin
index_url: https://coolhandlabs.com/help.md
---

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

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?](https://coolhandlabs.com/help/capture-agent-skill-runs-with-coolhand-cli.md).

## 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`:

   ```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?](https://coolhandlabs.com/help/capture-agent-skill-runs-with-coolhand-cli.md).
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:

```yaml
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

- [How do I capture my agent skills' runs in Coolhand?](https://coolhandlabs.com/help/capture-agent-skill-runs-with-coolhand-cli.md): what is sent, privacy controls, limits
- [How do I capture every skill in VS Code and GitHub Copilot?](https://coolhandlabs.com/help/capture-every-skill-in-vs-code-github-copilot.md): the same for Copilot
- Source and a working example: [coolhand-cli skills library guide](https://github.com/Coolhand-Labs/coolhand-cli/blob/main/docs/hook-capture-skills-library.md#add-the-hook-to-every-skill-in-a-claude-code-plugin)


---

Related:
- [How do I capture my agent skills' runs in Coolhand?](https://coolhandlabs.com/help/capture-agent-skill-runs-with-coolhand-cli.md)
- [How do I capture every skill in VS Code and GitHub Copilot?](https://coolhandlabs.com/help/capture-every-skill-in-vs-code-github-copilot.md)
- [Claude Code best practices](https://coolhandlabs.com/help/claude-code-best-practices.md)
- [Claude Cowork best practices](https://coolhandlabs.com/help/claude-cowork-best-practices.md)

[← All help articles](https://coolhandlabs.com/help.md) · [Coding agents](https://coolhandlabs.com/help/category/coding-agents.md)
