How to Write a Claude Skill That Loads

What is a Claude Skill?

A Claude Skill is a directory containing a SKILL.md file, and nothing else is required. That file carries YAML frontmatter with the two fields the specification makes mandatory, name and description, followed by Markdown instructions. Optional scripts/, references/ and assets/ folders sit beside it and load only when a task calls for them.

What Claude Skills are covers the concept, the types and where they run. This page covers the authoring, which is a separate job. The concept takes a paragraph. The file format has more edges than that paragraph suggests, and most of them are silent when you get them wrong.

How do you write a Claude Skill?

Writing a Claude Skill takes four steps and one file. The entire format is two required YAML fields and a Markdown body, which is a large part of why more than forty agent products now read it.

1. Create the directory. Name it for the job in lowercase with hyphens, for example processing-invoices. Put it in .claude/skills/ for one repository or ~/.claude/skills/ for every project on your machine.
2. Add SKILL.md. Open the file with a --- fence, a name line matching the directory, a description line, then a closing ---.
3. Write the description for discovery, not for a reader. Say what the skill does, then say when to use it, in the third person. This single line decides whether Claude ever opens the rest of the file.
4. Write the procedure underneath. Brief Claude the way you would brief a careful new colleague who already knows the fundamentals. Include a worked example of the input and the output you expect.

Anthropic's authoring guidance gives one instruction that saves the most rewriting: assume Claude is already competent. Explaining what a PDF is costs tokens and teaches nothing. Write down the judgement your team applies that Claude could not guess, and stop there.

Why the description decides whether a Claude Skill loads

The description is the only part of a Claude Skill that Claude reads before deciding to use it. At startup an agent loads the name and description of every installed skill and nothing more, roughly 100 tokens each according to the Agent Skills specification. The body is read only once a request matches.

That is what makes a vague description a silent failure. The skill installs, appears in the listing and never fires, and the symptom reads as Claude ignoring an instruction rather than as a metadata problem.

Anthropic's guidance is explicit that the description goes in the third person, because it is injected into the system prompt where a shift in point of view causes discovery problems. A line reading Processes Excel files and generates reports works. One that opens I can help you does not. Anthropic's own bundled skill goes further and quotes the phrases a user would actually type.

The description field has three limits, not one

The description limit for a Claude Skill depends on where the skill runs, and three different published figures apply. Every authoring guide checked for this article quotes at most one of them, and one quotes a number matching none.

All three were checked against their primary sources on 17 September 2026. Only one is documented as a truncation: the Claude Code reference says the listing is truncated at its figure. The other two are stated as maximums.

That makes the consequence sharper than a silent trim. A description that passes the specification's own validator at 1,024 characters, and works perfectly in Claude Code at 1,536, is still too long for the claude.ai uploader.

Write every description to fit 200 characters if the skill might ever leave your terminal. That is the only length valid on all three surfaces, and the constraint improves the line anyway.

What the 200-character cap costs a real skill

Shortening a description to 200 characters costs you the trigger clause, and that follows from Anthropic's own recommended shape rather than from bad luck. The guidance says to state the capability first and the Use when... clause second, so the end of the line is the natural place to trim. The end of the line is also the half that drives discovery.

As a measured example, take the five Claude Skills this site runs in production. Their descriptions were written for Claude Code, where the Agent Skills specification allows up to 1,024 characters. Measured on 17 September 2026 against the raw frontmatter of each SKILL.md, all five run past that upload path:

daily-post is the second shortest and shows the cost most clearly. Cut it at 200 characters and you stop mid-word inside a tool name, with every word of Use when asked to write, draft or publish the next blog post still to come. Trimmed to fit by hand, the skill would describe itself accurately and tell Claude nothing about when to run.

Five skills is an instance rather than a study, and they belong to one team. The part that generalises is the ordering: the recommended sentence order puts the discoverable half last, so whatever you trim to fit is the half you can least afford to lose. Front-load the trigger words and the problem costs nothing to avoid.

How to name a Claude Skill

A Claude Skill name must be 1 to 64 characters of lowercase letters, numbers and hyphens. It cannot start or end with a hyphen, cannot contain two hyphens in a row, and must match the name of its parent directory. The specification rejects anything else.

Anthropic suggests gerund form, so processing-pdfs rather than pdfs, on the grounds that it describes an activity. Noun phrases such as pdf-processing pass too. Vague names are the real failure: helper, utils and tools tell Claude nothing and tell your colleagues less.

One rule catches almost everyone's first attempt. A skill name cannot contain the reserved words anthropic or claude, which rules out naming a skill after the assistant it runs inside.

Where Claude Skills live, and which copy wins

Claude Code loads skills from several locations at once, and the directory name becomes the command you type. A skill at .claude/skills/deploy/SKILL.md is invoked as /deploy.

When two skills share a name, Claude Code resolves enterprise first, then personal, then project. Personal beats project, which catches people who expect a repository to override a machine. A forgotten copy in ~/.claude/skills/ silently shadows the reviewed one your team committed, and the only symptom is behaviour nobody else can reproduce.

Version-control the project ones. A skill is a text file, it changes how an agent behaves on your codebase, and reviewing it in a pull request is the same argument as reviewing a CI script.

How long should a SKILL.md be?

Keep the SKILL.md body under 500 lines. That figure appears in both Anthropic's authoring guidance and the Agent Skills specification, which adds that the instruction layer should stay under roughly 5,000 tokens. Past that, split the content into separate files.

Splitting costs nothing because of how loading works. Reference files sit on disk and consume no context window at all until Claude reads one, so a skill can bundle a complete API reference and still start cheap.

Keep those references one level deep from SKILL.md. Anthropic's guidance is that Claude may preview a file reached through another file with a partial read rather than reading it whole, so a reference pointing at a reference returns incomplete information. Give any reference file longer than 100 lines a table of contents at the top, for the same reason.

What about scripts, permissions and dependencies?

A Claude Skill can bundle executable code in a scripts/ folder, and Claude runs that code rather than reading it into context, so a long script costs only its output in tokens. Say which you want explicitly. Anthropic's guidance separates Run analyze_form.py to extract fields from See analyze_form.py for the extraction algorithm, and the two produce different behaviour.

Declare every dependency rather than assuming it, because the runtime differs by surface in the same way the limits do. claude.ai can install packages from npm and PyPI while a skill runs. The Claude API can do neither. A skill that installs what it needs therefore works on one surface and fails on the other, with nothing in the file to explain why.

There is a frontmatter field for saying so. The help centre documents an optional dependencies line holding the packages a skill needs, in the shape python>=3.8, pandas>=1.5.0. The specification does not list it, which puts it in the same category as everything else on this page: real where it is read, absent where it is not, and worth writing down either way.

The allowed-tools field pre-approves tools so Claude does not stop to ask permission. In Claude Code that grant covers only the turn which invoked the skill and clears with your next message, while the skill's instructions stay in context.

It grants rather than restricts. Every other tool remains callable, and disallowed-tools is the field that takes one away. The specification still marks allowed-tools experimental, so support varies between clients.

How to test a Claude Skill before you trust it

Build the evaluations before writing the skill. Anthropic's guidance is to run Claude on representative tasks with no skill at all, record exactly where it fails, then write only enough instruction to close those gaps. Writing the document first produces a skill that solves problems you imagined.

• Three scenarios, minimum. Each one a real request, with the behaviour you expect written down beforehand.
• Test on every model you will use it with. Instructions sufficient for Opus can leave Haiku short, and detail that helps Haiku can make Opus over-explain.
• Watch how Claude navigates the files. A reference it never opens is either unnecessary or badly signalled from SKILL.md.
• Test the trigger separately from the procedure. A skill that does the job perfectly once invoked, and never invokes itself, is a description problem wearing a procedure problem's clothes.

Anthropic ships a skill-creator skill for this loop, available in the anthropics/skills repository and as an official plugin. It drafts the skill, builds test cases, runs them with and without the skill loaded, and reports the difference.

Its benchmark step is the part worth knowing about. It runs each case repeatedly and reports the spread rather than a single pass or fail, which is the only honest way to test something probabilistic.

Which rules are actually enforced, and where

The Agent Skills specification and Claude Code disagree about what is mandatory, and that gap explains most of the contradictory advice in circulation. The specification requires name and description. Claude Code's reference marks every frontmatter field optional and treats name as a display label, because the directory name is what becomes the command.

Anthropic's own bundled skill-development skill demonstrates the split. Fetched raw on 17 September 2026, its frontmatter reads name: Skill Development, with a capital letter and a space, inside a directory called skill-development. That breaks the specification's name rule three ways at once, and it works perfectly in Claude Code. Its body runs to 637 lines and 3,196 words, over the 500-line guidance in the same documentation set.

It is not an isolated slip either. The help centre page that documents the 200-character cap uses name: Brand Guidelines as its own worked example, capitals and a space again. Two separate Anthropic surfaces teach a name style the Agent Skills specification rejects, which is the clearest sign available that the validation you get depends on the door you came in through.

Author to the specification even where your agent does not check, because the specification is what the other clients read. SKILL.md is now a cross-vendor format. Its own client showcase listed 46 products on 17 September 2026, counted from the page source, with Cursor, GitHub Copilot, VS Code, Gemini CLI, Codex and Goose among them. A skill valid only in Claude Code is a skill that travels nowhere.

The specification ships a validator for exactly this. Run skills-ref validate ./my-skill before sharing anything: it checks the frontmatter against the published naming conventions, which is the one piece of validation no agent performs for you at load time.

You no longer restart Claude Code after editing a skill

Claude Code picks up SKILL.md edits mid-session. Its reference documentation states that it watches the skill directories and applies changes without a restart, which makes the edit-and-retry loop any real skill needs far faster than it used to be.

Three exceptions survive, and the first one catches people writing their very first skill. Claude Code watches the directories it found at startup, so if you create a top-level skills directory that did not exist when the session began, restart once so it can start watching. Edits after that are picked up live.

The other two are narrower. Bare mode disables the watching entirely. And a skill folder that is also a plugin needs /reload-plugins before changes to its hooks, agents, MCP configuration or output styles take effect, although the SKILL.md text itself still reloads on its own.

Guides written earlier in 2026 instruct you to restart the session after every edit, which was true of an earlier build and is not true now. Check the date on any skill-authoring guide before following it. This page carries its own date at the foot for the same reason.

The Claude Skill checklist

Run this before sharing a Claude Skill with anyone. Each line is a rule from the specification, Anthropic's authoring guidance or the Claude Code reference, and each one fails silently when broken.

• name is lowercase letters, numbers and hyphens, 64 characters or fewer, with no leading, trailing or doubled hyphen, and it matches the directory name.
• name contains neither anthropic nor claude.
• description is in the third person and names both what the skill does and when to use it.
• description fits 200 characters if the skill will ever run on claude.ai, with the trigger words inside that limit.
• The SKILL.md body is under 500 lines, with detail moved into references/.
• Every reference file is one level deep from SKILL.md, and anything over 100 lines opens with a table of contents.
• File paths use forward slashes, including on Windows.
• No dates or version cut-offs in the instructions that will quietly become wrong.
• MCP tools are named in full, as ServerName:tool_name.
• Three evaluations exist, and the skill has been run against every model you will use it with.
• skills-ref validate ./my-skill passes.

Where Claude Skills fit beside MCP

A Claude Skill teaches procedure and the Model Context Protocol grants access, so a skill that has to touch a live system needs both. Writing a perfect procedure for a system Claude cannot reach produces a confident description of work that never happened. When a skill beats an MCP tool works through the decision properly.

RankX AI publishes six agent skills for search work, including a visibility audit and a content brief, documented in the Agent Skills reference. They call the RankX AI MCP server, so connecting the server comes first and the skill files second. Running a visibility audit from inside Claude shows one doing the job end to end.