Skills Directory / Guides

How to write a Claude Code skill

A skill is a folder with a SKILL.md file. The format takes five minutes to learn; writing skills that actually change agent behavior takes a bit more. Both are covered here.

The anatomy

my-skill/
  SKILL.md          # required: frontmatter + instructions
  references/       # optional: deep docs, loaded on demand
  scripts/          # optional: helper scripts the skill invokes
  assets/           # optional: templates, examples

The frontmatter

Two required fields:

• name — unique identifier, lowercase with hyphens.
• description — the most important line in the file. The agent reads only this at startup and matches tasks against it. State what the skill does and when to use it: "…Use when reviewing Worker code, configuring wrangler.jsonc, or checking for Workers anti-patterns."

A weak description means the skill never loads; an over-broad one means it loads constantly and wastes context. Look at how Cloudflare's wrangler skill or Superpowers' TDD skill write theirs — specific triggers, explicit verbs.

Starter template

---
name: my-skill-name
description: What this skill does and when to use it. Use when [trigger conditions — be specific, the agent matches tasks against this line].
---

# My Skill Name

## When to use
One paragraph on the exact situations this applies to (and when NOT to).

## Steps
1. Numbered, concrete steps with exact commands.
2. Include expected output so the agent can verify.
3. Branch points: "If X, do Y; otherwise Z."

## Pitfalls
- The mistakes this skill exists to prevent, stated bluntly.

## Verification
How to confirm the task actually succeeded.

What separates good skills from filler

• Encode decisions, not descriptions. "Prefer JSON config over TOML; newer features are JSON-only" beats a paragraph about configuration formats.
• Exact commands with expected output. The agent should be able to verify each step landed.
• Pitfalls section. The single highest-value content: the mistakes you've already made, so the agent doesn't repeat them.
• Progressive disclosure. Keep SKILL.md lean; push API references and long tables into references/ files the skill points to. The agent reads them only when needed.
• Bias to retrieval for volatile facts. CLI flags and API shapes go stale. The best vendor skills (Cloudflare's, for instance) tell the agent to fetch current docs rather than trusting baked-in knowledge.

Checklist before publishing

1. Description states trigger conditions ("Use when…")
2. Steps are numbered and copy-paste executable
3. Pitfalls section exists and is honest
4. Verification step included
5. Under ~500 lines; deep material moved to references/
6. Tested: fresh session, real task, skill actually loaded and changed the outcome

The formal spec lives at agentskills.io, and Anthropic's official repo ships a template plus production examples worth reading before your first attempt.

FAQ

What is the SKILL.md format?

A markdown file with YAML frontmatter. The frontmatter requires two fields — name (lowercase, hyphens) and description (when to use the skill). The markdown body contains the instructions the agent follows. The skill lives in its own folder, optionally with references/, scripts/, and assets/ subfolders.

What goes in SKILL.md frontmatter?

Required: name and description. The description is the most important line in the file — the agent reads it to decide when to load the skill, so it should state both what the skill does and the trigger conditions ('Use when...').

What is the difference between SKILL.md and AGENTS.md?

AGENTS.md (and CLAUDE.md) are always-loaded project context files — conventions the agent should permanently know in a repo. SKILL.md files are on-demand: loaded only when the task matches the description. Put stable project facts in AGENTS.md; put workflows and procedures in skills.

How long should a skill be?

The body should be as short as it can be while still changing behavior — a few hundred lines is typical. Move deep reference material into references/ files that the skill tells the agent to read when needed (progressive disclosure), keeping the always-loaded surface small.

See how the pros do it: browse 195+ real skills in the directory, or read skills vs plugins vs MCP to understand where skills fit.