A skill is a folder of instructions that Claude Code loads only when a request matches its description. This page covers what a skill is and when to write one, how progressive disclosure keeps unused skills from costing context, and the SKILL.md file format.
What a skill is
An agent skill is a folder of instructions, plus optional resources, that teaches Claude Code how to handle one kind of task. Its required SKILL.md starts with frontmatter holding a name and a description, followed by the instructions.1
How a skill gets used
At startup Claude Code scans the skill locations but loads only names and descriptions. It compares each request with those descriptions by meaning, not by an exact command string, and loads a matching skill on demand. The description is therefore both discovery metadata and the main trigger. How the rest of the skill stays out of context until needed is covered under Progressive disclosure.
After adding, editing, or removing a skill, restart Claude Code before testing, and test with several realistic phrasings rather than the words copied from the description.1
When a skill is the right tool
Good candidates are repeated, task-specific procedures: code-review checklists, commit formats, brand guidance, documentation templates, framework-specific debugging. Having to explain the same task repeatedly is the course’s signal that a skill may be worthwhile.1 Rules that always apply belong in CLAUDE.md instead; see Claude Code extension mechanisms.
Where skills live and who wins a name clash
| Scope | Location | Use |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | Preferences and workflows across projects |
| Project | .claude/skills/<skill-name>/SKILL.md | Repository standards shared through version control |
When two skills share a name, precedence is enterprise managed, then personal, then project, then plugin. Specific names such as frontend-review avoid clashes better than review.1
Sharing
| Audience | Method |
|---|---|
| One repository or team | Commit .claude/skills to Git |
| Several repositories or the community | Package as a plugin in a marketplace |
| Whole organization | Enterprise managed settings (highest priority) |
Sharing methods as described in the course.1
Skills are not limited to Claude Code: an agent in Claude Managed Agents bundles skills alongside its model, system prompt, tools, and MCP servers.2
In Claude Code GitHub Actions, repository skills need actions/checkout so .claude/skills/ exists on the runner, and plugin skills must be installed through plugin_marketplaces and plugins first.3
Skills are files
Because a skill is a plain file, it can be versioned, shared, and even edited by another agent: Warp’s self-improving skill loop has a scheduled agent propose edits to a skill through pull requests.4 In a sales rollout, a top performer’s routine written once as a skill can be provisioned into the team bundle, and updating the file updates it for everyone.5 The AI-native SDLC playbook puts organization-wide policy in skills rather than in an ever-growing repository CLAUDE.md.6
Troubleshooting
Run the Agent Skills validator first to rule out structural problems, then match the symptom:1
| Symptom | Likely cause | First fix |
|---|---|---|
| Does not trigger | Description does not overlap real requests | Add phrases users actually say |
| Does not load | Wrong directory, filename, or YAML | Put SKILL.md in a named skill directory; inspect claude --debug |
| Wrong skill activates | Descriptions too similar | Make scope and trigger language distinct |
| Personal skill ignored | Higher-priority skill has the same name | Check precedence; rename |
| Plugin skill absent | Cache, install, or plugin structure | Validate, clear cache, restart, reinstall |
| Runtime failure | Missing dependency, permission, bad path | Install requirements, chmod +x scripts, use forward slashes |
Progressive disclosure
Progressive disclosure means showing the model a cheap summary first and loading detail only once the task justifies it. For agent skills, discovery costs only a name and description; the full SKILL.md, and then any references or scripts, enter context later.1
flowchart TD accTitle: Skill discovery and loading accDescr: Claude sees only skill names and descriptions, matches the request against them, loads the chosen SKILL.md, and then reads a reference or runs a script only if the task needs one. B[Names and descriptions] --> M{Request matches?} M -->|No| N[Continue without the skill] M -->|Yes| S[Load SKILL.md] S --> R{More needed?} R -->|Detail| D[Read one reference file] R -->|Operation| X[Run a provided script] R -->|No| W[Follow the core workflow]
Each step down the chart costs more context, and each is taken only when the step above says so.
Applying it to a skill
- Keep the essential workflow in
SKILL.md; the course recommends under 500 lines. - Move conditional detail to
references/,scripts/, orassets/, and say inSKILL.mdwhen to read or run each. - Prefer scripts for operations: Claude runs a tested script and only its output enters context, not its source.1
Skill configuration
An agent skill is a directory named after the skill containing SKILL.md: YAML frontmatter, then the instructions Claude follows once the skill is loaded.1
Fields
| Field | Required | Guidance |
|---|---|---|
name | Yes | Lowercase letters, numbers, hyphens; at most 64 characters; same as the directory name |
description | Yes | At most 1,024 characters; what the skill does and when to use it, in words users actually say |
allowed-tools | No | Restricts tools for read-only or sensitive workflows (see Least-privilege tool access) |
model | No | Selects a model for the skill |
name identifies the skill, description decides when it matches, and the body says what to do.1
Layout
my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/Why the supporting folders exist is explained under Progressive disclosure.
Example
---
name: pr-description
description: Writes pull request descriptions. Use when creating or summarizing a pull request.
---
When writing a PR description:
1. Inspect the complete branch diff.
2. Explain what changed and why.
3. List the concrete changes and any renamed or deleted files.Related
- Subagents: subagents do not inherit skills.
- Context isolation saves context by moving work elsewhere; progressive disclosure saves it by not loading material until needed. (Analysis: this link is the wiki’s own comparison, not a claim from either source.)
- Subagent configuration file: the parallel format for subagents, which can list skills to preload.