SKILL 06 / META · DEEP DIVE

Reading the Official Authoring Guide

Six hard numbers on one docs page, and the physical reason behind each

2026-09-07 · BigCat

64 / 1024 / 1536 / 500 / 100 / 3. Only two of those six will ever actually stop you. Mix them up and you'll economize in exactly the wrong place.

Prerequisite → Skill 05 Meta-Skills Roundup (this page was item ⑦ on that list; here we open it up)

// WHY THIS MATTERS

How long should SKILL.md be? How many files? What makes a description trigger reliably? Anthropic answers all of it on one page — Skill authoring best practices — and answers in numbers. The problem is that the page runs several thousand words, and finishing it with only "be concise" in your head is the same as not reading it. This issue compresses it into one lookup table, then asks of every rule: why this number? Because once you know the mechanism, you know which rules bend and which ones break things. Every skill and doc named below is a link you can open; section 03 uses only skills that actually ship in the official repository, and section 04 covers where the guide itself will trip you up.

// 01

What it takes off your plate: six numbers instead of a hunch

Claim: this page isn't a skill and can't be installed — but everything it points at can be. The real workflow is: copy the minimal skeleton, fill it in against the table, verify with two built-in commands. Ten minutes, and worth more than the six thousand words.
HARD CONSTRAINTS (source: platform.claude.com · Skill authoring best practices) ──────────────────────────────────────────────────────────────────────────── name <= 64 chars · lowercase letters / digits / hyphens only no XML tags · no reserved words "anthropic" or "claude" gerund form recommended: processing-pdfs, analyzing-spreadsheets description non-empty · <= 1024 chars · no XML tags · THIRD PERSON must say both what it does AND when to use it body under 500 lines — a soft guideline; nothing errors, it just means it's time to split references one level deep only · every reference links from SKILL.md reference >100 lines put a table of contents at the top evaluations at least 3 · tested on Haiku, Sonnet AND Opus ──────────────────────────────────────────────────────────────────────────── CLAUDE CODE ADDS ONE REAL CUTOFF (source: code.claude.com · Skills) description + when_to_use are truncated at 1,536 chars in the skill listing. Past that, text isn't merely deprioritized — it is cut. The listing budget scales at roughly 1% of the model's context window. ──────────────────────────────────────────────────────────────────────────── THE THREE LOADING LEVELS (source: platform.claude.com · Agent Skills overview) Level 1 metadata (name+description) always, at startup ~100 tokens / skill Level 2 SKILL.md body when triggered under 5k tokens Level 3 bundled files and scripts only when used 0 until read; scripts bill output only

The first thing you can actually run

# 1. Copy the official minimal skeleton (template/ holds exactly one file)
mkdir -p .claude/skills/analyzing-invoices
curl -o .claude/skills/analyzing-invoices/SKILL.md \
  https://raw.githubusercontent.com/anthropics/skills/main/template/SKILL.md

# 2. Fill in name / description per the table, then check the YAML (v2.1.233+)
/plugin validate

# 3. See what this skill costs you in the listing — that's your standing tax
/context

# 4. Want the evaluation machinery? Install the official skill-creator
/plugin install skill-creator@claude-plugins-official

# 5. Two weeks later, audit: which skills never fired (v2.1.252+, interactive)
/skill-doctor
Failure mode: treating 500 as the hard limit and 1,536 as the suggestion. It's the other way around. Blow past 500 lines and nothing happens — you just make Claude swallow the whole thing on every trigger. 1,536 is a real cut: the crucial trigger phrase you put at the end of your description may never have reached the model at all.
Go deeper · Skill authoring best practices · anthropics/skills · template/ · Claude Code · Skills
// 02

Mechanism: every number maps to something concrete that breaks

Claim: these constraints aren't stylistic fussiness. Third person, one level deep, scripts over generated code — each corresponds to a reproducible failure. Know the failure and you won't be tempted to break the rule.

Why the description must be third person

Because it is injected into the system prompt. The guide's own wording: an inconsistent point of view "can cause discovery problems." "Processes Excel files and generates reports" is right; "I can help you process Excel files" and "You can use this to process Excel files" are both wrong — a first-person blurb appearing inside a system prompt blurs the line between the model's own identity and a candidate tool. And the description is the only retrieval key you get: the docs state plainly that Claude uses it to pick the right skill "from potentially 100+ available Skills." However good your body text is, it never enters that round of selection.

Why references must stay one level deep

The guide reports a very specific observed behavior: with nested references (SKILL.md → advanced.md → details.md), Claude often doesn't read the file whole — it previews with something like head -100 and walks away with incomplete information. So the rule isn't "don't nest too much," it's "every reference file links directly from SKILL.md." The same mechanism explains the neighboring rule: reference files over 100 lines need a table of contents at the top, because a partial read may be all you get, and a ToC at least tells the model what else is in there.

Why deterministic work belongs in a script

Look at the last row of the loading table: scripts execute through bash, their code never enters context, and only their output is billed. So shipping a validate.py versus having the model improvise validation code each time isn't a matter of taste — three things improve at once: reliability (it doesn't come out different every run), tokens (the code stays off the context window), and speed (nothing to generate). The guide also insists you state whether Claude should execute or read: "Run analyze_form.py to extract fields" and "See analyze_form.py for the extraction algorithm" are different instructions — the first is nearly free, the second costs you the whole file.

Degrees of freedom: narrow bridge or open field

The official analogy treats Claude as a robot walking a path. A narrow bridge with cliffs on both sides has exactly one safe route, so you give exact instructions and guardrails (low freedom). The doc's example is a database migration: "Run exactly this script: python scripts/migrate.py --verify --backup", immediately followed by "Do not modify the command or add additional flags." An open field with no hazards has many routes, so you give direction and get out of the way (high freedom) — the example is code review: analyze structure, check for bugs and edge cases, suggest readability improvements, verify project conventions. Four lines, not one concrete command. The middle rung is pseudocode or a parameterized script, for when a preferred pattern exists but variation is fine. The single criterion is how fragile the task is.

Failure mode: pinning a high-freedom task to a fixed procedure. Force code review into five mandatory steps and the model stops looking for what's peculiar about this repository. Invert it — tell a database migration to "use your judgment" — and it's only a matter of time. Ask first: if this goes wrong, can it be redone?
// 03

In practice: three disclosure patterns, each with a shipping example

Claim: the three progressive-disclosure patterns sound abstract on the page, but every one of them has a physical instance inside anthropics/skills. Copy the instance, not the page — because the paths in the docs' examples don't match the real skills.

Pattern 1: high-level guide with flat references

SKILL.md keeps only the quick start and hands everything else to sibling files — FORMS.md, REFERENCE.md, EXAMPLES.md — each read only when needed. Right for a skill that does one thing but has a few deep ends.

Pattern 2: split by domain — the shipping example is claude-api

The doc's illustration is a BigQuery skill with reference/finance.md, sales.md, product.md, marketing.md, and a SKILL.md that is pure navigation. The reasoning is concrete: when someone asks about sales metrics, the model shouldn't be forced to load the finance and marketing schemas. The official claude-api skill is this structure in finished form (it ships bundled with Claude Code), split by language and by topic across a dozen-plus files. The guide even suggests putting grep commands in SKILL.md — grep -i "revenue" reference/finance.md — so the model can fish for itself. When not to: splitting a single-domain skill into many files just adds a round trip.

Pattern 3: conditional detail plus a feedback loop — the example is docx

Basics live in the body, advanced branches hang off links: simple edits go straight to the XML; tracked changes → see REDLINING.md; OOXML internals → see OOXML.md. But the part of the real docx skill most worth stealing is its validation loop — unzip, run scripts/merge_runs.py to coalesce fragmented runs so text is findable, edit word/document.xml in place (with an explicit "do NOT reformat or pretty-print"), rezip, and then:

python scripts/office/validate.py out.docx --original doc.docx
# XSD checks; --auto-repair fixes common issues; add --author for redlining

Note a real inconsistency here: the best-practices page writes that example command as python ooxml/scripts/validate.py unpacked_dir/, while the repository's own skills/docx/SKILL.md actually runs scripts/office/validate.py out.docx --original doc.docx. The path in the docs is illustrative, not runnable. Copy commands from the skill, not from the guide.

Two patterns that aren't structural but decide the outcome

Boundary: a description can say when NOT to use it

The guide only tells you to write "what it does and when to use it." But look at the real thing — the docx description ends with: "Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation." Negative triggers are a move the docs never mention and the shipping skills use anyway. Once your library holds several adjacent skills (docx / pdf / pptx / xlsx being the obvious set), stating what a skill is not for buys more accuracy than another positive keyword.

Failure mode: putting time-sensitive information in SKILL.md. The guide calls this out by name — "before August 2025 use the old API, after that the new one" — because it is guaranteed to go stale. Write only the current method and fold the rest into a collapsed "Old patterns" section. Related anti-patterns: Windows backslash paths (always forward slashes), offering four libraries and letting the model choose (give a default plus one escape hatch), and inconsistent terminology (pick endpoint or URL or route, then never switch).
Go deeper · skills/docx/SKILL.md (the validation loop and the negative trigger, verbatim) · Claude API skill (domain splitting, finished)
// 04

The cost, and the alternative: after reading this, often the right move is not to write a skill

Claim: the most expensive advice on the page is the one nearly everyone skips — build evaluations before you write documentation. Skip it and you're solving imagined problems; honor it and it costs far more time than SKILL.md itself.

The five steps everyone skips

"Create evaluations BEFORE writing extensive documentation" is set in bold at the top of the evaluation section. The five steps: (1) run Claude on representative tasks with no skill and document the specific failures, (2) build three scenarios around those gaps, (3) measure the baseline, (4) write just enough content to close the gaps, (5) run the evals, compare against baseline, refine. One sentence of justification: this way you're solving actual problems.

There's a catch. The guide gives an evaluation JSON structure (skills / query / files / expected_behavior), then a Note immediately underneath says there is not currently a built-in way to run these evaluations — you build your own harness. So walking the five steps means writing a runner yourself, or installing skill-creator, which brings its own pipeline (evals/evals.json → grading.json → benchmark.json, running with-skill and without-skill groups side by side). The two tracks are not interchangeable; one eval file will not run everywhere.

The other skipped practice: Claude A and Claude B

The recommended iteration loop uses two instances: Claude A helps you write and refine the skill; Claude B, a fresh instance with the skill loaded, does real work with it. You watch where B stumbles and bring that back to A. The doc's own example is precise — "I asked B for a regional sales report and it wrote the query but forgot to filter out test accounts, even though the skill mentions this rule. Maybe it isn't prominent enough?" A might respond by reorganizing, or by hardening "always filter" into "MUST filter." The value is that it forces you to use observed behavior as evidence, instead of the feeling that things got better.

The honest costs

Failure mode: writing it and walking away. /skill-doctor lists each skill's token cost and invocation frequency and flags the ones that never fired at all — usually not because they're useless, but because the description never made it through selection. Delete them or rewrite the description; leaving them is pure rent.

// ONE-PAGE BUYING CARD

Do these three first: (1) copy template/SKILL.md into .claude/skills/ as your standing stub — plain text, zero cost, never expires; (2) install skill-creator (/plugin install skill-creator@claude-plugins-official) for its baseline-comparison evaluation machinery, not for drafting; (3) make /context and /skill-doctor a fortnightly habit.

When copying structure: one thing with several deep ends → pattern 1 (flat FORMS.md / REFERENCE.md); several domains → copy the official claude-api; correctness that must hold → copy the official docx loop of unpack, edit, scripts/office/validate.py, repack. Take commands from the skill itself, never from an illustrative path in the docs.

Numbers to keep handy: name <= 64 · description <= 1024 and third person · Claude Code listing truncates at 1,536 (a real cut) · body under 500 lines (a guideline) · references one level deep · reference files over 100 lines get a ToC · at least 3 evaluations · test on Haiku, Sonnet and Opus · ~100 tokens of standing metadata per skill · body under 5k tokens.

Order of operations: run the real task with no skill → write down the specific failures → build three scenarios → measure the baseline → write just enough → iterate against the baseline. Never documentation first.

// GLOSSARY

progressive disclosure
Layered loading: only name and description sit in context at startup; the SKILL.md body loads on trigger; bundled files load when read; scripts execute without their code entering context.
frontmatter
The YAML header at the top of SKILL.md. The spec requires only name and description; individual harnesses may add fields of their own.
degrees of freedom
How tightly the instructions pin the model down. The more fragile the task, the more exact the command (narrow bridge); the more open-ended, the more you give direction only (open field).
feedback loop
Run the validator, read the errors, fix, run again, and only proceed when it passes. The validator can be a script or a STYLE_GUIDE.md the model checks against.
plan-validate-execute
Have the model emit a machine-checkable intermediate plan, validate that, and only then execute. For batch, destructive or high-stakes operations.
voodoo constant
A magic number with no stated reason (TIMEOUT = 47). The guide asks that every configured value be justified: if you don't know the right value, how would Claude?

// FURTHER READING