What actually makes a Claude Skill work, according to Anthropic's own guide

A Skill is a folder Claude can open mid-task: a SKILL.md file plus, optionally, scripts and reference material. The pitch is that Claude only pays for what it uses — most of a Skill sits outside the context window until something in the conversation actually calls for it. Anthropic's own authoring guide spends less time on what to put in a Skill than on what to leave out, and the shape of that advice is worth copying directly.

The description field decides everything

Before Claude opens a Skill, it sees one thing: the description field in the YAML frontmatter, capped at 1,024 characters. Anthropic's guidance is specific — write it in third person ("Processes Excel files…", not "I can help you with…"), and state both what the Skill does and when to use it. With more than a hundred Skills potentially available at once, this sentence is a matching problem: Claude is choosing among candidates based on the description alone, so a vague one means the Skill quietly never gets picked, with no error to tell you why.

The name field is smaller but has its own rules — 64 characters max, lowercase letters, numbers and hyphens only, and it can't contain "claude" or "anthropic." Anthropic recommends gerund-style names (processing-pdfs, analyzing-spreadsheets) over vague ones (helper, utils).

Three levels, three costs

Skills load in stages, and the cost model is the reason the format looks the way it does:

That structure is also the reason the size limits exist: Anthropic recommends keeping the SKILL.md body under 5,000 tokens and under 500 lines. Past that, move content into a separate file and link to it — it costs nothing until Claude opens it.

Keep references one level deep

A file that Claude only partially reads is worse than a file it doesn't read at all. Anthropic's guidance warns that Claude may skim a deeply nested reference chain (effectively running something like head -100 on it) rather than reading the whole thing, so anything more than one link away from SKILL.md risks being read incompletely. For any reference file over 100 lines, put a table of contents at the top — that way even a partial read shows Claude the full scope of what's available.

Match the instructions to what can go wrong

Not every Skill needs the same kind of instruction. Anthropic frames this as "degrees of freedom": a judgment-heavy task (summarizing a document, drafting an email) can be described in flexible, high-freedom language, while a fragile or must-be-consistent operation (a database migration, a specific API call sequence) should be pinned down with an exact, low-freedom script. Writing loose prose for the fragile case is where Skills tend to fail silently.

Test the baseline before you write the essay

The recommended order is easy to skip and easy to regret skipping: run at least three real test scenarios with Claude before writing extensive documentation, so you know what Claude already does wrong without the Skill. Otherwise it's easy to spend paragraphs solving a problem Claude didn't actually have. Anthropic also recommends testing the finished Skill against every model you plan to run it with — Haiku, Sonnet, and Opus don't behave identically, and instructions concise enough for Opus can be too sparse for Haiku.

Treat it like installing software

Anthropic states this plainly: only use Skills you wrote yourself or that come directly from Anthropic. A Skill can instruct Claude to misuse a tool or exfiltrate data, and there is no sandboxing that makes an untrusted one safe by default. A folder of markdown and scripts you didn't write is still code you're about to let an agent run.

Check the date. Anthropic's own best-practices doc warns against baking in time-sensitive language like "before August 2025, use X" — Skill content isn't automatically refreshed, and the same caution applies to this article. Read the linked docs directly if the surface-availability details above have since changed.