What are Claude agent skills? A skill is a folder containing a SKILL.md file with instructions the model reads when a task matches the skill's description. It is not a plugin, not a tool, and not a separate model. It is a way to give a model a repeatable procedure it would otherwise have to be told every time.
This claude skills explained walkthrough covers what the file actually contains, how the model decides to open it, and how to write one that is worth keeping. Field names and file expectations change as the feature develops, so confirm the current schema in the official documentation for the tool you are using.
The definition that removes the confusion
Most confusion about agent skills comes from mixing three different things. A skill supplies knowledge and procedure. A tool lets the model act on a system. A subagent is a separate context that runs its own task.
A skill is the first of these. It contains no code and grants no permissions. It says: when someone asks me to do this kind of work, here is the procedure, here are the constraints, here are the output requirements.
What a skill is made of
- A folder with a predictable name, usually a short slug.
- A SKILL.md file at the root of that folder.
- Frontmatter at the top of the file, with the fields the model reads before deciding to open it.
- A body of instructions, references, and optional extra files loaded only when needed.
That last point matters. A skill can carry supporting documents that never enter the conversation unless the task actually requires them, which keeps the working context smaller.
How the model decides to use a skill
Selection is driven by the description. The model sees the description and the available tools, and it decides whether the skill applies to the request in front of it. This is why the description is the most important field in the file.
A vague description such as "helps with documents" will match almost nothing reliably. A description that names the trigger situations is what gets the skill opened when it should be.
A minimal skill you can copy
---
name: release-notes-writer
description: Use when the user asks for release notes, a changelog entry, or a customer-facing summary of shipped features from a commit list or ticket export.
allowed-tools: Read, Grep
---
Write release notes for a non-technical audience.
PROCEDURE
1. Read the supplied changes and group them into user-facing themes.
2. Drop anything internal: refactors, dependency bumps, test changes, CI edits.
3. For each theme, write one entry of at most two sentences.
4. Use plain past tense. No marketing adjectives.
RULES
- Never invent a feature, ticket number, or customer.
- If a change cannot be explained as a user benefit, leave it out.
- If the input is ambiguous about the release date, write [NEED INPUT: release date].
OUTPUT FORMAT
A markdown list, newest theme first, grouped under "Fixed", "Improved", and "Added".What each field is doing
- name: the identifier the folder and the model use. Lowercase with hyphens keeps it predictable across tools.
- description: the trigger text. Write it as the situations a user would describe, not as a category label.
- allowed-tools: the ceiling on what the skill may use while it is active. Restricting this is how you keep a read-only skill from taking actions you did not intend.
- body: the procedure. Numbered steps, explicit prohibitions, and an output format remove most rework.
Worked example: two descriptions, two outcomes
| Situation | Description | Result |
|---|---|---|
| A request for a customer-facing changelog | "Use when the user asks for release notes, a changelog entry, or a customer-facing summary of shipped features" | Skill opens reliably |
| A request to summarise a research paper | "Use when the user asks for release notes, a changelog entry, or a customer-facing summary of shipped features" | Skill stays closed |
The second row is the common failure. The model is not being difficult; the description simply does not describe that task, so not opening the skill is the correct behaviour.
Write the description as trigger conditions
The description is read on every request, so it should be short, concrete, and phrased in the user's words.
Use when the user asks to [situation one], [situation two], or [situation three]. Do not use for [nearby task that should not trigger it].
That last clause prevents a skill from firing on a neighbouring task and quietly applying the wrong procedure. Where your tool supports more metadata, keep it minimal; unused fields are still maintenance.
Keep a skill small enough to stay correct
A skill that handles thirty cases is hard to test and easy to break, because you cannot predict which case will trigger it. One procedure, a handful of triggers, and a short body is a skill you can reason about.
Two practical habits keep skills healthy. Write the reference material you only occasionally need into separate files that the skill reads on demand, and delete skills you stopped using. Both reduce the number of instructions competing for attention and make the remaining ones easier to verify.
Revise a skill when you catch yourself adding exceptions in conversation instead of in the file. That correction belongs in the body, once, where the next run will read it.
Common skill mistakes
- Writing a category label instead of triggers. "Helps with documents" matches nothing. Name the situations.
- Putting the procedure in the description. The description selects the skill, the body runs it.
- Granting every tool by default. A narrow allowed-tools list makes an accidental action impossible.
- Skipping the negative rules. "Never invent a ticket number" prevents the most damaging output failure.
- Loading everything up front. Large reference files belong in separate files the skill reads on demand.
Frequently asked questions
Do agent skills need code?
No. A skill is instructions in a markdown file. If your skill needs to run code or call an external service, that is a tool or a server, and the skill can describe how to use it.
How does a skill differ from a custom system prompt?
A system prompt applies to the whole conversation and is set by the operator. A skill is selected per task from the description and can be added later without rewriting everything else. Skills are for repeatable procedures; system-level instructions are for standing rules.
Where do skill files live?
That depends on the tool and the scope you are working at, such as per project or per user. Check the current documentation for the exact path in your setup, since it is one of the details most likely to have changed.
Why is my skill never used?
Usually the description. If it does not name the situations a user would describe, the model has no reason to open it. Test the description by reading it alone and asking whether you would have picked that skill.
Write one skill and test its trigger
Take one task you have explained to a model more than once, write it as a SKILL.md with a trigger-focused description and a narrow allowed-tools list, then ask for that task in three different phrasings. For the reusable instruction patterns underneath, browse the system prompt topic collection.