DEV Community

Neural Download
Neural Download

Posted on

Agent Skills Explained (Simply & Visually)

#agentskillsanthropicagentskill

https://www.youtube.com/watch?v=3yL8WbcwEXI

You wrote a skill. Then it didn't fire.

The prompt was right there. The folder was sitting in the right place. The agent just ignored it. And tweaking the wording didn't help.

This is one of the most common bugs with Anthropic's Agent Skills standard, and it almost always traces back to one wrong assumption: most devs treat the description field like a label. It's not. It's the router.

What an Agent Skill actually is

A skill is a folder. Inside that folder is one required file called SKILL.md. Everything else — extra docs, scripts, templates — is optional and lives in subfolders.

SKILL.md has YAML frontmatter at the top with two required fields: name and description. Below the frontmatter is plain markdown — the instructions the agent follows once the skill is active.

---
name: code-review
description: "Review pull requests — check naming, missing tests,"
  and security issues. Use this when the user pastes a diff or
  says "review this PR."
---

# Code Review Playbook

1. Read the diff.
2. Check naming rules.
3. Flag missing tests.
4. If anything touches auth, see references/security.md.
Enter fullscreen mode Exit fullscreen mode

That's it. A name, a description, a body. Anthropic's own example — the PDF skill — has the same shape.

The description is a router, not a tagline

When the agent starts up, it reads the name and description of every skill in your library. Just those two fields. About a hundred tokens per skill. That's the only thing the agent knows about a skill until something triggers it.

So when you type a prompt, the agent scans every description and decides: does this match? If your description for code-review says "helps with code," the agent has no idea when to fire it. Code is everywhere. It might fire on a typo question. It might miss an actual review request.

The fix is to write the description like a function signature for the agent's decision logic. Be specific about when, not just what. List the user phrasings that should trigger it. Anthropic ships an entire skill called skill-creator with a trigger evaluation loop just for tuning these.

Progressive disclosure: three loading layers

Once the agent decides to fire a skill, the second mechanism takes over. It's how the spec stays cheap as your library grows.

Layer 1 — Metadata. Name and description for every skill, always loaded, ~100 tokens each. Twenty skills cost you ~2,000 tokens of overhead. That's the price of having them available.

Layer 2 — Body. When the agent decides a skill matches, it reads the full SKILL.md into context. The spec recommends keeping this under 5,000 tokens, and Anthropic's best-practice guidance says aim for under 500 lines. That's the activation cost for one skill, paid every time it fires.

Layer 3 — References. Inside the body, you point to other files in references/, scripts/, or assets/. Those don't load until the body tells the agent to read them. Our code-review skill keeps a security checklist in references/security.md — that file only enters the conversation when the diff actually touches auth code.

The 500-line guideline isn't arbitrary. It nudges you to push detail outward. The body becomes a map; the references become the territory.

Skills are not MCP

If you've heard of MCP, you might be wondering where skills fit. They get conflated constantly. They shouldn't.

MCP exposes capabilities. Skills teach when and how to use them.

MCP is a protocol — it standardizes how an agent calls a tool. Your GitHub MCP server exposes "create issue," "list pulls," "post comment." The agent invokes those across a wire.

A skill doesn't expose a callable function. It teaches procedure — the order of steps, the team's conventions, what to do first.

The two compose. A code-review skill body might say "read the diff, check naming, then call the GitHub MCP tool to post the comment." The skill is the playbook; MCP is the hands. Anthropic describes a skill as "an onboarding guide for a new hire." MCP is what gets the new hire badged into the building.

What to do next

If your skill isn't firing, four things in order:

  1. Description is the router. Vague description, wrong routing. Add WHEN-clauses with the user phrasings that should trigger it.
  2. Body is the playbook. Loaded only when the description matches. Keep it under ~500 lines.
  3. References are the territory. Loaded only when the body says to load them. Push deep detail outward.
  4. Skills compose with MCP. They don't replace it. Skill bodies call MCP tools.

When you write your next skill, draft the description first. Before the body. Before a single instruction. Then test it — paste a prompt that should fire it, paste one that shouldn't, and watch which one the agent picks up. If it fires the wrong way, the description needs more WHEN, not more WHAT.

That's the spec. Description, body, references — composed with MCP. Go ship one that actually fires.

Top comments (0)