# Skill Authoring Best Practices Official Anthropic documentation on writing effective Skills. Retrieved 2026-03-19. ## Core Principles ### Concise is Key The context window is a public good. Your Skill shares it with everything else Claude needs to know. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context. Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information: - "Does Claude really need this explanation?" - "Can I assume Claude knows this?" - "Does this paragraph justify its token cost?" ### Set Appropriate Degrees of Freedom Match the level of specificity to the task's fragility and variability. - High freedom (text-based instructions): When multiple approaches are valid, decisions depend on context, heuristics guide the approach - Medium freedom (pseudocode or scripts with parameters): When a preferred pattern exists, some variation is acceptable - Low freedom (specific scripts, few or no parameters): When operations are fragile and error-prone, consistency is critical Analogy: Think of Claude as a robot exploring a path. Narrow bridge with cliffs = provide specific guardrails (low freedom). Open field = give general direction (high freedom). ### Test with All Models You Plan to Use Skills act as additions to models, so effectiveness depends on the underlying model. What works for Opus might need more detail for Haiku. ## Skill Structure ### YAML Frontmatter Requirements - `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words ("anthropic", "claude") - `description`: Maximum 1024 characters, non-empty, no XML tags. Should describe what the Skill does and when to use it ### Naming Conventions Consider using gerund form (verb + -ing): `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`. Avoid vague names (`helper`, `utils`), overly generic (`documents`, `data`), inconsistent patterns. ### Writing Effective Descriptions ALWAYS write in third person. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems. - Good: "Processes Excel files and generates reports" - Avoid: "I can help you process Excel files" - Avoid: "You can use this to process Excel files" Structure: [What it does] + [When to use it] + [Key capabilities] Examples of good descriptions: ```yaml description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. ``` ```yaml description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files. ``` ### Progressive Disclosure Patterns Keep SKILL.md body under 500 lines for optimal performance. Split content into separate files when approaching this limit. Pattern 1: High-level guide with references — SKILL.md contains quick start + links to detailed files Pattern 2: Domain-specific organization — Content split by domain to avoid loading irrelevant context Pattern 3: Conditional details — Basic content shown, advanced content linked ### Avoid Deeply Nested References Keep references one level deep from SKILL.md. Claude may partially read files when they're referenced from other referenced files. ### Structure Longer Reference Files with Table of Contents For reference files longer than 100 lines, include a table of contents at the top. ## Workflows and Feedback Loops ### Use Workflows for Complex Tasks Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses. ### Implement Feedback Loops Common pattern: Run validator → fix errors → repeat. This pattern greatly improves output quality. ## Content Guidelines ### Avoid Time-Sensitive Information Use "old patterns" sections with `<details>` tags rather than date-conditional instructions. ### Use Consistent Terminology Choose one term and use it throughout. Don't mix "API endpoint", "URL", "API route", "path". ## Common Patterns ### Template Pattern Provide templates for output format. Match strictness level to needs. ### Examples Pattern For Skills where output quality depends on seeing examples, provide input/output pairs. ### Conditional Workflow Pattern Guide Claude through decision points with explicit decision trees. ## Evaluation and Iteration ### Build Evaluations First Create evaluations BEFORE writing extensive documentation. Evaluation-driven development: 1. Identify gaps: Run Claude on representative tasks without a Skill 2. Create evaluations: Build three scenarios that test these gaps 3. Establish baseline: Measure performance without the Skill 4. Write minimal instructions: Just enough to address gaps 5. Iterate: Execute evaluations, compare against baseline, refine ### Develop Skills Iteratively with Claude Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps design and refine instructions, while Claude B tests them in real tasks. ### Observe How Claude Navigates Skills Watch for: unexpected exploration paths, missed connections, overreliance on certain sections, ignored content. ## Anti-Patterns to Avoid - Windows-style paths (use forward slashes always) - Offering too many options (provide a default with escape hatch) - Assuming tools are installed (be explicit about dependencies) ## Checklist for Effective Skills ### Core Quality - Description is specific and includes key terms - Description includes both what the Skill does and when to use it - SKILL.md body is under 500 lines - No time-sensitive information - Consistent terminology throughout - Examples are concrete, not abstract - File references are one level deep - Progressive disclosure used appropriately - Workflows have clear steps ### Testing - At least three evaluations created - Tested with Haiku, Sonnet, and Opus - Tested with real usage scenarios