Claude Code Skills: How to Write a SKILL.md That Works

Claude Code Skills: How to Write a SKILL.md That Works

To write a useful Claude Code skill, you create a folder with a SKILL.md file that has two parts: a header with a name and description, and a body with instructions. The description matters most, because it is what Claude reads to decide when to use the skill. Everything else should be short, verifiable and backed by separate files once the subject grows.

Key takeaways

• The description says what the skill does and when to use it. Claude reads it to decide whether to trigger the skill.
• The body of SKILL.md should be a procedure: steps, a definition of done, and what to do when something is unclear.
• Long material (templates, examples, references, scripts) belongs in support files that are read only when needed.
• Project skills live in the repository, so they can be reviewed like code, with a pull request and a named owner.
• Every skill needs a simple test: requests that should trigger it and requests that should not.

What is a skill, and how does Claude Code load it?

According to Anthropic's Claude Code documentation on skills, a skill is a folder that packages a capability: a SKILL.md file and, if needed, other files and scripts. Claude decides on its own when to use each skill, based on the user's request and the description you wrote. That is different from a command the person has to type.

The technical point that matters most for authors is staged loading. At the start of a session, Claude sees only the name and description of each available skill. When a skill looks relevant, it reads the body of SKILL.md. Support files are read only when the instructions tell Claude to consult them. This fits what Anthropic describes in its writing on context engineering for agents: context is a limited resource, and the goal is to bring the right information at the right moment, not everything at once. If that idea is new to you, start with what a context window is.

There are two common places to keep skills. Personal skills live in the user's own folder and apply to all of that person's projects. Project skills live in a folder inside the repository, and anyone who clones the project gets the same skills. For a team, the second option is usually the right one, because the skill gains history, an author and a review step. For a broader view of the topic, see Claude Code Skills: How to Create Them for Your Team.

How do you write a description that triggers the skill at the right time?

The SKILL.md header has a name field and a description field. The name identifies the skill, in lowercase letters and hyphens. The description is the trigger. If it is vague, the skill is never used, or it is used at the wrong time. If it is too broad, it fires in conversations that have nothing to do with it.

A good description answers two questions in the same breath: what the skill does and in which situations it should step in. Use the words your team actually uses when asking for the task, not the internal name of the process.

Compare two examples, both illustrative:

• Weak: Helps with reports.
• Better: Builds the weekly maintenance report from the spreadsheet exported by the system. Use when the request mentions the weekly report, the week close, or a summary of work orders.

The second version has a concrete verb, a data source and phrases that appear in real requests. It also helps prevent false triggers, because it marks out the territory.

A few practical rules for the description:

• One skill, one task. If the description needs several sentences joined by "or", you probably have two skills.
• Name the file type or system involved, when there is one.
• Say when not to use it, if a neighboring skill could be confused with this one.
• Avoid generic promises such as "improves any text". Claude will try to trigger it for everything.

What goes in the SKILL.md instructions?

The body is the procedure. Think of it as the script you would give a capable colleague who has never done this task at your company. They know how to write and reason, but they do not know your rules, your formats or your limits.

A structure that works well:

• Goal in one or two sentences: the expected result.
• Inputs: what the person must provide, and what to do if something is missing.
• Steps in order, each with a verifiable action.
• Output format: fields, order, tone, length.
• Limits: what the skill never does, and when to stop and ask for human confirmation.
• Definition of done: how to tell the work was finished properly.

Two writing choices make a difference. The first is to prefer specific, imperative instructions, such as "list the work orders open for more than a week", over "analyze progress". The second is to explain the reason behind the most important rules. When Claude understands why a rule exists, it applies the rule better in edge cases than when it receives a bare prohibition.

It also helps to be honest about what the skill does not solve. If a step depends on a business decision, write that Claude should present the options and wait for the choice instead of deciding alone. This matches Anthropic's advice in Building effective agents: start simple, use predictable workflows where you can, and reserve autonomy for places where judgment is needed.

The header can also restrict the tools the skill uses. The allowed-tools field, described in the documentation, limits what Claude can do while the skill is active. A review skill that only needs to read files should not have permission to edit them or run commands. Check the current documentation for the exact format and behavior, because this feature evolves.

When should you use support files and scripts?

A SKILL.md that grows too large becomes a double problem: it consumes context every time it is read, and it becomes hard to review. The fix is to split it. The body keeps the main flow and points to other files in the same folder, which Claude reads only when a step requires them.

Good candidates for separate files:

• Output templates, such as the standard text of a report or an email.
• Input and output examples approved by the team.
• Long domain rules, such as a naming policy or a code review checklist.
• A glossary of internal terms.
• Scripts for deterministic tasks, such as validating a format, converting a spreadsheet or calculating something that should not depend on interpretation.

The rule for scripts is simple: if the result must always be the same for the same input, do not ask the model to do it by hand. Let code run, and let Claude interpret the result. The same reasoning appears in Anthropic's guide on writing tools for agents: clear, predictable outputs make an agent more reliable.

In SKILL.md, reference each support file and say when to consult it. For example: "to build the final summary, read the report template in the support folder". Without that pointer, the file exists but nobody uses it.

A security warning: if the skill reads external documents, emails or web pages, that content can contain malicious instructions. State in the skill that text it reads is data, not orders, and read Prompt Injection Protection for AI Agents. If the skill also uses tools connected through MCP, see Configure MCP in Claude Code to understand scopes and permissions.

How do you review a skill as a team?

A skill is an instruction that changes the behavior of a tool that writes and runs things. It deserves the same care as an automation script. When it lives in the repository, the natural flow is the one used for code: a change on a branch, a pull request, a review and approval by someone responsible.

A review checklist you can use in the pull request:

• Does the description say what the skill does and when to use it, in the team's own words?
• Does it overlap with another skill? If so, do the descriptions make clear who does what?
• Are the steps verifiable, or are there vague phrases like "do a good analysis"?
• Are the allowed tools the minimum necessary?
• Does the skill handle personal data? If it does, is there an instruction not to copy that data into the output unnecessarily (consider the LGPD and, if data goes to providers outside Brazil, international data transfer when using AI providers)?
• Is there a stop instruction and human confirmation before irreversible actions?
• Are the support files up to date and referenced?
• Is there a named owner and an agreed date for the next review?

An acceptance test should be part of the review. Write a short list of real requests: some that should trigger the skill, some similar ones that should not, and some that are incomplete. Run each one and record the result. This is a lean version of what Anthropic describes in Demystifying evals for AI agents: define tasks and success criteria, and look at what the agent actually did, not only the final answer. For the generated code side, AI-Generated Tests: Can You Trust Them? is a useful complement.

Step by step: writing your first skill

The path below avoids the most common mistake, which is writing instructions before knowing which task the skill solves.

• Pick a task your team repeats and that has a known output format.
• Ask two people to describe how they do it today. Note the differences, because they show where rules are missing.
• Write the description first, covering what the skill does and when to use it. Show it to a colleague and ask in which situations they would expect it to trigger.
• Write the body with a goal, inputs, steps, output format and limits.
• Move long templates and examples into support files and reference each one.
• Define the minimum allowed tools.
• Run the list of test requests, adjust the description if it triggers too much or too little, and repeat.
• Open the pull request, name an owner and agree on when to reread the skill.

Illustrative scenario: a technical support team wants Claude Code to prepare a ticket summary to hand over to the next shift. The first version of the skill said only "summarizes tickets" and fired even when someone asked to summarize any random text. The team rewrote the description to mention shift handover and ticket history, moved the summary template into a support file, and added a rule: if the ticket number is missing, ask for it before summarizing. After that, they began testing a handful of requests of each kind before approving changes. The example is invented, but it shows the cycle: precise description, short body, separate support files, simple test.

The method we use in AI projects applies well here, at small scale. Map: understand how the task is done today and where it starts. Limit: define accessible data, allowed tools and actions that require approval. Pilot: run one skill in a real workflow, recording what happened against an agreed success criterion. Hand over: leave an owner, documentation and a review routine, then decide whether to expand, adjust or stop.

Frequently asked questions

How many skills should a team have? Start with a few, tied to repeated and well understood tasks. Each new skill adds a description that Claude must evaluate, and similar descriptions compete with each other. Create another only when there is a clearly distinct task.

Is a skill the same thing as the CLAUDE.md file? No. CLAUDE.md holds general project guidance that applies to the whole session, such as conventions and common commands. A skill is a procedure for a specific task and is loaded only when Claude judges it relevant.

My skill is not being triggered. What should I check first? Start with the description: does it name the task and the words people use in the request? Then check that the file is in the right folder, that the header is well formed, and that no other skill with a similar description is competing with it. Test with real requests and change one thing at a time.

Can I put customer data inside a skill? It is not recommended. A skill sits in a repository and circulates among people, so it should contain procedure and templates, not personal data or secrets. If the task needs data, say where to read it from with the right permission, and instruct the skill to use only what is necessary, in line with the LGPD.

Sources

• Anthropic: documentação de skills no Claude Code
• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• Anthropic: Demystifying evals for AI agents