Skills Best Practices

Opinionated guide to building Agent Skills for any agent - distilled from the Agent Skills open standard, 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: