SKILL.md

SKILL.md is the file convention for packaging agent skills: self-contained bundles of procedural knowledge that an AI agent loads on demand when a task calls for them, rather than carrying in every session. Where a CLAUDE.md is always-on standing instruction (“here is how this project works”), a skill is situational expertise (“here is how to fill out a PDF form,” “here is how to review a document in our house style,” “here is how to talk to this product's API”). The convention was introduced by Anthropic for Claude and formalized as a folder containing a markdown file with YAML frontmatter — a name, a description that tells the agent when the skill applies, and a body of instructions, optionally alongside scripts and reference files the skill can invoke.

Progressive Disclosure

The load-bearing idea in the skills design is progressive disclosure. An agent with fifty skills doesn't read fifty documents at startup — it reads fifty one-line descriptions. Only when a task matches does the full SKILL.md enter the context window, and only if that file points to deeper references (a REFERENCE.md, an API schema, a script) do those load too. This is context engineering as a file format: expertise organized so that the token cost of knowledge is paid exactly when the knowledge is needed. It's also why skills scale where mega-prompts don't — a skill library grows without inflating the cost of every unrelated task.

Skills vs. Prompts vs. Tools

Three mechanisms are often confused. A prompt is a one-shot instruction: ephemeral, unversioned. A tool (via MCP or function calling) gives an agent a new capability — something it couldn't do at all before, like querying a database. A skill gives an agent new competence — knowing how and when to use the capabilities it already has, in your preferred way. The three compose: a well-built product exposes tools via MCP and ships a SKILL.md teaching agents the idioms of using them well. markupmarkdown, for example, serves its agent guide live at mumd.metavert.io/SKILL.md — the same file is embedded in the server binary and versioned in the repo, so the published guidance can never drift from the deployed product. That pattern — SKILL.md as a product's public API documentation for agents — is becoming standard practice for agent-ready software.

Skills Are Software

Because a skill changes agent behavior wherever it's installed, it deserves the lifecycle of software: versioning, review, testing against real tasks, and deliberate rollout. A subtle wording change in a skill's description changes when it triggers; a stale instruction inside one propagates mistakes at scale. Teams that maintain skill libraries increasingly review them the way they review code — which, since skills are markdown, is exactly the docs-as-code workflow: threaded review, suggested edits, checks for required sections and banned placeholder text, and gated publication. A practical authoring guide lives at How to Write a SKILL.md.