Home / Extending: skills, MCP, subagents, hooks, plugins
Skills: teaching Claude a workflow
A skill encapsulates a reproducible workflow in a SKILL.md file, invoked by an explicit slash command or by automatic matching on its description.
A skill gathers a complete operating procedure into a single file, SKILL.md, which Claude Code loads like a set of instructions it knows how to follow without needing to retype it for every request. The file lives in a folder bearing the skill's name, and its content opens with a frontmatter header block, whose only genuinely recommended field is a natural-language description: what the skill does, and in what situation it should apply. If the field is omitted, Claude Code falls back on the first paragraph of the Markdown content to decide on triggering.
Two ways to trigger it
Claude invokes a skill in two distinct ways. The first is explicit: typing a slash command bearing the folder's name, for example /verifier-diacritiques for a skill stored in verifier-diacritiques/SKILL.md. The second is automatic: when processing a request, Claude compares its text against the description of each installed skill, and loads the one whose description best matches the current subject. No skill triggers unless its description mentions, in substance, the situation that should set it off, and a description that is too vague or too general does not match anything precise.
# Exemple illustratif, sur un dossier de démonstration
mkdir -p demo-skill/resumer-changelog
cat > demo-skill/resumer-changelog/SKILL.md <<'EOF'
---
description: Resume les derniers commits d'un depot en un changelog court, a utiliser quand on demande de preparer une note de version.
---
Lis les commits fournis, groupe-les par type, et rends une liste a puces
courte, une ligne par changement notable.
EOFWhat Claude actually adds to its toolbox
Once the skill is loaded, its content is added to the current turn as additional instructions, on the same footing as an instruction typed directly. Nothing is executed in advance: it is the file's text that guides the response, not a separate programme running in the background. That is why a well-written skill resembles a note you would leave for a colleague picking up a specific task, with enough detail that they do not have to guess, and little enough to stay readable in a single pass.
The action that deserves a skill is not just any action: it is the one that recurs. An explanation given only once does not justify the detour of a file. An explanation given again three times in the same week, however, already costs more to repeat than to fix in place once and for all. The logical next step, writing and testing your own skill, can be found in creating your own skill or your own command.
From repeated action to invoked skill
Explicit slash command versus automatic matching
| Triggering a skill | What triggers the loading | What success depends on | What happens if nothing matches |
|---|---|---|---|
| Explicit slash command | The user types /folder-name | The folder name is known and typed without error | The command simply does not exist yet |
| Automatic matching | The request's text matches the skill's description | The vocabulary of the request and that of the description overlap | Nothing signals that the skill existed, the request is handled without it |
A developer types the command /verifier-diacritiques in a project where a skill of the same name is installed at user level. Claude applies that skill's content to the current request.
Write, in one sentence, what this situation establishes, and in one sentence what it does not establish.
What this establishes: This result establishes that typing the slash command bearing the exact name of an installed skill is enough to trigger its execution, regardless of the content of its description.
What this does not establish: It does not establish that the same request, phrased without the slash command, would have triggered this skill through automatic matching on its description.
The three most common miscalibrations
- Too broad This result shows that every installed skill triggers automatically as soon as its subject is mentioned in a request.
- Too narrow This result proves nothing beyond the fact that a command was typed in the terminal.
- Off the mark This result shows that the developer knew the exact name of the skill's folder before typing the command.
- A skill is triggered in two ways: an explicit slash command typed by the user, or automatic matching between the request and the text of its description.
- The description field in the frontmatter is the only one genuinely recommended, and it is what Claude reads to decide whether to apply the skill without explicit intervention; failing that, the first paragraph of the content serves as a fallback.
- A skill's content is added to the current turn as additional instructions; there is no separate programme that runs in advance.
- An action deserves a skill as soon as it is requested again several times within the same work period, not the first time it is carried out.
Create a demo-skill/SKILL.md folder with a frontmatter description of a single sentence and a body of two or three lines, invoke it with its slash command in a Claude Code session, and confirm that the response does indeed follow the content you wrote.
Every datable claim in this lesson links here to the public text behind it. A source that does not open proves nothing.
- Claude Code, skills, recommended description field and fallback to the first paragraph consultée le 2026-09-02