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.1 The description is therefore both discovery metadata and the main trigger. How the rest of the skill stays out of context until needed is on 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) |
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 |
Related
- Source: The AI-Native SDLC Playbook
- Source: Building an AI-Native Revenue Organization
- Source: How Warp Builds Self-Improving Agents on Claude
- Source: Claude Code GitHub Actions
- Source: Claude Managed Agents
- Skill configuration: frontmatter fields and directory layout.
- Subagent: subagents do not inherit skills.
- Source: Introduction to Claude Code Agent Skills