Claude Skills Guide

TL;DR

Claude Skills are small instruction packs that change Claude Code's behavior for a specific task. Activate one (/caveman, etc.) and Claude follows that skill's role/style/workflow until further notice. One file, one command, instant effect.

This guide covers three things: installing existing skill collections, the most-used built-ins and when to pick them, and writing your own.

Installing a skill collection

The fastest way is the skills CLI. Matt Pocock's popular collection:

npx skills@latest add mattpocock/skills

That copies skills under ~/.claude/skills/. Restart Claude Code; the slash-command list now lists them — invoke with /<skill-name>.

List installed skills:

ls ~/.claude/skills/

Always read a skill's SKILL.md before using it — know what behavior change you're activating.

The most-used skills

/caveman — compact response mode

Compresses output ~75%. Drops articles, pleasantries, hedge words; preserves technical substance.

When: long technical conversations to save tokens, fast iteration, debugging. When not: preparing a final document for an audience — tone gets too telegraphic.

/grill-me — plan-grilling mode

Puts Claude into "aggressive interviewer" mode for a design or plan. Every assumption, edge case, and alternative is challenged. As you answer, the decision tree gets explored systematically.

When: discussing architecture, product spec, system design. When not: during execution of an already-decided task — it's just friction.

/init — bootstrap a CLAUDE.md

Run /init in a new repo. Claude scans the project, infers language/framework, and proposes a meaningful CLAUDE.md draft. You edit and add it.

When: first time using Claude Code on a new repository.

/review — structured code review

Produces "Critical / Suggestion / Style" sectioned feedback for a PR or branch. Consistent across team reviewers.

When: code review loop, PR template generation.

/security-review — security-focused review

Scans pending changes from a security lens: SQL injection, XSS, auth slip-ups, env-var leaks, dependency CVEs.

When: the gate just before deploying to production.

/simplify — quality/dedup/efficiency pass

Reviews freshly written code for: existing equivalents, quality issues, performance optimizations.

When: cleaning up your own code before opening a PR.

/find-skills — search the skill catalog

Browses installed skills and recommends relevant ones for a stated need.

How skills actually work

A skill is essentially a markdown file:

~/.claude/skills/<skill-name>/
└── SKILL.md

SKILL.md has YAML frontmatter on top, behavior rules in the body. Claude prepends the content as context and continues the conversation under it.

Frontmatter:

---
name: caveman
description: Ultra-compressed communication mode. Cuts token usage ~75%.
trigger: /caveman
---

The body is freeform markdown — rules, examples, scope. Most skills are 30–100 lines: specific enough to do real work, short enough not to drown the prompt.

Writing your own skill

Say you want to standardize PR descriptions across your team:

mkdir -p ~/.claude/skills/pr-description
$EDITOR ~/.claude/skills/pr-description/SKILL.md

Content:

---
name: pr-description
description: Produces a standardized, bilingual PR description.
trigger: /pr-description
---

# Generate a PR description

Produce a GitHub PR description for the pending changes.

## Sections

1. **Summary (1 sentence)** — what this change does.
2. **Why (2-3 sentences)** — why it's needed, what problem it solves.
3. **Changes (bullets)** — concrete edits.
4. **Testing (bullets)** — how to verify.

## Rules

- Bilingual: English first, Turkish below.
- Explain WHY, not WHAT.
- Under 200 words.
- If a related issue exists, add "Closes #123".

## Example

> ### Summary
> Add Stripe webhook signature verification.
>
> ### Why
> Webhooks were trusted blindly — any attacker could POST a fake event.
>
> ### Changes
> - Add `verifyStripeSignature` middleware
> - Apply to `/webhooks/stripe`
> - Throw 400 on signature mismatch
>
> ### Testing
> - [ ] Valid event with curl → 200
> - [ ] Tampered payload → 400
> - [ ] Replay → 400
>
> Closes #842

Restart Claude Code; /pr-description is in the menu. After a few useful skills, share via Git — a team-wide ~/.claude/skills/ or a project's claude/skills/.

Common pitfalls

Conflicting skills

caveman + grill-me clash: "be terse" vs "interrogate everything". Make sure stacked skills are compatible; add an "if other skills are active, defer" clause if needed.

Bloated skills

A 500-line skill leaves no room for the rest of the prompt. Keep skills under 100 lines — for bigger workflows use a subagent, not a skill.

Risky commands

A skill might say "run this shell command". Always read SKILL.md from foreign sources before installing. Without a sandbox, malicious instructions can sneak through.

Versioning

Update SKILL.md and you may need to restart Claude Code. Tracking skills in Git makes change history clear and team sharing easier.

Advanced patterns

Conditional behavior

Use trigger arguments for variants:

## Activation

- `/pr-description` — default: bilingual, full
- `/pr-description short` — English only, 5 lines
- `/pr-description tr` — Turkish only

Claude reads the argument and adjusts.

Auxiliary files

A skill can include more than SKILL.md. Templates, checklists, configs:

~/.claude/skills/new-react-component/
├── SKILL.md
├── template.tsx
└── README.md

In SKILL.md, instruct "read template.tsx and adapt it for the requested name".

Hooks for automatic triggers

To run a skill after every commit, every error, or every meeting summary, use the harness's hooks mechanism. Skills are manual; hooks are automatic.

Next steps

• Browse community collections: awesome-claude-skills repos
• Set up a team skill repo: distribute shared workflows
• Combine skills with MCP servers: skill defines behavior, MCP performs the action

Continue reading

• MCP Server Catalog — the other half of the same ecosystem.
• System Prompt Guide — skills are essentially specialized system prompts; ten persona examples there.
• MCP — skill defines behavior, MCP performs the action; how the two compose.
• System Prompt — the underlying concept.