** 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 Docs2
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 areskill.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?.