skill.md vs llms.txt: What Each File Does and When You Need Both<br>← Back to blog/Engineering<br>skill.md vs llms.txt: What Each File Does and When You Need Both<br>llms.txt and skill.md solve different problems. One is a map of your docs. The other is a compact playbook for how an agent should use them.<br>Faizan Khan<br>2026-06-04 • 8 min read
A lot of teams treat llms.txt and skill.md like competing standards. They are not. They sit at different layers.
The cleanest distinction is:
llms.txt tells the model where the important docs are
skill.md tells the model how to use them
One is a map. The other is a playbook.
That sounds simple, but it clears up most of the confusion around whether you need both.
If you want the longer background on either file, read What Is llms.txt? and our skill.md guide. This post is the comparison layer.
The Short Version
Here is the practical difference:
llms.txtskill.mdMain jobCurated discoveryAgent routing and judgmentShapeIndex of useful docs pagesCompact instruction fileBest forPointing models at the right pagesHelping models make fewer bad choicesTypical contentImportant links and short descriptionsStart order, decision rules, boundariesFailure if missingThe agent has to guess where the useful docs liveThe agent finds docs but reads them in a bad order
If you only publish llms.txt, the model may know which pages exist but still use them badly.
If you only publish skill.md, the model may get good instructions but still lack a broad map of the docs.
That is why they complement each other.
What llms.txt Is Good At
llms.txt works well when the hard problem is discovery.
It answers questions like:
what are the important pages on this docs site?
where is the quickstart?
which SDK pages are canonical?
which docs sections matter most?
A simple llms.txt file might look like this:
Markdown<br>Copy<br>1# Acme Docs
3## Start Here
5- [Quickstart](https://docs.acme.com/quickstart)<br>6- [Authentication](https://docs.acme.com/authentication)<br>7- [Errors](https://docs.acme.com/errors)
9## SDKs<br>10
11- [Node SDK](https://docs.acme.com/sdks/node)<br>12- [Python SDK](https://docs.acme.com/sdks/python)
That is useful because it gives the model a curated starting map.
But it does not tell the model:
whether to prefer SDK docs over raw REST docs
which docs surface applies to a given task
which assumptions are unsafe
what mistakes to avoid
That is where skill.md comes in.
What skill.md Is Good At
skill.md works well when the hard problem is judgment.
It answers questions like:
which page should I read first?
when should I use the SDK docs instead of the API reference?
what part of the docs is canonical for this workflow?
what should I not assume?
A simple skill.md file might look like this:
Markdown<br>Copy<br>1# Acme API Docs
3Read `/quickstart` before `/api-reference`.<br>4Read `/authentication` before implementing OAuth.<br>5Use `/sdks/node` for Node-specific tasks instead of REST examples.
7Do not invent undocumented webhook fields.
This is not a map of the whole docs site. It is a small operating note that makes the model less likely to go wrong.
That is the core distinction.
Discovery vs Judgment
Another way to say it:
llms.txt helps the model discover
skill.md helps the model choose
Discovery without judgment is incomplete.
Judgment without discovery is narrow.
You can see this pretty clearly in real failure modes.
Failure mode with only llms.txt
The model finds:
/quickstart
/authentication
/api-reference
/errors
That is good.
But it may still jump into the reference docs first, skip the quickstart, and then build on the wrong assumptions.
Failure mode with only skill.md
The model knows:
start with the quickstart
prefer SDK docs for language-specific work
do not invent undocumented flags
Also good.
But if it needs broader discovery across the docs set, the file may not give enough coverage on its own.
That is why the two files reinforce each other rather than competing.
When You Only Need One
You do not always need both on day one.
Start with llms.txt if:
your main problem is discoverability
your docs site is large or messy
the hard part is just surfacing the right pages
Start with skill.md if:
the model usually finds the docs but uses them badly
the same mistakes keep repeating
your product has multiple surfaces or non-obvious workflow order
Ship both if:
you have a real docs program
you care about agent quality, not just discoverability
your API, SDK, CLI, or help-center docs have different roles
For most serious developer-docs setups, both is the right long-term answer.
Why They Feel Similar
They can feel similar because both are short, agent-facing files and both often sit next to the docs.
But their useful content is different.
Good llms.txt content:
page lists
section groupings
canonical entry points
Good skill.md content:
start order
decision rules
boundaries
workflow-specific warnings
If your skill.md just restates your...