Agent Skills in plain English: 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 (Anthropic docs). Progressive disclosure means you show the menu first, then the full recipe only when someone orders that dish.

Why everyone is talking about skills this week

Over the last week, posts about Agent Skills and Claude skills flooded developer timelines (thousands of public posts on X mentioning Agent Skills / Claude skills between Oct 9–15, 2026 — volume we measured via X recent search counts). Anthropic’s own explainer and docs are the primary map (Claude blog: Skills, Agent Skills overview).

Think of the hype wave as a kitchen trend: suddenly every cooking show is talking about "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 (Agent Skills overview).

MCP = the hands. The Model Context Protocol connects apps to tools and data. Claude Code can even load skills listed by an MCP server, checking size and SHA-256 before trust (Claude Code v2.1.299 notes).

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 (Agent Skills overview); the public anthropics/skills repo shows 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 (Agent Skills overview).

Try this in five minutes

1. Skim Anthropic’s Skills overview so the folder shape is clear.
2. Open a bundled skill folder (or copy one from anthropics/skills).
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 (Anthropic guidance).

Cursor discovers skills in several folders (.claude/skills, .agents/skills, .codex/skills) per the Cursor CLI changelog. 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 (Anthropic guidance). Claude Code’s skill-from-MCP path adds size and SHA-256 checks before load (v2.1.299) — still not a substitute for reading what you install.

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 intro).
• 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 (Agent Skills overview).

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.

Source: platform.claude.com · context windows · overview · claude.com · skills · modelcontextprotocol.io · intro · github.com · v2.1.299 · anthropics/skills · cursor.com · changelog