Short answer

A SKILL.md starts with YAML frontmatter holding a name, in lowercase letters, numbers and hyphens up to 64 characters, and a description of what the Skill does and when to use it, up to 1,024 characters. The body holds the steps Claude cannot infer, kept under 500 lines. Longer reference material goes in separate files the body links to.

What goes in a SKILL.md file?

A YAML header that decides when the Skill loads, and a Markdown body that says what to do once it has. The Skill is the folder around the file, and it can also hold scripts, templates and reference documents.

client-status-report/
  SKILL.md          instructions, loaded when the Skill triggers
  template.md       the report layout, read when needed
  reference/
    clients.md      account names and owners, read when needed
  scripts/
    check_dates.py  run, not read into context

Anthropic's rules for the header, as of September 2026:

  • name: at most 64 characters, lowercase letters, numbers and hyphens only, and it cannot contain "anthropic" or "claude".
  • description: required, at most 1,024 characters, no XML tags, and it should say both what the Skill does and when to use it.

The same format is the Agent Skills open standard, so a well-written Skill also works in other tools that read it, such as Codex, Gemini CLI, Cursor and VS Code.

How do you write a description that triggers?

Claude sees only the name and description of each installed Skill until one matches. Write the description in the words a person will type.

  • Say what it does and when. "Writes the weekly client status report. Use when asked for a status update, weekly report or account summary for a client."
  • Name the triggers: the file types, phrases and tasks people mention, including the informal ones.
  • Write in the third person. Anthropic's guidance warns that "I can help you" or "You can use this" confuses selection.
  • Avoid category labels. "Helps with reports" competes with every other Skill and rarely wins.

What belongs in the body, and what does not?

Only what Claude would get wrong without being told. It knows what a status report is, not that yours leads with risks.

  • Lead with the steps, numbered when the order matters.
  • State rules as rules. "Never include pricing" beats a paragraph explaining why pricing is sensitive.
  • Match the freedom to the risk. Loose guidance for judgment work, an exact script and "run exactly this" for anything fragile.
  • Keep the body under 500 lines, Anthropic's recommendation. Split into files as you approach it.
  • Link reference files one level deep. Claude may only preview a file that is linked from another linked file, so every reference should be linked from SKILL.md itself.
  • Leave out time-sensitive notes such as "until August use the old form". They go stale.

What does a good SKILL.md look like?

A small example where every line changes what Claude does.

---
name: client-status-report
description: Writes the weekly client status report from the project
  folder. Use when asked for a status update, weekly report, account
  summary or "where are we" note for a client.
---

# Client status report

1. Read the latest notes in the client's folder. Ignore anything older
   than 14 days unless it is an open risk.
2. Fill in template.md. Keep the section order.
3. Lead with risks and decisions needed. Progress comes second.
4. Name an owner and a date for every open item. If either is
   missing, write "owner needed" rather than guessing.
5. Run scripts/check_dates.py on the draft and fix what it reports.

Rules
- Never include fees, rates or invoice amounts.
- Dates as "Sep 28", never ISO.
- Under 300 words. If it runs longer, cut progress, not risks.

Account names and owners: see reference/clients.md

How do you test that a Skill works?

Test the trigger first, then the output.

  1. Write three test requests before the Skill, in the words a colleague would use, and note how Claude does without it. Anthropic recommends building these evaluations first.
  2. Check it triggers in a fresh conversation, from each request, without naming the Skill.
  3. Check it does not trigger on nearby requests that should go elsewhere.
  4. Read what Claude did, not just the result. If it keeps opening the same reference file, that content belongs in SKILL.md. If it never opens one, the link is unclear or the file is unnecessary.
  5. Test on every model you use. Instructions that suit a large model can be too thin for a small one.

You do not have to start from a blank file. Do the task once with Claude, then ask it to turn what you just told it into a Skill, and trim what it writes.

Where do you install a Skill?

In the Claude apps, upload the folder as a ZIP under Customize, then Skills. It needs code execution turned on. On Team and Enterprise plans, Owners can provision a Skill for the whole organization. In Claude Code, put the folder in .claude/skills/ inside a repository to share it with the team, or in ~/.claude/skills/ for yourself. To decide between a Skill and an MCP server, see Claude Skills vs MCP.

Common questions

How long should a SKILL.md be?

Anthropic recommends keeping the body under 500 lines, and most good Skills are far shorter. The body loads when the Skill triggers, so every line competes with the conversation for attention. Move long reference material into separate files.

Why is my Claude Skill not triggering?

Almost always the description. It is the only part Claude reads before deciding, so it needs to say what the Skill does, when to use it, and the words people actually use for that task. Rewrite it in the third person with concrete triggers, then test from a fresh conversation without naming the Skill.

Can a Skill include code?

Yes. A Skill can bundle scripts that Claude runs instead of writing its own code each time, which is more reliable and uses fewer tokens because only the output enters the conversation. Say plainly whether Claude should run a script or read it, and list any packages the script needs.

Related reading