Comprehensive guide for skill development based on Anthropic's official best practices - use for complex skills requiring detailed structure

Anthropic's official skill authoring best practices Apply Anthropic's official skill authoring best practices to your skill. Good Skills are concise, well structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively. Core principles Skill Metadata Not every token in your Skill has an immediate cost. 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. Test with all models you plan to use Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with. Testing considerations by model : Claude Haiku (fast, economical): Does the Skill provide enough guidance? Claude Sonnet (balanced): Is the Skill clear and efficient? Claude Opus (powerful reasoning): Does the Skill avoid over explaining? What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them. Skill structure <Note YAML Frontmatter : The SKILL.md frontmatter supports two fields: name Human readable name of the Skill (64 characters maximum) description One line description of what the Skill does and when to use it (1024 characters maximum) For complete Skill structure details, see the [Skills overview](docs.claude.com/en/docs/agents and tools/agent skills/overview skill structure). </Note Naming conventions Use consistent naming patterns to make Skills easier to reference and discuss. We recommend using gerund form (verb + ing) for Skill names, as this clearly describes the activity or capability the Skill provides. Good naming examples (gerund form) : "Processing PDFs" "Analyzing spreadsheets" "Managing databases" "Testing code" "Writing documentation" Acceptable alternatives : Noun phrases: "PDF Processing", "Spreadsheet Analysis" Action oriented: "Process PDFs", "Analyze Spreadsheets" Avoid : Vague names: "Helper", "Utils", "Tools" Overly generic: "Documents", "Data", "Files" Inconsistent patterns within your skill collection Consistent naming makes it easier to: Reference Skills in documentation and conversations Understand what a Skill does at a glance Organize and search through multiple Skills Maintain a professional, cohesive skill library Writing effective descriptions The description field enables Skill discovery and should include both what the Skill does and when to use it. <Warning 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" </Warning Be specific and include key terms . Include both what the Skill does and specific triggers/contexts for when to use it. Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details. Effective examples: PDF Processing skill: Excel Analysis skill: Git Commit Helper skill: Avoid vague descriptions like these: Progressive disclosure patterns SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](docs.claude.com/en/docs/agents and tools/agent skills/overview how skills work) in the overview. Practical guidance: Keep SKILL.md body under 500 lines for optimal performance Split content into separate files when approaching this limit Use the patterns below to organize instructions, code, and resources effectively Visual overview: From simple to complex A basic Skill starts with just a SKILL.md file containing metadata and instructions: <img src="https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills simple file.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=87782ff239b297d9a9e8e1b72ed72db9" alt="Simple SKILL.md file showing YAML frontmatter and markdown body" data og width="2048" width="2048" data og height="1153" height="1153" data path="images/agent skills simple file.png" data optimize="true" data opv="3" srcset="https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills simple file.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c61cc33b6f5855809907f7fda94cd80e 280w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills simple file.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=90d2c0c1c76b36e8d485f49e0810dbfd 560w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills simple file.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=ad17d231ac7b0bea7e5b4d58fb4aeabb 840w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills simple file.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f5d0a7a3c668435bb0aee9a3a8f8c329 1100w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills simple file.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0e927c1af9de5799cfe557d12249f6e6 1650w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills simple file.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=46bbb1a51dd4c8202a470ac8c80a893d 2500w" / As your Skill grows, you can bundle additional content that Claude loads only when needed: <img src="https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills bundling content.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a5e0aa41e3d53985a7e3e43668a33ea3" alt="Bundling additional reference files like reference.md and forms.md." data og width="2048" width="2048" data og height="1327" height="1327" data path="images/agent skills bundling content.png" data optimize="true" data opv="3" srcset="https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills bundling content.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f8a0e73783e99b4a643d79eac86b70a2 280w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills bundling content.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=dc510a2a9d3f14359416b706f067904a 560w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills bundling content.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=82cd6286c966303f7dd914c28170e385 840w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills bundling content.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=56f3be36c77e4fe4b523df209a6824c6 1100w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills bundling content.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d22b5161b2075656417d56f41a74f3dd 1650w, https://mintcdn.com/anthropic claude docs/4Bny2bjzuGBK7o00/images/agent skills bundling content.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=3dd4bdd6850ffcc96c6c45fcb0acd6eb 2500w" / The complete Skill directory structure might look like this: Pattern 1: High level guide with references python import pdfplumber with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract text() Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed. Pattern 2: Domain specific organization For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales related schemas, not finance or marketing data. This keeps token usage low and context focused. bash grep i "revenue" reference/finance.md grep i "pipeline" reference/sales.md grep i "api usage" reference/product.md Pattern 3: Conditional details Show basic content, link to advanced content: Claude reads REDLINING.md or OOXML.md only when the user needs those features. Avoid deeply nested references Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like head 100 to preview content rather than reading entire files, resulting in incomplete information. Keep references one level deep from SKILL.md . All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed. Bad example: Too deep : Good example: One level deep : Structure longer reference files with table of contents For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads. Example : Claude can then read the complete file or jump to specific sections as needed. For details on how this filesystem based architecture enables progressive disclosure, see the [Runtime environment]( runtime environment) section in the Advanced section below. 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. Example 1: Research synthesis workflow (for Skills without code): Research Progress: [ ] Step 1: Read all source documents [ ] Step 2: Identify key themes [ ] Step 3: Cross reference claims [ ] Step 4: Create structured summary [ ] Step 5: Verify citations This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multi step process. Example 2: PDF form filling workflow (for Skills with code): Task Progress: [ ] Step 1: Analyze the form (run analyze form.py) [ ] Step 2: Create field mapping (edit fields.json) [ ] Step 3: Validate mapping (run validate fields.py) [ ] Step 4: Fill the form (run fill form.py) [ ] Step 5: Verify output (run verify output.py) Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi step workflows. Implement feedback loops Common pattern : Run validator → fix errors → repeat This pattern greatly improves output quality. Example 1: Style guide compliance (for Skills without code): This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\ GUIDE.md, and Claude performs the check by reading and comparing. Example 2: Document editing process (for Skills with code): The validation loop catches errors early. Content guidelines Avoid time sensitive information Don't include information that will become outdated: Bad example: Time sensitive (will become wrong): Good example (use "old patterns" section): The old patterns section provides historical context without cluttering the main content. Use consistent terminology Choose one term and use it throughout the Skill: Good Consistent : Always "API endpoint" Always "field" Always "extract" Bad Inconsistent : Mix "API endpoint", "URL", "API route", "path" Mix "field", "box", "element", "control" Mix "extract", "pull", "get", "retrieve" Consistency helps Claude understand and follow instructions. Common patterns

apply-anthropic-skill-best-practices