Agent Skill Best Practices

Core Principles

• Keep SKILL.md concise; Claude already knows basics.
• Write a specific, third-person description that includes what + when.
• Favor stable concepts over volatile paths and time-sensitive info.
• Use progressive disclosure: link to extra files from SKILL.md.
• Keep references one level deep to avoid partial reads.

Naming Guidance

• Use lowercase and hyphens; keep names short and descriptive.
• Prefer gerund names when possible (e.g., writing-docs).

Quality Checklist

• Description includes what + when, third-person.
• Body is short and avoids redundant context.
• Terminology is consistent.
• No brittle file paths unless they are stable interfaces.
• Examples match the intended output format.

Progressive Disclosure Tips

• For large skills, split reference docs and link from SKILL.md.
• Keep long files readable with a table of contents.
• Use scripts for deterministic work when needed.