Guide

What is a Claude skill?

A Claude skill is a SKILL.md file — markdown instructions with YAML frontmatter, plus optional scripts and resources — that the agent loads automatically when the skill’s description matches the task. It teaches the agent how to do something well and consistently, without you re-explaining it each time. The format is cross-agent: the same SKILL.md runs in Claude Code, Cursor, Codex, Gemini CLI, and Antigravity.

The whole point is selective loading. A skill announces itself with a short description; the agent only pulls in the full instructions when they are relevant, so your context window is not permanently spent on capabilities you are not using.

How they load

Three tiers, progressive disclosure

1
Tier 1 — Metadata (always loaded)
The name and description from the SKILL.md frontmatter, roughly 100 tokens, stay in context. The agent scans these to decide whether a skill is relevant. A weak description is the single biggest reason a skill never triggers.
2
Tier 2 — Instructions (loaded on trigger)
When the description matches the task, the agent loads the markdown body of the SKILL.md — the actual instructions — typically under 5K tokens. Once loaded, it stays in context across turns, so every line is a recurring token cost.
3
Tier 3 — Bundled files (loaded on demand)
Scripts, reference docs, and templates the skill ships are only read when the instructions call for them. This progressive disclosure keeps the agent efficient — it never pays for what it does not use.

What’s inside

A minimal SKILL.md

Only name and description are required by the spec. The description is the field that decides whether the skill ever triggers.

---
name: pdf-form-filler
description: Fill, flatten, and extract fields from PDF forms.
  Use when the user mentions filling a PDF, AcroForm fields,
  or merging data into a PDF template.
---

# PDF form filler

When filling a PDF form:
1. Inspect the AcroForm field names with the bundled script.
2. Map the user's data to those field names.
3. Fill, then flatten so values are not editable.
...

For the full pattern — frontmatter fields, when to add scripts, how to write a description that triggers reliably — see the anatomy of a SKILL.md.