Writing Agent Skills the Anthropic way: right description, under 500 lines, evals first

Writing a skill is easy: one SKILL.md file with a name and a description. Writing a skill that Claude uses at the right moment and that does the right thing is much harder. Popular skills tend to fail in two ways: a vague description so Claude never calls it, or a sprawling body explaining things Claude already knows, burning context every time it runs. Anthropic has a whole page on Skill authoring best practices; this post summarises the most practical principles, plus a checklist before sharing a skill with your team.

Principle 1: be concise, assume Claude is already smart

At startup only the name and description of every skill are preloaded. SKILL.md is read when the skill is relevant, extra files only when needed. But once loaded, every token of the skill competes with the conversation history. For each paragraph, ask: "Does Claude really need this explanation?" The docs' example: a ~50-token PDF text extraction section (just the library and four lines of code) works better than a 150-token version explaining what a PDF is.

Principle 2: pick the right "degree of freedom"

An easy image: a narrow bridge with cliffs on both sides needs guardrails; an open field just needs a direction.

Principle 3: name and description decide whether the skill is used

• name: max 64 characters, lowercase letters, numbers and hyphens only; must not contain "anthropic" or "claude". Prefer gerunds: processing-pdfs, analyzing-spreadsheets. Avoid helper, utils.
• description: max 1,024 characters, saying both what it does and when to use it, with the keywords users actually type.
• Always write in the third person ("Processes Excel files…"), because the description is injected into the system prompt.

description: Generate descriptive commit messages by analyzing git diffs.
  Use when the user asks for help writing commit messages or reviewing
  staged changes.

Principle 4: progressive disclosure

• Keep the SKILL.md body under 500 lines; split into files beyond that.
• SKILL.md acts as a table of contents: "Form filling: see FORMS.md; API: see REFERENCE.md".
• Keep references one level deep from SKILL.md. If A points to B which points to C, Claude may only skim (head) and miss things.
• Reference files over 100 lines should start with a table of contents.
• Split by domain: reference/finance.md, reference/sales.md… a revenue question only reads the finance file.

Principle 5: workflows, checklists and feedback loops

For multi-step work, give Claude a checklist to copy into its reply and tick off. For critical work, add a "run validator → fix errors → run again" loop and only proceed once validation passes. Utility scripts beat having Claude write code itself: they're more reliable, and only the script's output costs tokens, not its contents.

Principle 6: evals first, writing second

1. Have Claude do a real task without the skill and note where it fails.
2. Write 3 test scenarios targeting exactly those failures and measure a baseline.
3. Write the minimum instructions needed to pass, then iterate.

A great trick: use "Claude A" to write the skill with you and "Claude B" (a fresh session with the skill) to run real tasks, bringing B's observations back to A for fixes. Test with every model you'll use: what Opus gets immediately may not be clear enough for Haiku.

Common mistakes

• Windows-style paths (scripts\helper.py); always use /.
• Offering too many options ("use pypdf, or pdfplumber, or…"); pick one default with one escape hatch.
• Time-sensitive information ("before August, use the old API"); move it to an "old patterns" section.
• Inconsistent terminology and unexplained "magic constants" in scripts.

How to apply it

• Dev: Open your existing skills, rewrite descriptions as "what it does + when to use + keywords", and cut every paragraph explaining common knowledge.
• Tech Lead: Review skills like code: description, length, one-level references, at least 3 evals.
• PM: Turn repeated workflows (writing PRDs, synthesising feedback) into skills by doing them once with Claude and asking it to "package the pattern we just used".