You've explained your pull-request format to an agent four times this week. The bullet order, the "Why" section before the "What," the line that links the issue. It works every time, and every time you type it again. A Skill is how you stop.

If you read one thing: a Skill is a folder with a SKILL.md file inside it — YAML frontmatter (name and description) plus a Markdown body of instructions — and the agent pulls it in automatically whenever your request matches the description. Write your workflow down once; the agent repeats it without you re-prompting.

What a Skill actually is#

Per Anthropic's Agent Skills docs, a Skill is a filesystem resource: a directory whose required core is a single SKILL.md. That file has two parts:

That's the whole minimum. Optionally, the folder can also carry scripts (validate.py), templates, and extra reference files (REFERENCE.md, FORMS.md) that the agent only opens when it needs them.

Why the format is built this way: progressive disclosure#

The reason a Skill is a folder and not one giant prompt is a loading trick the docs call progressive disclosure. Content loads in three tiers, each at a different moment:

  1. Metadata (always loaded). At startup, only each skill's name and description go into the system prompt — roughly 100 tokens per skill. This is what the agent scans to decide whether a skill is relevant.
  2. Instructions (loaded on trigger). When your request matches the description, the agent reads the SKILL.md body into context. Anthropic recommends keeping it under 500 lines / under ~5k tokens.
  3. Resources (loaded as needed). Bundled files load only when the body references them; bundled scripts run via bash and only their output enters context — the code itself never does.

The math is the point. Install eight skills and startup costs you a few hundred tokens of metadata — not the ~70,000 you'd pay if every full skill loaded up front. You can keep a big library of skills installed and pay almost nothing until one actually fires. (If you're weighing this against tool-based approaches, see our take on how MCP moved to a stateless model — Skills and MCP solve different halves of the same problem.)

The one rule that makes or breaks a skill: the description is a trigger#

This is where most first skills fail. The best-practices guide is blunt: the description is the only thing the agent sees at startup, so it must say both what the skill does and when to use it — written in the third person, packed with the concrete keywords a request would contain.

The strong version names the triggers ("opens a PR," "PR description," "summarize a diff") the agent can match against. Think of it as SEO for your own agent.

Build it: a writing-pr-descriptions skill, start to finish#

Let's ship a real one. Anthropic suggests gerund-form names, so we'll call it writing-pr-descriptions.

Step 1 — Make the folder. In a repo, project skills live in .claude/skills/; personal ones live in ~/.claude/skills/.

.claude/skills/
└── writing-pr-descriptions/
    ├── SKILL.md          # frontmatter + instructions (loaded on trigger)
    └── examples.md       # good/bad PR bodies (loaded only if referenced)

Step 2 — Write SKILL.md. Here's a complete, minimal version:

---
name: writing-pr-descriptions
description: Writes pull-request descriptions in our house format. Use when the user opens a PR, asks for a PR description, or wants to summarize a staged diff for review.
---

# Writing PR descriptions

Generate a PR description from the diff. Always follow this structure.

## Structure

Why#

[One or two sentences: the problem or motivation. Link the issue as Closes #NNN.]

What changed#

How to test#

  1. [Concrete steps a reviewer can run]

Risk#

[Blast radius + rollback note. Write "Low — isolated change" if trivial.]


## Rules

- Lead "Why" with the user impact, not the implementation.
- List breaking changes in **What changed** with a **BREAKING:** prefix.
- Never invent test steps you can't derive from the diff. If unclear, say so.

For tricky cases (large refactors, revert PRs), see [examples.md](examples.md).

Two things worth copying here. First, the body is short — it assumes the model already knows what a PR is and only encodes your conventions. Second, it defers the long stuff: examples.md only loads if the agent hits a tricky case, keeping the common path cheap.

Step 3 — Trigger it. In Claude Code, the skill is discovered automatically — ask "write a PR description for my staged changes" and the description match fires it. You can also run it explicitly with /writing-pr-descriptions.

Step 4 — Iterate. The docs recommend building your skill with an agent: complete the task once by hand, notice what you kept re-explaining, then ask the agent to capture it as a skill. Watch where it goes wrong on the next real PR and tighten the wording — "always filter" becomes "MUST filter."

Optional frontmatter you'll reach for in Claude Code#

The core standard only defines name and description. Claude Code extends it with a few optional fields — handy, but tool-specific, so leave them out if you want maximum portability:

Distribution: one file, many tools#

You have a working folder. Now put it to work:

The bigger unlock: SKILL.md is an open standard. Claude Code notes it follows the Agent Skills spec, "which works across multiple AI tools" — so the same folder runs in Cursor, Gemini CLI, and Codex too, each with its own install path. Your writing-pr-descriptions skill isn't locked to one vendor; it follows you across your stack. If you're mapping that stack, our agent framework roundup covers where the standards are converging.

This portability is also why the format is having a moment — Anthropic and DeepLearning.AI shipped a full Agent Skills course in early 2026, and "agent skills" has become the default way builders describe teaching an agent a repeatable job.

The takeaway#

A Skill is the cheapest reliability upgrade you can give an agent: write your workflow down once, in Markdown, and it stops drifting every time you re-ask. Start with the one procedure you re-type most — a PR format, a changelog style, a support-reply tone — keep the SKILL.md body under 500 lines, and make the description a real trigger. Next step: pick that one workflow, mkdir .claude/skills/your-skill, and paste the template above.