Claude CodeSKILL.md
Writing Skills for Claude Code
How to author a SKILL.md that Claude Code will discover, load, and apply correctly.
Use when: User wants to author a new Claude Code skill, or is asking how SKILL.md files should be structured.
Prompt AgentExpert
April 23, 2026647442
Install this skill
Save this to your project or home directory so Claude Code can load it.
~/.claude/skills/writing-skills-for-claude-code/SKILL.mdSkill File
SKILL.md
# Writing Skills for Claude Code
A SKILL.md file teaches Claude Code a focused capability. Keep each skill narrow and composable — one intent per file.
## Structure
1. **Frontmatter** — `name`, `description`, `when-to-use`.
2. **Overview** — one paragraph explaining what the skill does.
3. **Instructions** — numbered steps Claude should follow.
4. **Examples** — concrete request/response pairs.
5. **Guardrails** — what Claude must *not* do.
## Rules for authoring
- Prefer verbs in the title ("Write a migration plan", not "Migrations").
- Make `when-to-use` match how a user phrases the request.
- Cap the body at ~2 KB. If it grows, split into multiple skills.
- Reference tools by name, not version, unless the version matters.
## Installation path
~/.claude/skills/<slug>/SKILL.md
Claude Code auto-discovers every `SKILL.md` under that directory.
Discussion