LLM Wiki — Synaptic Lattice

Skill Authoring Best Practices

Properties1
tagsprompt-engineering, workflow-pattern, architecture-pattern

Leitura de 5 min

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.

Worked Example — new-rag-eval Skill (2026-04-24)

A 2026-04-24 field report instantiates every principle on this page in one skill. The description frontmatter names both what it does (scaffold a RAG eval case from a golden example, wire it into the harness, run it, write a result summary) and the exact triggers (“add an eval for …”, “cover this regression with an eval”) — third-person, trigger-rich, the single field the router uses. Progressive disclosure in practice: metadata at session start, instructions on trigger, harness scripts and fixtures only on reference, so ambient cost stays low even with dozens of skills installed. Degrees of freedom are mixed deliberately: medium-freedom steps (gather query, expected citations, trace id; slugify kebab-case; summarize pass/fail plus grounded-citation and unsupported-claim rates) around low-freedom guardrails in a Do not block (never edit the case template, never touch other suites, never open a PR — that flow lives in the companion PR skill). Deterministic scoping via allowed-tools (read/write/edit plus uv run and git add on the eval path only) means the skill can run the harness and stage the case but cannot push — packaging rule: add skills when a workflow is stable enough to trigger by name.

Implications: this validates the page’s concision economics with a runnable artifact — the Do not block is the low-freedom guardrail pattern applied verbatim, and the no-PR boundary shows how skills compose (eval skill points at PR skill) instead of sprawling. Skill authors copying this get both the description formula and the allowed-tools scoping in one example.

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

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 agents-md-patterns — command-first, closure-defined instruction patterns for AGENTS.md files (the cross-tool equivalent of SKILL.md authoring)

Sources

  • raw/external/github-com-anthropic-best-practices-md-d3c57d61.md
  • raw/external/freedium-mirror-cfd-i-spent-6-months-tuning-claude-code-here-a23e1587.md

Visão de gráfico

Backlinks