Claude Code Skills
Some tasks need detailed know-how: your company report format, a testing checklist, a migration recipe. Skills package that know-how into a folder that Claude Code loads only when a task calls for it. The assistant stays light during normal work and becomes an expert on demand.
The Recipe Book Idea
A kitchen shelf holds many cookbooks. A chef pulls out the pastry book for dessert and leaves the others closed. Skills behave like those cookbooks. Claude Code sees the title and a short description of each skill and opens the full instructions only when the task matches.
SKILL SHELF
├── pdf-report "Builds our standard PDF report"
├── db-migration "Steps for safe database changes"
└── release-notes "Writes release notes in our format"
Task: "Prepare release notes"
↓
Claude Code opens ONLY the release-notes skill
Anatomy of a Skill
A skill is a folder with one required file named SKILL.md. The folder can hold templates, scripts, and reference documents.
.claude/skills/release-notes/ ├── SKILL.md ├── template.md └── example.md
Project skills live in .claude/skills/. Personal skills live in ~/.claude/skills/ and follow you across projects.
Writing SKILL.md
The file starts with a short header. Two fields matter: a name and a description.
--- name: release-notes description: Writes release notes from recent commits in the company format. Use when asked for release notes or a changelog. --- # Release Notes 1. Read the commits since the last tag. 2. Group changes under Features, Fixes, and Improvements. 3. Follow the layout in template.md. 4. Keep every line under 100 characters.
The description acts as the trigger. Claude Code scans every description at the start of a session and loads the matching skill when your request fits.
How Loading Works
| Stage | What Claude Code Reads | Memory Cost |
|---|---|---|
| Session start | Name and description of each skill | Very small |
| Matching task | Full SKILL.md instructions | Moderate |
| Detailed step | Extra files such as templates | Only when needed |
Skills Compared With Other Tools
| Tool | Best For |
|---|---|
| CLAUDE.md | Short rules that apply to every task |
| Custom slash command | A saved prompt you trigger by name |
| Subagent | A helper with its own workspace |
| Skill | Detailed procedures with supporting files |
| Hook | Actions that must run every time |
Skill Ideas
- A code-review checklist tuned to your team.
- A framework guide with preferred patterns.
- A report generator with a fixed template.
- A deployment routine with safety steps.
Tips for Strong Skills
Write a Sharp Description
Name what the skill does and when to use it. Vague descriptions cause missed or wrong triggers.
Keep SKILL.md Short
Move long reference material into separate files that load on demand.
Include Examples
A sample of finished output shows the target faster than a paragraph of rules.
Review Shared Skills
Skills can include scripts. Read any skill from an outside source before you install it.
A Starter Skill Plan
Choose one task your team repeats every week. Write the steps in plain language inside SKILL.md. Add one example of a finished result. Test the skill with a real request and watch whether Claude Code loads it. Adjust the description until the trigger works reliably. A single well-tested skill delivers more value than ten rushed ones.
Name skills after the job they perform, such as release-notes or db-migration. Clear names help teammates browse the folder and understand each skill at a glance. Retire skills that no longer match your process.
Key Points
- A skill is a folder with a SKILL.md file and optional extras.
- Claude Code loads a skill only when the task matches its description.
- Project skills travel with the repository; personal skills follow you.
- Skills suit detailed procedures; CLAUDE.md suits short universal rules.
- Review third-party skills before use.