Claude Agent Skills

Instead of repeating instructions every time you ask Claude to review a PR or write a commit message, you write a skill once and Claude applies it whenever the task comes up.

What a Skill Is

A skill is a SKILL.md file with name and description in its frontmatter, plus instructions in the body. Claude matches your request against every available skill’s description and activates the ones that fit.

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---
 
Check for: missing tests, unhandled errors, and inconsistent naming.

Claude Code also ships with its own skills — /code-review, /debug, /run, /loop and others — so you’re already using this system before writing a single one.

Where They Live

• Personal — ~/.claude/skills/<name>/SKILL.md — follows you across every project.
• Project — .claude/skills/<name>/SKILL.md — committed to the repo, shared with anyone who clones it.
• Plugins — bundled and distributed via marketplaces.

Priority on a name collision: Enterprise > Personal > Project > Plugins. Use specific names (frontend-review, not review) to avoid stepping on another skill.

Frontmatter Fields

allowed-tools grants, it doesn’t restrict. It’s easy to assume it sandboxes a skill to a tool list — it doesn’t. It pre-approves those tools so Claude skips the permission prompt; every other tool is still callable, and the grant clears on your next message. To actually take a tool away, use disallowed-tools: Edit, Write, Bash instead.

Skills vs. CLAUDE.md vs. Slash Commands

• CLAUDE.md loads into every conversation — always-on project rules.
• Skills load only when triggered — task-specific expertise Claude applies automatically.
• Slash commands require you to type them explicitly.

Creating One

mkdir -p ~/.claude/skills/pr-description
cd ~/.claude/skills/pr-description
touch SKILL.md

Write the frontmatter and instructions, then just ask for the task — no registration step. Edits and deletions apply live, within the same session; no restart needed. Run /skills any time to see what’s currently installed.

For anything beyond a trivial skill, skip the blank file: install Anthropic’s skill-creator plugin (/plugin install skill-creator@claude-plugins-official, then run /skill-creator). It scaffolds the SKILL.md, and can also eval, A/B-compare, and benchmark a skill’s trigger accuracy across runs — useful once you’re iterating on a description that isn’t firing reliably.

Progressive Disclosure

Keep SKILL.md under 500 lines. Push detail into files Claude only reads when it needs them:

my-skill/
├── SKILL.md       # overview — keep this short
├── reference.md   # detailed docs, loaded on demand
└── scripts/       # executable code — only its output loads into context, not the source

Security

Skills are instructions and code Claude will act on — treat installing one like installing software:

• Default to skills you wrote yourself or that came from Anthropic.
• Anything else — a plugin marketplace, a repo you don’t control — deserves a full read-through of SKILL.md and any bundled scripts first.
• Be wary of skills that fetch from external URLs; fetched content can carry its own instructions.

Troubleshooting

• Not triggering? Weak description — add phrases that match how you actually ask.
• Wrong skill firing? Descriptions are too similar — make them more distinct.
• Not loading? Check SKILL.md sits inside a named directory and is spelled exactly.
• Not sure what’s costing context or going unused? Run /skill-doctor.