skills-best-practices

# Skills Best Practices Opinionated guide to building Agent Skills for any agent - distilled from the [Agent Skills open standard](https://agentskills.io), Anthropic's official guidance, and production experience, with deviations from the official line marked where they occur. Skills are folders (often just a single file) containing instructions, scripts, and resources that teach an agent how to handle specific tasks. ## Quick Start A minimal skill is a directory with a `SKILL.md` file: ``` my-skill/ ├── SKILL.md # Required - instructions with YAML frontmatter ├── references/ # Optional - detailed docs loaded on demand ├── scripts/ # Optional - executable code └── assets/ # Optional - templates, fonts, icons ``` Minimal `SKILL.md`: ```yaml --- name: my-skill-name description: What it does. Use when [specific triggers]. --- # My Skill Name [Instructions here] ``` Only `name` and `description` are required in frontmatter. ## Core Design Principles ### Single File vs. references/ (Most Important) **Default to a single SKILL.md.** One file can be pasted to a person, gisted, embedded in a CLI binary, and printed by a `<tool> skill` subcommand - a directory cannot. Split into `references/` only when **both** hold: 1. **Conditional loading**: a meaningful chunk of content is needed by only a subset of invocations (e.g. a tracked-changes doc most DOCX tasks never touch). If every invocation reads everything anyway, splitting adds Read ro...