How to package expertise into folders Claude discovers and uses on its own — progressive disclosure, auto-invocation, and the frontmatter that controls it all.
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.
You never say a skill's name. You describe what you want — Claude does the matching.
| 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 |
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…
description: Helps with documents
No trigger terms. Nothing a user says will ever map to this.
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.
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.
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.
Anyone can fire it. Right for most skills — code review, research, formatting.
Only you, via /name. For side effects — /deploy, /commit. You don't want Claude deploying because the code "looks ready."
Hidden from the / menu. For background knowledge — a brand-voice guide helps Claude write, but means nothing as a command.
allowed-tools runs listed tools without permission prompts; disallowed-tools removes tools entirely while the skill is active.
model: opus and effort: high override per skill — heavyweight skills get heavyweight reasoning, cheap ones stay cheap.
paths: src/api/**/*.ts limits auto-activation to matching files — the API skill stays quiet while you edit docs.
A hooks: block runs only during this skill's lifecycle — e.g. validate every Bash call the skill makes, and nothing else.
--- 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…
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/ ├── SKILL.md # L2 ├── templates/ # L3 │ ├── review-checklist.md │ └── finding-template.md └── scripts/ # L3 ├── analyze-metrics.py └── compare-complexity.py
| /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 |
Ask "what skills are available?", filter the /skills menu, then test by asking something matching the description and by direct /name.
Skill(deploy *) in deny rules blocks one skill; a bare Skill deny disables them all. Allowlists work the same way.
skillOverrides: on (project may shadow user) · off (user always wins) · name-only · user-invocable-only.
disableSkillShellExecution: true turns every !`cmd` into literal text — for locked-down CI and shared enterprise machines.
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.