Agent Skills: Recipe cards for your AI

👋 Easy read · Oct 16, 2026 · ~6 min read

Jargon jar: an agent does things, not just chats. A skill is a reusable recipe. The context window is everything the model can see at once. Progressive disclosure means you show the menu first, then the full recipe only when someone orders that dish.

Why skills keep coming up

Keep running into “skills” and feel like you missed the memo? You did not miss much, and this plate catches you up. Anthropic’s launch post and docs are the primary map (Anthropic: Agent Skills announcement, Claude docs: how Skills load).

Think of it as a kitchen habit that keeps resurfacing: "mise en place cards." The cards were always a good idea; the release notes and blog posts made them easy to share.

What changed is discoverability — a standard folder shape, a tiny startup cost, and a clear story for when to reach for a skill versus an MCP server.

Skills vs MCP vs "just put it in CLAUDE.md"

Skills = the recipe card. YAML frontmatter (name, description) plus instructions, optional scripts and reference files. Progressive disclosure: only the name and description load at startup; the body loads when a request matches (Claude docs: how Skills load).

MCP = the hands. The Model Context Protocol connects apps to tools and data. In Claude Code, a skill folder can even ship as a plugin that bundles its own MCP servers (Claude Code docs: using Skills).

CLAUDE.md = the house rules. Always-on project facts — not a skill. If you paste a 2,000-word essay into every chat, you are paying for the full recipe on every order. A skill keeps the title on the menu and brings the body out when needed.

Skills teach the moves. MCP gives new hands. Mixing them up is how you end up with 40 tools in context and an agent that still can’t find your deploy script.

What a skill folder actually contains

At minimum, a skill is a directory with a SKILL.md that has YAML frontmatter (name, description) and a markdown body. Optional files (scripts, reference docs, examples) sit beside it.

Anthropic’s overview walks the shape end-to-end (Claude docs: how Skills load), and Anthropic’s example skills on GitHub show real folders you can copy.

Analogy: the frontmatter is the card title and one-line blurb on a recipe box. The markdown body is the steps. Scripts are the pre-measured spice jars you only open when that recipe is on the stove. Reference files are the dog-eared cookbook pages you don’t want in every prompt.

Startup cost stays tiny because the agent indexes names and descriptions first (~100 tokens per skill in Anthropic’s framing). When your request matches a description, the full instructions load.

When the job is done, they leave the context — that is the progressive-disclosure bargain that makes a library of skills cheaper than one giant always-on prompt (Claude docs: how Skills load).

Try this in five minutes

1. Skim Anthropic’s Claude docs: how Skills load so the folder shape is clear.
2. Open a bundled skill folder (or copy one from Anthropic’s example skills on GitHub).
3. Ask your agent to do that job — watch whether it loads the skill on demand instead of inventing steps from scratch.
4. Optional: write a one-page skill for your weekly chore (changelog summary, PR triage, release notes). Keep the description specific enough that the matcher can find it.

You do not need to claim you "tested" anything in a lab — follow the official docs, use a skill you trust, and judge from the behavior in your own session.

Where skills show up (and where they don’t)

Skills on claude.ai, the API, and Claude Code are managed separately. A skill you install in one place does not magically appear in the others — treat each surface as its own pantry (Claude docs: where Skills work).

Cursor discovers skills in several folders (.claude/skills, .agents/skills, .codex/skills) per the Cursor CLI changelog: skill folders it scans. If a skill "vanishes," check which folder your tool actually scans before you rewrite the recipe.

Trust: only install skills you trust — they can run scripts. Prefer official or reviewed sources; treat random zip files like unmarked spice jars (Claude docs: Skills security). Anthropic’s advice is blunt: audit every file a skill bundles, scripts included, before you let it cook.

Common mix-ups (and how to unmix them)

• Skill vs MCP: if you need live tickets, a database, or a deploy button, you need hands (MCP). If you need the same careful procedure every Friday, you need a recipe (skill).
• Skill vs CLAUDE.md: house rules that always apply belong in CLAUDE.md. A workflow you only run sometimes belongs in a skill.
• Too many tools in context: dumping every MCP tool into every turn is how agents get lost. Skills keep know-how out of the way until matched; MCP tools should stay scoped to the job (MCP docs: what MCP connects).
• Vague descriptions: if every skill says "helps with coding," the matcher shrugs. Write descriptions like menu blurbs: what dish, for whom, when.

How this shows up in the wild

When a task matches a skill’s description, the agent pulls in the recipe — scripts, reference files, the works — then puts them away when the job is done.

That is why skills scale better than pasting the same essay into every prompt: you pay for the card title up front, and the full instructions only when you need them (Claude docs: how Skills load).

Teams that publish a small set of sharp skills (one per recurring workflow) tend to get clearer agent behavior than teams that bolt on another MCP server for every itch. Start with one recipe you already repeat weekly. Expand the drawer only when the next chore earns its own card.

Chef’s pick: write one skill for the workflow you repeat weekly. One recipe beats a drawer of gadgets.