skill.md vs llms.txt: What Each File Does and When You Need Both

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:

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:

1# Acme Docs
2
3## Start Here
4
5- [Quickstart](https://docs.acme.com/quickstart)
6- [Authentication](https://docs.acme.com/authentication)
7- [Errors](https://docs.acme.com/errors)
8
9## SDKs
10
11- [Node SDK](https://docs.acme.com/sdks/node)
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:

1# Acme API Docs
2
3Read `/quickstart` before `/api-reference`.
4Read `/authentication` before implementing OAuth.
5Use `/sdks/node` for Node-specific tasks instead of REST examples.
6
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 llms.txt, it is probably weak.

If your llms.txt tries to do all the routing and best-practice work of skill.md, it is probably getting overloaded.

A Better Mental Model

If you want a stack that makes sense, think about the files like this:

1. docs content: the actual source of truth
2. llms.txt: the curated map
3. skill.md: the agent playbook
4. MCP, if relevant: live tools and actions

That ordering matters.

It also helps explain why neither file is magical on its own. They only help if the underlying docs are good enough to support them.

The Practical Takeaway

llms.txt and skill.md do different jobs.

Use llms.txt when you need the model to find the right pages. Use skill.md when you need the model to use those pages in a better order and with better judgment.

For most real documentation systems, that means you eventually want both.

Not because standards are fun, but because models make two different mistakes:

• they fail to find the right docs
• they fail to use the right docs well

These files address those problems from different angles.

If you want the concrete side of skill.md, read skill.md Examples. If you want the discovery side of the stack, read llms.txt vs sitemap.xml.