Anatomy of Skills

Reusable skills, playbooks, references, and how to structure them.

Skills

Reusable, auto-activating capability packs that make Claude predictable and powerful.

TL;DR

A Skill is a folder under skills/ containing instructions, scripts, references, and assets.
Claude auto-loads a skill when the user's intent matches its triggers.
One skill = one job, done well.
Skills make repeatable workflows deterministic and reviewable.

Why this matters

Skills are like kitchen mise en place — ingredients, tools, and recipes prepped before service. When the order comes in, you don't improvise; you execute.

Bottom line: Skills convert tribal knowledge into shippable AI behavior.

The Big Picture

Bottom line: Trigger → load → execute → audit.

Skill Anatomy

skills/code-review/
├── SKILL.md          # Instructions & triggers
├── scripts/
│   ├── analyze.sh    # Executable automation
│   └── report.sh     # Generates summary
├── references/
│   ├── style-guide.md
│   └── checklist.md  # Loaded on demand
└── assets/
    └── pr-template.md

Folder	Purpose
`SKILL.md`	The skill's brain — metadata, triggers, instructions
`scripts/`	Shell/Node/Python scripts the skill may run
`references/`	Long docs loaded on demand to save context
`assets/`	Static templates, diagrams, examples

`SKILL.md` Structure

---
name: code-review
description: Review code quality, security, and tests on PRs.
triggers: ["review", "audit", "pr", "quality"]
auto_activation: true
requires: [git, node, grep]
---

## When to activate
When the user asks to review, audit, or check a PR.

## What it does
1. Run `scripts/analyze.sh` to diff against `main`.
2. Check tests & coverage.
3. Report findings with file:line refs.

## Output format
- Summary
- Risks & issues
- Missing tests
- Suggestions (file:line)

## Notes
Follow project rules in CLAUDE.md.

Step-by-Step Setup

1. Scaffold the skill

mkdir -p skills/code-review/{scripts,references,assets}
touch skills/code-review/SKILL.md

2. Write `SKILL.md` (see template above)

3. Add an executable

cat > skills/code-review/scripts/analyze.sh <<'EOF'
#!/usr/bin/env bash
git fetch origin main
git diff origin/main --stat
EOF
chmod +x skills/code-review/scripts/analyze.sh

4. Add references (loaded on demand)

echo "# Style guide ..." > skills/code-review/references/style-guide.md

5. Test

Ask Claude: "Review my last PR." — the skill should auto-activate.

Variants for Different Team Settings

👤 Solo

One skill: code-review. That's enough.

👥 Small team

Add test-writer, docs-writer. Standardize triggers across the team.

🏢 Enterprise

Pin script versions and code-sign them.
Require review for any skill change.
Add an audit_log field to SKILL.md.

---
name: security-audit
audit_log: /var/log/claude/skills.log
---

🌍 Open-source

Ship skills inside the repo so forks inherit them.
Add a CONTRIBUTING-SKILLS.md with examples.

Bottom line: Same folder shape, escalating governance.

Trigger Examples

Phrases that activate code-review:

"review this PR"
"audit the code"
"check quality"
"any issues?"
"lint and review"

💡 Tip: Add synonyms people actually use in your team.

Popular Skills (examples)

Skill	Best for	Key tools	Outputs
`code-review`	PR reviews, quality gates	Read, Bash, Grep	Review report
`test-writer`	Unit & integration tests	Read, Bash, Edit	Tests + coverage
`docs-writer`	Docs, API references	Read, Edit	Markdown docs
`security-audit`	Vulnerabilities, secrets	Read, WebSearch	Risk report
`refactor`	Code cleanup & design	Read, Edit, Bash	Refactored code
`bug-triage`	Issue classification	Read, WebSearch	Triage summary

Common Patterns & Recipes

Pattern 1 — Multi-step skill

## What it does
Lint  → `scripts/lint.sh`
Test  → `scripts/test.sh`
Build → `scripts/build.sh`
Report combined results.

Pattern 2 — Reference-only skill (no scripts)

Use this for "always remind Claude of X" — references/ loaded conditionally.

Pattern 3 — Skill that calls a subagent

After analysis, delegate fixes to `@refactor` subagent.

Pattern 4 — Trigger with exclusions

triggers:
  include: ["review", "audit"]
  exclude: ["self-review"]

Best Practices ✅

One job per skill.
Clear triggers & description.
Keep SKILL.md concise (< 200 lines).
Scripts must be deterministic.
Reference CLAUDE.md instead of duplicating rules.
Version skills with the repo.

Anti-Patterns ❌

Mega-skill that does everything.
Vague trigger words ("help", "do").
Non-idempotent scripts.
Skills with hard-coded secrets.
No description → impossible auto-routing.

Troubleshooting

Symptom	Cause	Fix
Skill never activates	Trigger mismatch	Add synonyms
Wrong skill activates	Triggers too broad	Add `exclude` list
Script fails	Missing dependency	Add to `requires:`
Slow	Heavy script in hot path	Move work to subagent
Stale output	References outdated	Update + commit

Skill Skeleton (copy this)

---
name: my-skill
description: Do one thing really well.
triggers: ["mytask", "synonym"]
requires: [bash]
---

## When to activate
<conditions>

## What it does
1. Step one
2. Step two

## Output format
- ...

## Notes
Follow CLAUDE.md.

💡 Tip: Start tiny. Evolve as the skill proves valuable.

Glossary

Skill — A folder Claude auto-loads to handle a specific task.
Trigger — A keyword or phrase that activates a skill.
Auto-activation — Skill loads without explicit user invocation.
Reference — A long doc loaded on demand (saves context budget).
Asset — A static template, image, or example file.

TL;DR​

Why this matters​

The Big Picture​

Skill Anatomy​

SKILL.md Structure​

Step-by-Step Setup​

1. Scaffold the skill​

2. Write SKILL.md (see template above)​

3. Add an executable​

4. Add references (loaded on demand)​

5. Test​

Variants for Different Team Settings​

👤 Solo​

👥 Small team​

🏢 Enterprise​

🌍 Open-source​

Trigger Examples​

Popular Skills (examples)​

Common Patterns & Recipes​

Pattern 1 — Multi-step skill​

Pattern 2 — Reference-only skill (no scripts)​

Pattern 3 — Skill that calls a subagent​

Pattern 4 — Trigger with exclusions​

Best Practices ✅​

Anti-Patterns ❌​

Troubleshooting​

Skill Skeleton (copy this)​

Glossary​

Further Reading​