# SKILL.md

> SKILL.md files package procedural knowledge for AI agents — loaded on demand when a task matches, instead of crowding every context window. How agent skills work, progressive disclosure, and how skills differ from prompts, CLAUDE.md, and MCP tools.

Source: https://metavert.io/SKILL.md  
Published: 2026-07-04  
Updated: 2026-10-24

**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](https://metavert.io/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](https://metavert.io/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](https://metavert.io/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](https://metavert.io/model-context-protocol) 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](https://metavert.io/markupmarkdown), for example, serves its agent guide live at [mumd.metavert.io/SKILL.md](https://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](https://metavert.io/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](https://metavert.io/how-to-write-a-SKILL.md).

## Related Topics

- [How to Write a SKILL.md](https://metavert.io/how-to-write-a-SKILL.md) — The practical guide
- [CLAUDE.md](https://metavert.io/CLAUDE.md) — Always-on instructions, vs. on-demand skills
- [Markdown](https://metavert.io/markdown) — The format skills are written in
- [Model Context Protocol](https://metavert.io/model-context-protocol) — Capabilities that skills teach agents to use well
- [Context Engineering](https://metavert.io/context-engineering) — Progressive disclosure is context engineering as file format
- [Claude Code](https://metavert.io/claude-code) — A primary consumer of skills
- [markupmarkdown](https://metavert.io/markupmarkdown) — Review skill files with your team and your agents
- [Docs as Code](https://metavert.io/docs-as-code) — The quality machinery for skill libraries
- [OpenMontage](https://metavert.io/openmontage) — A video production system built from 700+ skill and knowledge files

## Further Reading

- [Equipping Agents for the Real World with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic
- [Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) — Anthropic
- [anthropics/skills — open-source skill examples](https://github.com/anthropics/skills) — GitHub
- [markupmarkdown's live SKILL.md](https://mumd.metavert.io/SKILL.md) — a worked example of product-as-skill documentation