# How to Write a Claude Skill That Loads

> Source: https://rankxai.com/blog/how-to-write-a-claude-skill · Last updated: 2026-10-01

A Claude Skill is a folder holding a SKILL.md file: YAML frontmatter with a name and a description, then Markdown instructions. Claude reads only the description until a task matches it, so the description decides whether the skill ever loads. Write that line first, then the procedure beneath it.

## 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](/blog/what-are-claude-skills) 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.

| Where the skill runs | Description limit | Stated by |
| --- | --- | --- |
| claude.ai, custom skill uploaded as a zip | **200 characters** | [Claude help centre](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) |
| Agent Skills specification, and the Claude API | **1,024 characters** | [Agent Skills specification](https://agentskills.io/specification) |
| Claude Code | **1,536 characters**, counting `description` plus `when_to_use` together, then truncated | [Claude Code reference](https://code.claude.com/docs/en/skills) |

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:

| Skill | Description length | Times the 200-character cap |
| --- | --- | --- |
| `page-ui` | 904 characters | 4.5x |
| `content-review` | 741 characters | 3.7x |
| `page-seo` | 630 characters | 3.2x |
| `daily-post` | 367 characters | 1.8x |
| `organise-docs` | 351 characters | 1.8x |

`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`.

| Scope | Path | Loads in |
| --- | --- | --- |
| Personal | `~/.claude/skills/<name>/SKILL.md` | every project on that machine |
| Project | `.claude/skills/<name>/SKILL.md` | sessions in that repository |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | invoked as `/plugin-name:skill-name` |
| Enterprise | `.claude/skills/<name>/SKILL.md` in the managed settings directory | every user it is deployed to |

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](/glossary/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](/blog/how-mcp-works) 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](/blog/mcp-vs-skills) 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](/docs/mcp/agent-skills). They call the RankX AI MCP server, so [connecting the server](/blog/connect-rankx-to-claude) comes first and the skill files second. [Running a visibility audit from inside Claude](/blog/running-your-seo-from-claude-and-chatgpt) shows one doing the job end to end.

## Can you teach Claude a skill?

Yes, by writing a file rather than by training anything. A skill is a folder with a SKILL.md inside it, holding a name, a description and plain Markdown instructions. Claude reads the description at startup and loads the instructions when a request matches. No model weights change and no code is required.

## Does Claude have a skill creator skill?

Anthropic publishes one. The skill-creator skill ships in the anthropics/skills repository and as an official Claude Code plugin. It gathers requirements, drafts the SKILL.md, builds test cases, then runs them with and without the skill loaded so you can see what the skill actually changed rather than assuming it helped.

## What are some examples of Claude Skills?

Anthropic's public repository holds working examples covering documents, spreadsheets and slide decks. RankX AI publishes six for search work, including a visibility audit and a content brief. This site runs five internally, among them a content-review skill and the daily-post skill that drafted this article.

## How is a Claude Skill different from a subagent?

A Claude Skill is instructions loaded into the current conversation. A subagent is a separate agent with its own system prompt and its own context window. Skills can hand work to a subagent, and a subagent can preload skills, so the two compose rather than compete.