skill.md: An open standard for agent skills

TL;DR

skill.md is a markdown file that lives alongside your documentation, describing how AI agents should use your product. llms.txt gives agents a page index, MCP servers give them tools, but neither tells them how to use your product well. skill.md fills that gap. It can be installed into 20+ coding agents including Claude Code, Cursor, and OpenCode.

This post covers what skill.md is, what we learned building our generator from Anthropic's best practices, and a practical guide for implementing it yourself.

The Problem skill.md Solves

We shipped llms.txt support a few weeks ago. llms.txt gives agents a map of your documentation. But there's a gap between "here are all the pages" and "here's how to actually use this product well."

Agents with access to raw documentation still write bad code. Not because models are stupid. They're remarkably capable with the right context. The problem is that documentation is written for humans who browse, skim, and build mental models over time. Agents need different things:

• Decision tables, not prose. "If you need X, use Y" beats three paragraphs explaining options.
• Boundaries, not disclaimers. "Cannot configure DNS" is more useful than a Terms of Service link.
• Page paths, not page counts. "Read /quickstart" beats "Getting Started: 5 pages."

skill.md is the cheat sheet your documentation never had. It sits alongside your docs, tells agents what your product does, when to use what, and where to look for specifics. Think of it as the context document a senior engineer would write for a new teammate, except the teammate is Claude.

The Standard

skill.md is an emerging open standard backed by the Cloudflare Skills RFC, the agentskills.io proposal, and Vercel's skills CLI.

How Discovery Works

Agents don't just fetch /skill.md. The standard uses a well-known discovery path:

1GET /.well-known/skills/index.json

This returns a JSON manifest:

1{
2  "skills": [
3    {
4      "name": "your-product",
5      "description": "Your product documentation reference...",
6      "files": ["SKILL.md"]
7    }
8  ]
9}

Then the agent fetches /.well-known/skills/SKILL.md, reads the content, and installs it locally. When you run npx skills add https://your-docs-url.com, the CLI handles this entire flow and drops the file into the right directory for your agent:

1Claude Code  → ~/.claude/skills/your-product/SKILL.md
2Cursor       → ~/.cursor/skills/your-product/SKILL.md
3OpenCode     → ~/.config/opencode/skills/your-product/SKILL.md
4Codex        → ~/.codex/skills/your-product/SKILL.md

After that, the agent loads your skill's metadata at startup and reads the full file whenever the skill becomes relevant. No manual copy-paste. No config editing.

What We Learned from Anthropic's Best Practices

Before writing our generator, we studied Anthropic's official skill authoring guide. The full document is dense and worth reading. Here's what actually changed how we built things.

1. Concise is key

The single most important rule. Anthropic's framing:

"The context window is a public good. Your Skill shares the context window with everything else Claude needs to know."

Your skill.md competes with conversation history, other skills, the system prompt, and the actual code the user is working on. Every token has to justify its existence.

The default assumption is that Claude is already smart. You don't need to explain what documentation is. You don't need to say "This skill helps you search and retrieve documentation" - the agent already knows it can do that. Only add information the model doesn't already have.

This killed our entire "Capabilities" section. Our first version had lines like:

1## Capabilities
2- Search and retrieve SolidJS documentation
3- Explain SolidJS concepts and features
4- Provide guidance on Getting Started

That's three lines of nothing. Claude knows it can search docs. What it doesn't know is that SolidJS uses fine-grained reactivity with signals, effects, and memos. That's what belongs in a skill file.

2. Decision tables over prose

Agents struggle with choices. When documentation says "you can use library A, or library B, or library C," agents pick randomly or ask the user. Decision tables eliminate this:

We applied the same pattern to our documentation map. Instead of listing page counts per nav group, we list actual page paths:

An agent reading this can immediately jump to the right page. No guessing.

3. Progressive disclosure

Anthropic recommends keeping SKILL.md under 500 lines. The skill file is Level 2 in a three-tier system:

• Level 1 (metadata): Name + description, ~100 tokens. Loaded at startup for all installed skills.
• Level 2 (SKILL.md): The main file, read when triggered. Keep under 5K tokens.
• Level 3 (resources): Additional files loaded on demand. Unlimited size.

Our generated skills are about 40 lines. That's intentional. The skill file is a cheat sheet that points to /llms.txt and /llms-full.txt for depth. We don't try to cram the entire documentation into the skill. We give agents a map and let them navigate.

4. Third-person descriptions

Small thing, big impact. The description field in the YAML frontmatter is injected into the system prompt. If you write "I can help you process PDFs," it clashes with the agent's perspective. Always third person:

1# Bad
2description: I can help you work with SolidJS documentation
3
4# Bad
5description: Use this to find information about SolidJS
6
7# Good
8description: >
9  SolidJS documentation reference. Covers getting started, core concepts,
10  API reference. Use when implementing reactivity or components, or
11  troubleshooting SolidJS integrations.

5. Explicit boundaries

A well-structured skill separates what agents can configure from what requires human setup. Our generated skills keep this concise:

1## Boundaries
2
3- Read-only access to published documentation
4- Cannot modify docs content, manage accounts, or configure infrastructure
5- For undocumented topics, direct users to the product's official support channels

Three lines. Agents know exactly where their authority ends.

Skills vs MCP: Different Problems

This comes up a lot, so let's address it directly. MCP (Model Context Protocol) and skill.md look superficially similar. Both give agents context about your product. But they solve different problems and operate at different layers.

MCP gives agents hands. Skills give agents knowledge.

An MCP server for your documentation might expose a search_docs tool that agents can call in real-time to query your content. That's powerful. It means agents get live results, can filter, and don't need your entire docs in context.

A skill file tells the agent how to think about your product. It says "for database queries, start with /guides/query-builder not /api/raw-sql" and "the v1 REST endpoints are deprecated, use the GraphQL API instead." No tool call needed—the agent just knows.

They're complementary. In fact, our skill files point agents to /llms.txt and /llms-full.txt, which are effectively the "read" layer. If we shipped an MCP server alongside, the skill would tell agents when to use each MCP tool and how to interpret the results.

The practical difference for most documentation platforms: skill.md is a static file you can ship today in 20 minutes. An MCP server is a service you need to run, monitor, and maintain. Start with skill.md. Add MCP when you need live capabilities.

The Implementation

For anyone building this themselves, here's the architecture.

Three endpoints

You need three things served from your docs domain:

The discovery endpoint returns the JSON manifest. The skill endpoint generates the actual markdown content.

How to Implement This for Your Docs

If you're running a documentation platform or want to add skill.md to your product docs, here's the step-by-step.

Step 1: Serve the discovery endpoint

Create /.well-known/skills/index.json:

1{
2  "skills": [
3    {
4      "name": "your-product",
5      "description": "Your product docs. Covers authentication, API reference, SDKs. Use when implementing your-product features or troubleshooting integrations.",
6      "files": ["SKILL.md"]
7    }
8  ]
9}

Rules for the name field: lowercase, alphanumeric + hyphens, max 64 characters. No reserved words like "anthropic" or "claude."

Rules for description: max 1024 characters, third person, include trigger terms.

Step 2: Create SKILL.md

Serve it at /.well-known/skills/SKILL.md (and optionally at /skill.md for convenience).

Step 3: Test with the CLI

1npx skills add https://docs.your-product.com

If discovery is set up correctly, you'll see the skill installed. Then open your agent and verify it activates when you ask about your product.

Step 4: Iterate based on agent behavior

This is the part most people skip. Anthropic's guide recommends an observe-refine-test loop:

1. Ask an agent a question about your product with the skill installed
2. Watch which pages it reads (or doesn't)
3. If it misses something, make it more prominent in the documentation map
4. If it reads something useless, remove it from key topics

Your skill.md is a living document. Update it when your docs change.

Docsalot Now Serves skill.md by Default

Every documentation site hosted on Docsalot now serves a skill.md file automatically, across all tiers, no configuration needed. Your docs are already discoverable by npx skills add https://your-docs.docsalot.dev and installable into Claude Code, Cursor, OpenCode, and every other agent that supports the standard.

If you want to customize what your skill file contains, just add an updated SKILL.md to your docs repo with the structure we outlined above. The generator will pick it up and serve it at the right endpoint.

References

• Cloudflare Skills RFC - The protocol specification
• agentskills.io - Community standard and agent compatibility list
• Vercel skills CLI - npx skills add implementation
• Anthropic skill authoring best practices - The official guide we followed
• Vercel web design guidelines - Another example of agent-optimized documentation