Skills (SKILL.md)
A skill is a reusable agent capability defined by a SKILL.md file in a known directory (~/.claude/skills/<name>/SKILL.md or .claude/skills/<name>/SKILL.md). The SKILL.md has YAML frontmatter (name, description, optional fields like allowed-tools and model) and a body of instructions. Invoked via /name or the Skill tool.
Skills are tools in a toolbox — the toolbox stays in the truck (skills directory), you pull out the right tool when the job asks for it. CLAUDE.md is the safety vest you always wear.
Skill structure: frontmatter (YAML: name, description, model preference) + markdown body with instructions, examples, expected inputs/outputs. The 'description' field is critical — it's what the model uses to decide when to invoke the skill. Skills can ship with helper files (templates, scripts) in the skill directory; the SKILL.md can reference them. Skills are loaded into context only when invoked — they don't bloat the base prompt. Skills can call other skills.
Skills vs prompts: a prompt is one-shot, a skill is reusable across sessions and discoverable. The 'description' is matched against user intent when the harness suggests skills; weak descriptions = skills don't fire. Skills can be triggered by users (slash command), by the model (Skill tool), or by hooks (programmatically). Sandbox: skills can specify allowed tools, model preferences, and isolation modes. Plugin namespacing: plugins ship skills under their plugin name, accessed as /plugin:skill. Skill files participate in prompt caching — stable skills get cache benefits.
Skills are reusable agent capabilities defined in SKILL.md files. Each skill has YAML frontmatter (name, description, optional fields like allowed-tools and model) and a body of instructions, optionally with helper scripts. Skills are loaded only when invoked — unlike CLAUDE.md they don't bloat every prompt. The description field is the most important piece because it's what the model matches against user intent. Skills are how I encode 'how we do X' — code review, security audits, deployment runbooks — without making every session pay for them in tokens.
Writing skills that duplicate CLAUDE.md content. CLAUDE.md is for always-on rules; skills are for on-demand workflows. If you find yourself invoking a skill on every session, it probably belongs in CLAUDE.md.