# How to Write a SKILL.md > A practical guide to authoring SKILL.md files for AI agents: frontmatter and trigger descriptions, progressive disclosure structure, bundling scripts and references, testing skills against real tasks, and maintaining a skill library. Source: https://metavert.io/how-to-write-a-SKILL.md Published: 2026-07-04 Updated: 2026-07-04 A [SKILL.md](https://metavert.io/SKILL.md) packages procedural knowledge an agent should load *only when a task calls for it*. Writing one well is mostly about two things: a trigger description precise enough that the skill fires at the right moments, and a body organized so the agent pays for depth only when it needs depth. This guide covers both, plus the maintenance practices that keep a skill library trustworthy. ### The Frontmatter Is the Product A skill starts with YAML frontmatter, and the `description` field is the single most important line you'll write — it is all the agent sees when deciding whether to load the skill: ``` --- name: markupmarkdown description: Google-Docs-style commenting on markdown documents. Lets agents and human reviewers collaborate on the same docs — read, comment, reply, resolve threads, and trigger AI revisions of a doc based on comments humans have approved. --- ``` Write the description in terms of *tasks and trigger words*, not features: “Use when the user asks to review, comment on, or ship a markdown document” beats “A document collaboration tool.” If a skill fires too often, the description is too broad; too rarely, too narrow. Tune it like a search query — empirically. ### Structure for Progressive Disclosure Organize the body in descending order of necessity. First: the mental model in a few sentences — what the agent is operating on and the vocabulary it needs. Second: the workflows for the most common tasks, each as a short numbered sequence. Third: the reference material — and once reference material grows past a screen or two, move it to separate files the skill links to (`REFERENCE.md`, an API schema, example payloads). The agent reads linked files only when a task requires them, which keeps the routine case cheap. Bundled scripts follow the same rule: a deterministic operation (parsing, format conversion, API pagination) belongs in a script the agent *runs*, not prose it re-derives every session. ### Write for a Competent Stranger The agent reading your skill knows nothing you didn't write down, and it will follow what you did write with disconcerting literalness. Three habits pay off. **State preconditions** (“requires a token with write scope; get one from the avatar menu”). **Show one complete worked example** per workflow — a real request and a real response teach more reliably than any amount of description. **Mark the boundaries**: what the agent should never do with this skill (“never push without explicit human approval”), because a skill without stated limits inherits whatever ambient permissions the session has. ### Test It Like Software A skill's test suite is a set of real tasks. Run each with the skill installed and confirm: it triggered when it should, it didn't when it shouldn't, and the agent's behavior actually matched the instructions. When an agent misuses your product's API despite a skill, that's a bug report against the skill — fix the wording that misled it. Publishing a skill for a live product? Serve it from the product itself so it can't drift from the deployment — [markupmarkdown](https://metavert.io/markupmarkdown) embeds its SKILL.md in the server binary and serves it at [/SKILL.md](https://mumd.metavert.io/SKILL.md), with a build-time test that fails when the repo copy and the embedded copy diverge. ### Maintain the Library Skill edits change agent behavior everywhere, so review them like code and prose at once: threaded comments on the exact sentence at issue, suggested edits applied in one click, [checks](https://metavert.io/docs-as-code) that required sections exist and placeholder text doesn't, and a human approval gate before publication. That is the [markupmarkdown](https://metavert.io/markupmarkdown) loop — and since a skill library is just a folder of markdown in a repo, its markdown indexes give you the whole library on one reviewable page. ## Related Topics - [SKILL.md](https://metavert.io/SKILL.md) — The concept page - [How to Write a CLAUDE.md](https://metavert.io/how-to-write-a-CLAUDE.md) — The sibling guide for standing instructions - [Markdown](https://metavert.io/markdown) — The format and why it won - [Context Engineering](https://metavert.io/context-engineering) — Progressive disclosure in depth - [Model Context Protocol](https://metavert.io/model-context-protocol) — The capability layer skills teach - [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 ## 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 - [Skill Authoring Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) — Anthropic - [anthropics/skills — worked examples](https://github.com/anthropics/skills) — GitHub - [markupmarkdown's live SKILL.md](https://mumd.metavert.io/SKILL.md) — product-as-skill in practice