Anthropic Releases Official Best Practices for Agent Skill Authoring

Anthropic has updated its documentation with official best practices for authoring agent skills, emphasizing structure, naming conventions, and testing methodologies to improve model performance.

Naming and Structure

The guide advises naming skills with gerunds (e.g., processing-pdfs) rather than generic nouns like utils or data, as this clearly describes the skill's function. While noun phrases or action names are acceptable, consistency across the library is required. For file organization, references should be kept one level deep; linking directly from SKILL.md is preferred over chained links, which may result in Claude only previewing the first 100 characters of subsequent files. Subfolders are permitted, but deep link chains are not.

Content Optimization

To ensure agents recognize relevance, the guide suggests placing a table of contents at the top of files if critical information appears later (e.g., line 350), as agents may only read the first 100 lines to determine if a file is worth processing. The description field is treated as the primary product interface; it must be written in the third person, explicitly stating what the skill does and when to use it, including key terms users are likely to search for. This is critical because the description is always loaded, allowing Claude to select the correct skill from potentially over 100 options.

Development and Testing

Anthropic recommends evaluation-driven development over "vibe checking." Developers should first run Claude on a task without the skill to establish a baseline and identify failure points, then build minimal test scenarios to measure improvements. Since there is no built-in evaluation tool yet, developers must create their own. Additionally, the principle of progressive disclosure is highlighted: only the name and description should sit in the system prompt at startup, with SKILL.md loading only when relevant and extra files loading only when needed. SKILL.md should remain under 500 lines. Finally, skills must be tested on every target model, as performance may vary between models like Opus and Haiku.