Skills — User-Invocable Workflows

~/.claude/skills/review/
├── SKILL.md             # frontmatter + instructions
├── checklist.md         # referenced template (optional)
└── examples/
    └── good-review.md   # auxiliary file (optional)

---
name: review
description: Review a pull request — diff, concerns, verdict
model: opus
allowed-tools: [Bash, Read, Grep, Glob, WebFetch]
---

---
name: security-review
description: Complete a security review of the pending changes on the current branch
model: opus                  # optional override
allowed-tools: [Bash, Read, Grep, Glob]
---

---
name: security-review
description: Complete a security review of the pending changes on the current branch
model: opus
allowed-tools: [Bash, Read, Grep, Glob]
---

Run a security pass over the diff between the current branch and `main`.

Steps:
1. Run `git diff main...HEAD` and read the full diff.
2. For each modified file, run Grep for these patterns:
   - `eval(`, `Function(`, `child_process.exec`
   - `dangerouslySetInnerHTML`
   - `process.env.*` without validation
   - SQL constructed by string concatenation
3. Read any files where matches appear and assess.

Produce a report with:
- One-line verdict: pass / concerns / blocked.
- Per-finding: file + line + the risk + the suggested fix.
- A summary of patterns that did not appear (negative findings).

Do not modify any files. Do not commit.

---
name: init
description: Initialize a new CLAUDE.md file with codebase documentation
---

You are creating a CLAUDE.md for the current repository.

Steps:
1. List the top-level files and directories. Read package.json (or pyproject.toml, Cargo.toml, etc.).
2. Identify the build system, the test runner, the linter.
3. Look for unusual conventions in scripts/, config files, or .github/workflows/.
4. Draft a CLAUDE.md with sections:
   - Commands
   - Architecture (only things not obvious from the file tree)
   - Conventions
   - Gotchas (only if any genuine ones surface)

Style:
- Concise. Each section under 200 lines.
- No emojis.
- The reader is a competent engineer new to the repo.

Write the file to ./CLAUDE.md only after the user has reviewed the draft.

---
name: fewer-permission-prompts
description: Scan transcripts and add a prioritized allowlist to settings.json
allowed-tools: [Bash, Read, Edit]
---

Run the bundled scanner to find common Bash commands across recent transcripts:

```bash
bash ~/.claude/skills/fewer-permission-prompts/scan.sh

The script does the heavy data work; the skill body does the human-facing reasoning and the edit proposal.

### Intent matching in action

The user types: "set up a recurring task to check the deploy every 5 minutes". The harness sees the `schedule` skill ("Create, update, list, or run scheduled remote agents") and the `loop` skill ("Run a prompt or slash command on a recurring interval"). Both might fit; the harness picks the closer match — likely `loop` for the in-session case, `schedule` for the cron case — or asks.

## Gotchas

- **Descriptions are how skills get found.** A skill with a vague description never gets auto-invoked. Write the description as if a stranger had to decide whether it applies.
- **Two overlapping descriptions cause friction.** The harness has to disambiguate, which means more prompts to the user. Curate the skill set so each description is distinct.
- **Skills run inline — no context isolation.** A skill that reads a hundred files dumps a hundred files into the parent's context. For isolated work, use a sub-agent instead.
- **`allowed-tools` is enforced.** A skill cannot call tools outside its allowlist even if the body asks. This is a feature for safety; an inconvenience if the allowlist is too tight.
- **Skill bodies are still prompts.** Anything in the body is text the model reads. Hostile or malformed content in a skill body could mislead the model. Audit committed skills the same way you audit committed code.
- **Project skills travel with the repo.** Every contributor gets every project skill. Coordinate before merging a new one.
- **A skill is not a substitute for a slash command for muscle-memory cases.** If you type `/review` ten times a day, the slash is still the right entry point — wire the slash to invoke the skill if you want both surfaces.
- **No interactive prompts.** Like slash commands, skills cannot stop and ask. Design for "make the sensible call, surface the rationale" instead of "stop and ask".

<Callout type="info" title="When the harness suggests a skill, the description did the work">
  The moment a user types "review this PR" and Claude Code says "I'll use the review skill" — that handoff is the description doing its job. A well-written description is the single highest-leverage line in the entire skill file. Spend more time on it than on the body; the body only runs if the description matches.
</Callout>

### Skill vs slash vs sub-agent at a glance

<Compare>
  <div slot="left">
    <strong>Skill</strong>
    <ul>
      <li>Invoked by name or by intent</li>
      <li>Runs inline in the parent session</li>
      <li>Tool allowlist via <code>allowed-tools</code></li>
      <li>Description is the matcher</li>
      <li>A directory with markdown + optional scripts</li>
    </ul>
  </div>
  <div slot="right">
    <strong>Slash command / Sub-agent</strong>
    <ul>
      <li>Slash: invoked by typed name only</li>
      <li>Sub-agent: invoked via the Task tool, runs in isolated context</li>
      <li>Slash: a single markdown file; Sub-agent: a directory with config</li>
      <li>Slash is a typed shortcut; sub-agent is an isolated worker</li>
      <li>Skill sits between: discoverable like slash, structured like sub-agent</li>
    </ul>
  </div>
</Compare>

## Related features

- [Slash Commands](/claude-code/slash-commands)
- [Sub-Agents](/claude-code/sub-agents)
- [Writing Custom Slash Commands](/claude-code/writing-custom-slash-commands)
- [Custom Sub-Agents](/claude-code/custom-sub-agents)
- [Settings and Configuration](/claude-code/settings-and-configuration)

<Spoiler summary="The matcher quality determines whether a skill earns its place">
  An unused skill is worse than no skill — it bloats the description list the harness has to consider on every request. The test for whether a skill is paying its rent is simple: over the last week, has the harness invoked it without an explicit user request? If yes, the description is doing real work and the skill belongs. If not, either the description is wrong or the skill should be a slash command instead. Prune ruthlessly; a tight set of five well-described skills beats fifteen mediocre ones.
</Spoiler>