What a skill is and what it solves
A skill is a package of instructions the agent loads when it is needed. In its simplest form it is a single markdown file called SKILL.md: YAML frontmatter at the top (explaining when it should be used) and the instructions the agent follows below.
A skill triggers in two ways:
- You invoke it by typing
/skill-name. - The agent invokes it when the task matches the
descriptionfield.
The problem it solves is concrete: retyping the same set of instructions into chat every time. If you keep re-explaining the same checklist or the same procedure, that belongs in a skill.
| Mechanism | When it loads | What it fits |
|---|---|---|
| CLAUDE.md | Every session, always | Short facts: conventions, commands, prohibitions |
| `.claude/rules/` (with paths) | When matching files are worked on | Area-scoped rules: testing, security |
| Skill | When invoked, or when it matches the task | Multi-step procedures, checklists, long reference material |
The core of the difference is token economics. Every line of CLAUDE.md enters the context on every request. A skill's body loads only when used — so keeping a 400-line release checklist as a skill is practically free, while keeping it in CLAUDE.md eats every session's budget.
A few important details:
- Skills follow the Agent Skills open standard, so the format is not tied to a single tool.
- Claude Code ships with bundled skills such as
/code-review,/debugand/loop. - A skill folder can hold supporting files (reference docs, scripts) that are read only when needed.
- Once a skill loads, its content stays in context for the rest of the session — which is why keeping the body short matters.
📚 Sources and documentation
- Claude Code — Skillsofficialcode.claude.com
Skill locations, frontmatter fields and loading behaviour.
- Agent Skills open standardofficialagentskills.io