Writing Agent Skills

Workflow

1. Clarify the skill's purpose - What specific capability? When should it trigger?
2. Choose complexity level - Single file vs. multi-file based on content volume
3. Write the description first - This determines discoverability
4. Draft SKILL.md body - Keep under 500 lines
5. Split if needed - Extract to reference files for progressive disclosure

Quick Reference

Required Structure

---
name: skill-name-here
description: What it does and when to use it. Always third person.
---

# Skill Title

[Instructions go here]

Naming Rules

• Max 64 characters
• Lowercase letters, numbers, hyphens only
• No "anthropic" or "claude" in name
• Prefer gerund form: processing-pdfs, analyzing-code, writing-tests

Description Rules

• Max 1024 characters
• Third person only ("Processes files", not "I process files")
• Include WHAT it does AND WHEN to use it
• Include trigger keywords users might say

Key Principles

Concise is key - Context window is shared. Only add what Claude doesn't already know.

Match freedom to fragility:

• High freedom (text instructions) → Multiple valid approaches, context-dependent
• Medium freedom (pseudocode/templates) → Preferred pattern exists, some variation OK
• Low freedom (exact scripts) → Fragile operations, must follow precisely

Progressive disclosure - SKILL.md is the table of contents. Reference files for details.

Detailed References

• Structure & YAML requirements: See reference/structure.md
• Writing effective descriptions: See reference/descriptions.md
• Patterns (templates, workflows, examples): See reference/patterns.md
• Progressive disclosure & file organization: See reference/progressive-disclosure.md

Full Documentation

For comprehensive guidance, see the Anthropic docs in this project:

• agent-skills-overview.md - Architecture, how skills work
• agent-skills-best-practices.md - Complete authoring guide
• agent-skills-in-the-sdk.md - SDK integration

Checklist Before Finalizing

• Description includes WHAT and WHEN
• Description is third person
• Name uses lowercase/numbers/hyphens only
• SKILL.md body under 500 lines
• References are one level deep (not nested)
• No time-sensitive information
• Consistent terminology throughout