What Is a SKILL.md File? The Field Manual

A SKILL.md file is a plain-text Markdown document that packages one repeatable procedure so an AI coding agent can load it on demand and run it like a field manual. Frontmatter up top declares the skill's name and a description of when to use it; the body below is the actual workflow — the steps, the checks, the gotchas. That's the whole idea: the description tells the agent when to requisition the skill, the body tells it what to do once it has it in hand. Skills are portable plain text — the same file works across Claude Code, claude.ai, and Codex — and the good ones ship with reference files, templates, and proof they hold up in the field.

Anatomy of a skill

Open any skill and you'll find the same layout. It's a folder, not a loose file, and SKILL.md sits at the top.

Frontmatter — the label on the crate. A YAML block with two fields that carry weight: name and description. The description is load-bearing. It isn't marketing copy; it's the trigger. The agent reads every installed skill's description, decides which job the current request maps to, and loads the body of the one that fits. A vague description is a skill that never gets pulled off the shelf. A sharp one names the exact situations — "use whenever building, auditing, or improving an iOS paywall, or diagnosing downloads-but-no-revenue" — so the match is unambiguous.

The workflow body — the manual itself. Everything under the frontmatter is plain Markdown: headings, numbered steps, tables, code blocks, decision gates. This is what the agent actually executes. Good bodies read like a procedure, not an essay — "run this grep first, then the compliance check, halt if the core isn't payable." Structure over prose.

references/ — the supplements. Longer reference material the agent pulls in only when a step needs it: a compliance checklist, an API's failure modes, a lookup table. Keeping it out of the main body keeps the skill lean — the agent loads the detail on demand instead of carrying it on every run.

templates/ and the rest of the crate. Fill-in-the-blank scaffolds (a dossier template, a config file), plus the housekeeping a shippable package carries: a QUICKSTART, a CHANGELOG so you can see what changed and when, a LICENSE. None of it is required by the format. All of it is what separates a maintained skill from a text file someone dumped in a repo.

Skill vs prompt vs MCP tool

Three different things, easy to conflate.

• A prompt is a single instruction you type once. It runs in the moment and it's gone — no structure, no reuse, nothing the agent decides to load on its own.
• A skill is a prompt's procedure, packaged and named so the agent loads it itself when the situation calls for it. It persists, it versions, it can carry references and templates. A prompt is a spoken order; a skill is the standing procedure in the manual.
• An MCP tool is a live capability — code behind a server the agent can call to do something in the world (query a database, hit an API, delete a record). A skill is knowledge; a tool is an action. A skill often tells the agent how and when to use tools; the tool is what actually fires.

Put plainly: the prompt is this turn's order, the skill is the field manual, the MCP tool is the equipment. Related, not interchangeable.

How an agent decides to use a skill

The agent doesn't run every skill it has. It reads the description of each one installed, matches the user's request against those descriptions, and loads only the body of the skill that fits — the way you'd scan crate labels before pulling the one you need. Then it follows the workflow inside.

Which is why the description does more work than any other line in the file. Selection is a matching problem, and the same failure modes that make an agent pick the wrong tool make it pick the wrong skill: overlapping scope, fuzzy boundaries, no "when to use" signal. That isn't hand-waving — it's exactly what MCP Tool Reliability Auditor measures. Its field report captures an agent mis-selecting between two tools with duplicate paths and no boundary text, then the rewrite that removes the collision. The same discipline — one clear job, an unambiguous when-to-use line — is what makes a skill get loaded at the right moment instead of the wrong one, or not at all.

What makes a skill actually good

Three things, and they're the same three whether it's a skill or any other gear an agent reaches for:

1. One job, scoped tight. A skill that tries to do everything gets loaded for nothing. "Audit an iOS paywall" is a job. "Help with apps" is not. Granular scope is what makes the description match cleanly.
2. Tested, not asserted. A workflow that's never been run is a guess in Markdown. Deep QA Audit Loop is a skill built out of what breaks — its field report documents a threshold bug guarded at one of thirteen call sites and shipped across two releases, plus the rule that got written back into the skill so the next run greps all thirteen. The lessons are in the file because they were paid for.
3. Documented so it holds up. A CHANGELOG, references the agent can pull on demand, honest notes on where it fails. Maintenance, not a one-time dump.

Here's the gap most of the market ignores. There are somewhere north of 2.2 million SKILL.md files floating around free directories, and almost none have been run in front of a witness. The label says it works. Nothing proves it. AgentSource ships a field report with every skill — real captured output from an actual run — so you can read what the skill did before you requisition it. iOS Paywall Playbook is the pattern: two documented App Store rejections are written into its compliance references because they happened, not because they read well in a spec. Every skill in the depot came out of a real app factory that shipped 15+ App Store apps. That's the difference between field-tested gear and surplus of unknown provenance.

Where skills run

A SKILL.md file is just Markdown. No runtime, no dependency, no lock-in — which is the point. The same file is compatible with Claude Code, claude.ai, and Codex; drop it in, and the agent reads the description and follows the body. Because it's plain text, it versions in git like any other source, it diffs in a pull request, and it moves between environments without a rewrite. You're not buying a binary. You're buying a procedure written down well enough that a machine can follow it — and portable enough to take with you.