Skill Authoring Best Practices

Anthropic’s official authoring guidance for SKILL.md files: how to write Skills that Claude can discover and use successfully. Only the metadata (name + description) is pre-loaded at startup; SKILL.md is read only when it becomes relevant, so concision and discoverability govern quality.

Core Principles (confidence: high)

• Concise is key. The context window is a public good — every token in a loaded SKILL.md competes with conversation history and other context. Challenge each paragraph: “Does Claude really need this? Can I assume it knows this? Does this justify its token cost?” The canonical contrast: ~50-token “use pdfplumber” instruction vs a ~150-token explanation of what PDFs are.
• Default assumption: Claude is already very smart. Only add context it doesn’t already have.
• Set appropriate degrees of freedom, matched to task fragility:
  • High freedom (text-based instructions) — multiple valid approaches, context-dependent decisions, heuristics. Example: code review process.
  • Medium freedom (pseudocode/scripts with parameters) — a preferred pattern exists, some variation acceptable. Example: report template with a customizable function.
  • Low freedom (specific scripts, no params) — fragile, error-prone, consistency-critical operations. Example: “run exactly python scripts/migrate.py --verify --backup, do not modify.” Analogy: narrow bridge with cliffs → guardrails; open field → general direction.
• Test with all models you plan to use. Haiku may need more guidance; Opus may be over-explained. Aim for instructions that work across the model set.

Structure and Naming (confidence: high)

• SKILL.md frontmatter supports exactly two fields: name (≤64 chars) and description (≤1024 chars).
• Naming: prefer gerund form (verb + -ing): “Processing PDFs”, “Managing databases”. Acceptable: noun phrases (“PDF Processing”) and action-oriented (“Process PDFs”). Avoid vague (“Helper”, “Utils”, “Tools”) and overly generic (“Documents”, “Data”, “Files”).
• Descriptions are written in third person — the description is injected into the system prompt, and inconsistent point-of-view breaks discovery. Good: “Processes Excel files and generates reports.” Avoid: “I can help you…”, “You can use this to…”. Include both what the Skill does and specific triggers/contexts for when to use it, because the description is the single field Claude uses to select among 100+ Skills.
• Example of a strong description: “Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.”

Progressive Disclosure (confidence: high)

SKILL.md is an overview pointing to detail files loaded only when needed — like a table of contents in an onboarding guide.

• Keep SKILL.md body under ~500 lines; split when approaching the limit.
• Pattern 1 — High-level guide with references: quick start + “See FORMS.md / REFERENCE.md / EXAMPLES.md” for advanced features.
• Pattern 2 — Domain-specific organization: per-domain reference files (finance.md, sales.md, marketing.md) so the agent only reads the schema relevant to the current query, keeping token usage low.
• Pattern 3 — Conditional details: basic content inline, advanced content behind links.
• Avoid deeply nested references. Claude may head -100 a file referenced from another referenced file, reading it incompletely. Keep all references one level deep from SKILL.md.

Implications: This is the counterpart of skills-directory-gate — that pattern describes routing through a directory of skills; this page governs writing each skill so the gate’s descriptions and bodies are worth loading. Together they form the authoring→discovery→loading lifecycle of the skill ecosystem. It also grounds why skill-reducer’s measured compression (48% description / 39% body with +2.8% quality) works: the marginal token cost of verbosity is real and the guidance explicitly prices it.

Open Questions

• Anthropic’s guidance is written for Claude’s own skill system. Do the same principles hold for the agent-agnostic registries (skills-re, openagentskill) whose consumers include Codex, Gemini CLI, and Cursor? The registries add cross-agent metadata (fit scores, trust, freshness) that this doc does not cover.
• The <500-line SKILL.md ceiling is unmeasured — a heuristic. No study yet ties body length to success rate across agents (skill-reducer is the closest, on descriptions).

Related

skills-directory-gate — the routing pattern that consumes authored Skills skill-reducer — measured evidence that Skill descriptions carry compressible fat multi-file-agent-architecture — the general pattern of which progressive disclosure is the skill-level instance monolithic-prompt-limits — the scaling problem progressive disclosure answers claude-code-best-practices — operational workflow guidance for the same agent that loads Skills

Sources

• raw/external/github-com-anthropic-best-practices-md-d3c57d61.md