What Is skill.md? A Practical Guide for Agent-Ready Docs

skill.md is a small markdown file that tells an agent how to use your product without guessing. That is the short version.

If llms.txt is the map, skill.md is the playbook.

It is not meant to replace your documentation. It is not meant to duplicate your sitemap. It is not an MCP server. It is a compact set of instructions that helps an agent choose the right docs path, avoid common mistakes, and understand the boundaries of your product.

That matters because most documentation is still written for humans who browse. Agents do not browse very well. They do much better when you tell them where to start and what not to assume.

If you want the long implementation story, read our original skill.md post. This one is the practical answer to the question people actually type into search: what is skill.md, and why does it exist?

What skill.md Is

skill.md is an agent-facing instruction file.

A good one usually tells the agent:

• what the docs set is for
• which workflows matter most
• which pages to read first
• what the product can and cannot do
• which sources are canonical

That is it.

The file does not need to be long. In many cases, shorter is better. The point is not to compress your whole docs site into one markdown file. The point is to give the model a better starting position.

A minimal example:

1# Acme API Docs
2
3Use this skill when working with authentication, webhooks, rate limits,
4and Node SDK integrations for Acme.
5
6Start with `/quickstart` for first requests.
7Use `/authentication` for API keys and OAuth.
8Use `/errors` and `/rate-limits` before writing retry logic.
9
10Do not invent undocumented webhook payload fields.

That is already enough to improve how an agent approaches the docs.

Why skill.md Exists

The problem is not that models cannot read documentation.

The problem is that they often read the wrong page first.

That happens because most docs sites are optimized for:

• navigation trees
• search boxes
• human skimming
• broad reference coverage

Those are good things. But they do not tell an agent which page is the best first move for a task.

Take a typical API docs site. It might have:

• a quickstart
• an auth guide
• a webhooks section
• an API reference
• SDK docs
• troubleshooting pages

Humans infer the order over time. Agents often do not. They jump into the reference docs and then improvise.

skill.md exists to reduce that improvisation.

What skill.md Is Not

It is easier to understand the file if you also understand what it is not.

It is not:

• a replacement for full documentation
• a replacement for llms.txt
• a replacement for MCP
• a giant export of your nav tree
• a marketing overview of your company

This is where a lot of weak skill.md files go wrong. They read like launch copy or product descriptions when they should read like an internal operating note.

Bad:

1Acme is a modern, scalable developer platform that helps teams move faster.

Better:

1Use `/quickstart` before `/api-reference`.
2Use `/authentication` before writing OAuth flows.
3Do not assume sandbox behavior matches production limits.

One of these gives the model something actionable. The other gives it vibes.

skill.md vs llms.txt

The cleanest distinction is:

• llms.txt says where the docs are
• skill.md says how to use them

llms.txt is a curated index. It points to important pages.

skill.md adds routing and judgment:

• start here
• prefer this page over that one
• do not mix these surfaces
• watch out for this failure mode

That is why the two work well together instead of replacing each other.

If you want the full comparison, there is a separate post coming for skill.md vs llms.txt. The short version is that one is a map and the other is a playbook.

skill.md vs MCP

This distinction matters too.

MCP gives an agent tools. skill.md gives it instructions.

An MCP server might let the model search docs, execute actions, or fetch live data.

skill.md tells the model things like:

• when to use a tool
• which docs surface is authoritative
• which workflow to prefer
• which assumptions are unsafe

MCP gives an agent hands. skill.md gives it judgment.

That is why a product can reasonably have all three:

• docs
• llms.txt
• skill.md
• and maybe MCP on top

They solve different layers of the same problem.

What Goes Into a Good skill.md

A good file usually contains four things:

1. A Tight Description

Not branding. Just enough to establish scope.

Example:

1Use this skill when working with Acme authentication, SDK setup, webhooks,
2and API error handling.

2. A Start Order

This is often the highest-value part.

Example:

1Start with `/quickstart`.
2Read `/authentication` before writing OAuth logic.
3Read `/errors` before implementing retries.

3. A Small Decision Layer

This can be prose or a table.

1| Need | Read |
2|------|------|
3| First request | `/quickstart` |
4| API keys or OAuth | `/authentication` |
5| Webhooks | `/webhooks/overview` |
6| Request fields | `/api-reference` |

4. Boundaries

This is the part teams skip, and it matters a lot.

Example:

1- Do not invent undocumented fields.
2- Prefer canonical docs over examples copied from blog posts.
3- Use Node SDK examples only when the task is Node-specific.

That is enough to materially improve agent behavior.

When You Probably Need One

You probably need skill.md if:

• your docs have multiple surfaces
• the quickstart is not obvious from the nav alone
• agents frequently jump into the wrong part of the docs
• your product has hidden workflow constraints
• your API, SDK, and CLI docs get mixed together

You probably do not need an elaborate one if your product is tiny, your docs are extremely linear, and the correct path is obvious.

The point is not to comply with a trend. The point is to remove ambiguity where ambiguity hurts agent quality.

The Practical Takeaway

skill.md is a small file with a narrow job:

help the agent make fewer bad decisions.

That usually means:

• less branding
• fewer words
• clearer page paths
• more explicit boundaries

If your docs already exist, skill.md is usually not a huge new system. It is a thin layer of judgment on top of the docs you already have.

That is why it is useful. Not because it is magical, but because most docs leave too much routing work for the model to infer on its own.

If you want concrete templates, read skill.md Examples. If you want install and discovery paths, read Where Does skill.md Live?.