apply-anthropic-skill-best-practices

Write the description in third person, stating both what the skill does and when to use it, with specific trigger keywords. Avoid vague phrases like "helps with documents" and first- or second-person phrasing, since the description is injected into the system prompt for skill selection.

Keep the SKILL.md body under 500 lines for optimal performance. When approaching that limit, split content into separate reference files linked directly from SKILL.md so the agent loads details only when needed.

Use gerund form (verb + -ing), such as "Processing PDFs" or "Analyzing spreadsheets". Noun phrases and action-oriented names are acceptable alternatives, but avoid vague names like "Helper" or "Utils" and keep naming consistent across your skill collection.

Avoid nesting references more than one level deep from SKILL.md. Agents may partially read deeply nested files using preview commands, resulting in incomplete information. Link all reference files directly from SKILL.md.

Use evaluation-driven development: create test scenarios before writing documentation, establish a baseline without the skill, then iterate. Test with every model you plan to use, since instructions that work for a powerful model may lack detail needed by a faster one.

Scripts should handle error conditions explicitly, such as creating missing files or falling back to defaults, rather than throwing errors back to the agent. This "solve, don't punt" pattern keeps workflows deterministic and avoids forcing the agent to guess recovery steps.