Agent Skills in Claude Code
How to package expertise into folders Claude discovers and uses on its own — progressive disclosure, auto-invocation, and the frontmatter that controls it all.
You keep re-teaching Claude the same things — skills end that
Every chat starts from zero. So you paste the review checklist again, explain the API conventions again, describe the deploy steps again. A prompt lives and dies with one conversation. A skill moves that expertise into the filesystem — written once, versioned in git, and applied automatically whenever the task matches.
That's the definition: a skill is a folder with a SKILL.md inside — instructions, plus any templates and scripts they need. Claude reads the folder, you stop repeating yourself.
A skill costs ~100 tokens until the moment it's needed
From your sentence to a finished result in five beats
You never say a skill's name. You describe what you want — Claude does the matching.
Where a skill lives decides who gets it — and who wins a name clash
| Enterprise | Managed settings — pushed to every user in the org |
| ~/.claude/skills/ | Personal — follows you across all projects, never shared |
| .claude/skills/ | Project — commit to git, the whole team has it on next pull |
| <plugin>/skills/ | Plugin — namespaced plugin:skill, can never collide |
- Same name at multiple levels → enterprise beats personal beats project (tunable via skillOverrides)
- Monorepos: editing in packages/frontend/ auto-discovers that package's own .claude/skills/
- /reload-skills re-scans everything without restarting the session
SKILL.md is frontmatter plus instructions — two fields are required
my-skill/ ├── SKILL.md # required — keep under 500 lines ├── templates/ # Level 3 — loaded as needed ├── examples/ └── scripts/ --- name: code-review-specialist # lowercase + hyphens, max 64 chars description: Comprehensive code review with security and performance analysis. Use when users ask to review code, evaluate PRs, or mention security analysis. --- # instructions follow as plain Markdown…
The description is the trigger — write it like a matching rule
Vague — never fires
description: Helps with documents
No trigger terms. Nothing a user says will ever map to this.
Specific — fires reliably
description: Extract text and tables
from PDF files, fill forms, merge
documents. Use when working with
PDFs, forms, or document extraction.
What it does and when to use it — in the words users actually say.
Every skill is either knowledge Claude applies or a task Claude runs
Reference — knowledge
name: api-conventions --- When writing API endpoints: - RESTful naming conventions - Consistent error formats - Request validation
Conventions, patterns, style guides. Runs inline with your conversation — it shapes work already in flight.
Task — action
name: deploy context: fork disable-model-invocation: true --- 1. Run the test suite 2. Build the application 3. Push to the deployment target
Step-by-step procedures. Usually invoked directly as /deploy — a workflow with a beginning and an end.
Two flags split skills into three invocation modes
Default
Anyone can fire it. Right for most skills — code review, research, formatting.
disable-model-invocation
Only you, via /name. For side effects — /deploy, /commit. You don't want Claude deploying because the code "looks ready."
user-invocable: false
Hidden from the / menu. For background knowledge — a brand-voice guide helps Claude write, but means nothing as a command.
Four frontmatter fields do the heavy lifting beyond the basics
1Tool scoping
allowed-tools runs listed tools without permission prompts; disallowed-tools removes tools entirely while the skill is active.
2Model & effort
model: opus and effort: high override per skill — heavyweight skills get heavyweight reasoning, cheap ones stay cheap.
3Path activation
paths: src/api/**/*.ts limits auto-activation to matching files — the API skill stays quiet while you edit docs.
4Skill-scoped hooks
A hooks: block runs only during this skill's lifecycle — e.g. validate every Bash call the skill makes, and nothing else.
$ARGUMENTS and !`command` make a skill live, not canned
--- name: pr-summary description: Summarize changes in a pull request --- ## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` ## Your task Summarize pull request $ARGUMENTS…
- $ARGUMENTS carries your input; $0, $1 address pieces individually
- !`command` runs before Claude reads the prompt — real diff, real comments, not a guess
- ${CLAUDE_SKILL_DIR} locates bundled scripts; ${CLAUDE_EFFORT} lets behavior branch by effort level
context: fork hands the skill to a subagent and keeps your window clean
The skill content becomes the task for a dedicated subagent — it forks off your conversation, grinds through the work in its own context window, and only the result comes back. Twenty files of research stop flooding your main session.
| agent: Explore | Read-only research and codebase analysis |
| agent: Plan | Creating implementation plans |
| agent: general-purpose | Broad tasks that need all tools |
| agent: <custom> | Any specialized agent defined in your configuration |
code-review-specialist shows all three levels in one skill
code-review-specialist/ ├── SKILL.md # L2 ├── templates/ # L3 │ ├── review-checklist.md │ └── finding-template.md └── scripts/ # L3 ├── analyze-metrics.py └── compare-complexity.py
- Description names its triggers: "review code, evaluate pull requests, security analysis"
- Body defines four review lenses — security, performance, quality, maintainability — and a findings template
- Scripts compute complexity metrics via bash; their code never enters context
Nine skills ship built-in — no install needed
| /code-review | Review the current diff at a chosen effort level |
| /verify | Build, run, and observe the app to confirm a fix actually works |
| /run | Launch this project's app to see a change running |
| /batch | Orchestrate large parallel changes using git worktrees |
| /loop | Run a prompt repeatedly on an interval |
| /debug | Troubleshoot the current session from its debug log |
| /claude-api | Load Claude API/SDK reference on demand |
| /fewer-permission-prompts | Propose an allowlist from your transcript history |
| /run-skill-generator | Teach /run and /verify how to handle this project |
You stay in charge of what fires, what overrides, and what runs shell
1Test both routes
Ask "what skills are available?", filter the /skills menu, then test by asking something matching the description and by direct /name.
2Permission rules
Skill(deploy *) in deny rules blocks one skill; a bare Skill deny disables them all. Allowlists work the same way.
3Override policy
skillOverrides: on (project may shadow user) · off (user always wins) · name-only · user-invocable-only.
4Shell kill switch
disableSkillShellExecution: true turns every !`cmd` into literal text — for locked-down CI and shared enterprise machines.
One skill, one capability — and the description does the selling
Do
- Keep skills focused — "PDF form filling", not "document processing"
- Put trigger terms users actually say in the description
- Keep SKILL.md under 500 lines; push detail to Level 3 files
- Package the scripts and templates the skill depends on
- Test with real scenarios before relying on auto-fire
Don't
- Build skills for one-time tasks
- Duplicate what an existing skill already does
- Skip the description field — it's the trigger
- Make one mega-skill that does everything
- Install from untrusted sources without reading every file
Write the description first — the rest is just Markdown
A skill is a folder with a SKILL.md: progressive disclosure keeps dozens installed at ~100 tokens each, the description decides when it auto-fires, two flags split action skills (user-only) from knowledge skills (model-only), and context: fork sends heavy work to a subagent. Memory (ch. 2) is what Claude always knows; skills are what Claude can do when asked — or when it notices.