How to Write a Good skill.md for API Docs and Developer Tools

The easiest way to write a bad skill.md file is to treat it like a polished overview. That usually produces a file that sounds professional and helps almost no one.

Good skill.md files are usually narrower, more opinionated, and a little blunt.

They tell the model:

• where to start
• which docs surface to trust
• which mistakes to avoid
• when not to improvise

That is especially important for API docs and developer tools, because the failure modes are repetitive. Agents guess auth flows, mix SDK and REST examples, invent CLI flags, and treat conceptual docs like reference docs.

This post is about how to write a skill.md file that reduces those mistakes.

If you want concrete templates first, read skill.md Examples. This post is the best-practices layer on top.

Start with Failure Modes, Not Features

Most teams start by listing what their product does.

That is usually the wrong first move.

The better starting point is:

Where do agents go wrong today?

For API docs, common failures look like this:

• jumping into the reference docs before the quickstart
• using deprecated auth flows
• mixing sandbox and production assumptions
• inventing webhook fields
• copying SDK examples from the wrong language

For CLIs and developer tools, common failures look like this:

• guessing flags that do not exist
• skipping installation or auth preconditions
• confusing global config with project config
• answering from blog posts instead of canonical docs

Those mistakes should shape the file more than your product positioning does.

A Good skill.md File Routes, It Does Not Describe

Weak files describe the product.

Good files route the model through the docs.

Weak:

1This skill helps with the Acme API and related integrations.

Better:

1Read `/quickstart` before `/api-reference`.
2Read `/authentication` before implementing OAuth.
3Read `/errors` and `/rate-limits` before retry logic.

The second version gives the model a sequence.

That is what usually improves outcomes.

Keep the Description Small

The description is not where you win.

Use it to establish scope, not to sound impressive.

A good description usually answers:

• which docs set is this?
• which workflows is it for?
• when should the agent use it?

Example:

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

That is enough.

What not to do:

• explain your market category
• pitch your company
• summarize every feature
• restate things the model can already infer from page titles

Every extra word has to justify itself.

Put Real Paths in the File

A surprising number of skill.md files are vague about where the important docs actually live.

They say things like:

• see the authentication docs
• use the API reference
• review integration guides

That is not enough.

Use real paths:

1- `/quickstart`
2- `/authentication`
3- `/webhooks/overview`
4- `/errors`
5- `/rate-limits`

The more your file sounds like a routing table, the more useful it usually becomes.

This is also why a short decision table works well:

1| Need | Read |
2|------|------|
3| First request | `/quickstart` |
4| API keys or OAuth | `/authentication` |
5| Webhooks | `/webhooks/overview` |
6| Error handling | `/errors` |

That is more useful than three paragraphs of explanation.

Write Explicit Boundaries

This is one of the highest-leverage parts of the file.

If you do not tell the agent what not to assume, it will often improvise.

Examples of useful boundaries:

1- Do not invent undocumented fields or flags.
2- Prefer the API reference over examples copied from guides when fields conflict.
3- Use language-specific SDK docs instead of raw HTTP examples when the task is SDK-based.
4- Do not answer UI setup questions from developer reference pages.

These lines look simple, but they prevent a lot of garbage output.

Most weak files have no boundaries at all. They assume the model will infer safe behavior from the docs. Sometimes it will. Often it will not.

Separate Documentation Surfaces

A lot of products now have mixed docs:

• help-center docs
• product UI docs
• API docs
• SDK docs
• CLI docs

If your skill file does not separate those, the model has to infer which surface applies.

That is a common source of bad answers.

A better pattern is to make the split explicit:

1| If the user needs... | Start with... |
2|----------------------|---------------|
3| API implementation | `/developers/quickstart` |
4| Dashboard setup | `/product/settings` |
5| CLI workflows | `/cli/installation` |
6| End-user help | `/help/getting-started` |

This is boring documentation work, but it helps a lot.

Keep It Short Enough to Survive Contact with Reality

Long skill.md files are tempting because you know a lot about your product.

But big files tend to degrade in the same way big prompts do:

• they become repetitive
• they hide the useful parts
• they are harder to maintain
• they stop feeling like a sharp tool

You do not need every page. You do not need every caveat. You do not need every product feature.

You need the smallest file that reliably improves the model's first few choices.

That is a better optimization target than completeness.

A Practical Structure That Usually Works

For API docs and developer tools, this structure is usually enough:

1---
2name: your-product
3description: >
4  Documentation for [product]. Use when implementing [main workflows].
5---
6
7# [Product] Docs
8
9## Start Here
10
11- `/quickstart`
12- `/authentication`
13- `/errors`
14
15## Decision Guide
16
17| Need | Read |
18|------|------|
19| First setup | `/quickstart` |
20| Auth | `/authentication` |
21| Debugging | `/errors` |
22| Reference | `/api-reference` |
23
24## Boundaries
25
26- Do not invent undocumented fields or flags.
27- Prefer canonical docs over old blog posts or examples.
28- Use the language-specific SDK docs when the task is SDK-specific.

Most teams can get pretty far with just that.

A Simple Review Checklist

Before publishing the file, ask:

1. does it tell the model where to start?
2. does it include real paths?
3. does it separate docs surfaces clearly?
4. does it tell the model what not to assume?
5. is there anything here that sounds like homepage copy?

If the answer to the last one is yes, cut it.

That is harsh, but it works.

The Practical Takeaway

A good skill.md file is not the most complete one.

It is the one that reduces bad decisions fastest.

That usually means:

• tight scope
• real paths
• short decision rules
• explicit boundaries
• no product theater

If you write it that way, the file behaves less like a brochure and more like the kind of note a senior engineer leaves for the next person touching the system.

That is a much better model for agent-facing documentation anyway.

If you want a broader explanation of the file itself, read What Is skill.md?. If you want concrete examples, read skill.md Examples.