What Is skill.md? A Practical Guide for Agent-Ready Docs← Back to blog/Engineering<br>What Is skill.md? A Practical Guide for Agent-Ready Docs<br>skill.md is not a replacement for docs, llms.txt, or MCP. It is a compact playbook that tells an agent how to use your product and where to start in your docs.<br>Faizan Khan<br>2026-06-04 • 8 min read

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:

Markdown<br>Copy<br>1# Acme API Docs

3Use this skill when working with authentication, webhooks, rate limits,<br>4and Node SDK integrations for Acme.

6Start with `/quickstart` for first requests.<br>7Use `/authentication` for API keys and OAuth.<br>8Use `/errors` and `/rate-limits` before writing retry logic.

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:

Markdown<br>Copy<br>1Acme is a modern, scalable developer platform that helps teams move faster.

Better:

Markdown<br>Copy<br>1Use `/quickstart` before `/api-reference`.<br>2Use `/authentication` before writing OAuth flows.<br>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:

Markdown<br>Copy<br>1Use this skill when working with Acme authentication, SDK setup, webhooks,<br>2and API error handling.

2. A Start Order

This is often the highest-value part.

Example:

Markdown<br>Copy<br>1Start...