skill.md Examples: Real Patterns for Claude Code, Cursor, and Codex

Most skill.md files are too vague to be useful. They say things like "this skill helps with the Acme API" or "use this to answer questions about our docs." That sounds fine until you watch an agent actually use it.

Agents do not need another mission statement. They need a compact operating manual:

• when to use which part of the docs
• which pages are canonical
• what the product can and cannot do
• what a good path through the docs looks like

The point of a skill.md file is not to describe your product beautifully. It is to reduce bad choices.

If you have not read the broader explanation first, start with our main skill.md guide. This post is the practical follow-up: real patterns, concrete templates, and the difference between a skill.md file that sounds nice and one that actually helps Claude Code, Cursor, Codex, or OpenCode do better work.

What a Good skill.md Example Actually Does

A good skill.md example should make an agent better at three things:

1. choosing the right doc page
2. avoiding the wrong abstraction
3. knowing its own boundaries

That means a strong file usually has:

• a tight description of the product or docs set
• a few decision rules
• a small map of high-value pages
• explicit boundaries
• references to canonical paths, not vague topic names

The easiest way to make a weak file is to write it like homepage copy.

Bad:

1# Acme API Skill
2
3This skill helps AI agents work with the Acme API. Acme is a powerful,
4scalable platform for modern development teams.

That tells the model almost nothing.

Better:

1# Acme API Docs
2
3Use this skill when working with Acme authentication, webhooks, rate limits,
4or SDK setup.
5
6Start with `/quickstart` for first requests.
7Use `/authentication` for API keys and OAuth.
8Use `/errors` and `/rate-limits` when debugging retries or 429s.
9
10Do not invent webhook payload fields. Read `/webhooks/events` first.

That is already more useful because it gives the model routing, not branding.

Pattern 1: API Docs

API docs are the cleanest use case for skill.md because agents usually fail in predictable ways. They guess authentication flows, misuse rate limits, or jump into reference docs before reading the quickstart.

Here is a practical API-docs pattern:

1---
2name: acme-api
3description: >
4  Acme API documentation. Use when implementing authentication, webhooks,
5  rate limits, or SDK integrations for the Acme platform.
6---
7
8# Acme API Docs
9
10## Start Here
11
12- Read `/quickstart` before writing the first request.
13- Read `/authentication` before using API keys, OAuth, or token refresh.
14- Read `/errors` and `/rate-limits` before implementing retries.
15
16## Decision Guide
17
18| Need | Read |
19|------|------|
20| First successful request | `/quickstart` |
21| API keys or OAuth | `/authentication` |
22| Event delivery | `/webhooks/overview` |
23| Error handling | `/errors` |
24| Backoff and retry policy | `/rate-limits` |
25| Request/response fields | `/api-reference` |
26
27## Boundaries
28
29- Do not invent endpoint parameters that are not documented.
30- Do not assume sandbox and production behavior are identical.
31- If a field is undocumented, prefer the API reference over examples in guides.

Why this works:

• it routes the model toward the quickstart first
• it separates operational docs from raw reference docs
• it makes error handling and boundaries explicit

What usually goes wrong:

• too many links
• no decision layer
• a giant dump of every endpoint section

If your file looks like a flattened table of contents, it is probably doing too much.

Pattern 2: SDK Docs

SDK docs are different from API docs. The hard part is usually not raw endpoint usage. It is versioning, environment setup, authentication wrappers, and avoiding examples copied from the wrong language.

An SDK-oriented skill.md should bias toward language-specific entry points and common failure modes:

1---
2name: acme-node-sdk
3description: >
4  Node SDK documentation for Acme. Use when setting up the SDK, authenticating,
5  handling retries, or using webhook helpers in Node.js services.
6---
7
8# Acme Node SDK
9
10## Use This Skill For
11
12- installing and initializing the Node SDK
13- authenticating requests in Node services
14- handling retries and pagination
15- validating webhook signatures
16
17## Start Here
18
19- `/sdks/node/installation`
20- `/sdks/node/quickstart`
21- `/sdks/node/authentication`
22
23## Decision Guide
24
25| Need | Read |
26|------|------|
27| Install and bootstrap | `/sdks/node/installation` |
28| First working example | `/sdks/node/quickstart` |
29| Auth and client config | `/sdks/node/authentication` |
30| Pagination helpers | `/sdks/node/pagination` |
31| Retry behavior | `/sdks/node/retries` |
32| Webhook verification | `/sdks/node/webhooks` |
33
34## Boundaries
35
36- Use Node examples only. Do not mix them with REST snippets from other languages.
37- Prefer SDK helper methods when they exist instead of raw HTTP examples.
38- Check the versioned SDK docs before using old blog snippets or gists.

The useful detail here is not "this is a Node SDK." The useful detail is that the agent should prefer Node-native examples and helper methods rather than falling back to raw HTTP examples from another page.

That kind of guardrail is where skill.md earns its keep.

Pattern 3: CLI Docs

CLI docs benefit from skill.md when commands have hidden preconditions or when the same workflow can be done through both config files and CLI flags.

Here is a good CLI shape:

1---
2name: acme-cli
3description: >
4  Acme CLI documentation. Use when installing the CLI, authenticating,
5  configuring environments, and running deploy or sync commands.
6---
7
8# Acme CLI Docs
9
10## Start Here
11
12- Read `/cli/installation` before using commands.
13- Read `/cli/auth` before using project-scoped actions.
14- Read `/cli/config` before editing YAML or environment-specific settings.
15
16## Decision Guide
17
18| Need | Read |
19|------|------|
20| Install the CLI | `/cli/installation` |
21| Log in or configure tokens | `/cli/auth` |
22| Configure environments | `/cli/config` |
23| Deploy changes | `/cli/deploy` |
24| Troubleshoot failures | `/cli/troubleshooting` |
25
26## Boundaries
27
28- Do not assume a command is global if the docs show a project-scoped workflow.
29- Prefer documented flags over guessed short aliases.
30- If a command mutates infrastructure, read `/cli/troubleshooting` and `/cli/config` first.

This is especially useful for agents because CLI docs often hide important behavior in setup sections that humans skim once and forget.

Pattern 4: Product Docs with Multiple Surfaces

Some products have API docs, dashboard docs, help-center docs, and integration docs all in one place. In those cases the biggest job of skill.md is to prevent the model from grabbing the wrong surface.

Example:

1# Acme Product Docs
2
3## Choose the Right Surface
4
5| If the user needs... | Start with... |
6|----------------------|---------------|
7| End-user setup steps | `/help/getting-started` |
8| Dashboard configuration | `/product/settings` |
9| API implementation | `/developers/quickstart` |
10| CLI workflows | `/cli/installation` |
11
12## Boundaries
13
14- Do not answer API questions from help-center articles.
15- Do not answer end-user UI questions from developer reference pages.
16- Prefer implementation guides before deep reference pages when the task is new.

This pattern matters more than it seems. A lot of agent mistakes are not "the model was dumb." They are "the documentation surface was mixed and the file did not tell the model where to start."

What to Copy from These Examples

The reusable parts are not the exact headings. They are the patterns:

• use real paths
• give the model a start order
• include a small decision table
• write explicit boundaries
• split by workflow, not by department org chart

If your documentation has a quickstart, auth guide, errors page, and API reference, your skill.md should probably reflect that exact order.

If your product has both CLI and dashboard workflows, say so directly instead of making the model infer it.

What Not to Copy

Do not copy these mistakes:

• giant capabilities sections
• six paragraphs describing your company
• every page in the docs nav
• vague labels like "learn more about integrations"
• marketing adjectives instead of routing instructions

The right mental model is not "write a polished overview." It is "write the smallest document that helps an agent stop making obvious mistakes."

A Simple Template You Can Start From

If you just want a starting point, this is enough:

1---
2name: your-product
3description: >
4  Documentation for [product]. Use when implementing [main use cases].
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 pages over examples copied from blogs or gists.
28- Use the product's documented workflow before suggesting alternatives.

Then tighten it based on the actual failure modes you see.

That last part matters. A good skill.md file is not static doctrine. It is accumulated scar tissue from the mistakes agents keep making.

The Practical Takeaway

If you are writing skill.md files for real docs, the best examples are not the most elegant ones. They are the ones that prevent bad choices.

That usually means:

• fewer words
• more paths
• more decision rules
• clearer boundaries

The standard itself is not the hard part. The hard part is deciding what an agent should read first, what it should ignore, and where it tends to go wrong.

That is also why skill.md pairs well with llms.txt. llms.txt gives the map. skill.md gives the playbook.

If you want the broader context, read our main skill.md guide. If you want the corresponding discovery layer, read What Is llms.txt?.