skills-best-practices

# Skills Best Practices Comprehensive reference for building Agent Skills that follow Anthropic's official guidelines. Skills are folders containing instructions, scripts, and resources that teach Claude how to handle specific tasks. They follow the [Agent Skills open standard](https://agentskills.io). ## 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 ### Progressive Disclosure (Most Important) Skills load information in three levels to minimize token usage: | Level | When Loaded | Token Cost | Content | |-------|------------|------------|---------| | **1: Metadata** | Always (startup) | ~100 tokens | `name` + `description` from frontmatter | | **2: Instructions** | When skill triggers | <5k tokens (recommended) | SKILL.md body | | **3: Resources** | As needed | Effectively unlimited | Bundled files, scripts | Keep SKILL.md under **500 lines**. Move detailed docs to separate files and reference them: ```markdown ## Advanced features - **Form filling...