## What is SKILL.md?

SKILL.md is a single Markdown file — typically served at `/skill.md` — that tells an AI agent how to use your service. The file opens with YAML frontmatter declaring two fields, `name` and `description`, then free-form Markdown that documents the endpoints, auth model, and request shapes the agent needs to act.

The spec is published at [agentskills.io](https://agentskills.io/specification) and has been adopted as a cross-vendor convention by Anthropic's Claude Code, OpenAI Codex, Cursor, GitHub Copilot, and Microsoft's Agent Framework. A SKILL.md file is the smallest possible artifact that lets an agent go from "I found this site" to "I know how to call it."

## Why SKILL.md matters

LLM agents face the same onboarding cost humans do: figuring out what an unfamiliar service is for and how to call it correctly. With humans you write a quickstart guide; with agents you write a SKILL.md. The frontmatter `name` gives the agent a stable identifier it can register internally; the `description` is what shows up in tool listings and the agent's planner; the body is the playbook.

The alternative — an agent reading your full docs site, OpenAPI schema, and homepage to reconstruct the same information — is slow, expensive, and lossy. SKILL.md collapses the onboarding step to a single fetch and a few hundred tokens. For sites that want agents to *actually use them* (not just discover them), SKILL.md is the highest-leverage file you can publish.

## How SKILL.md works

There is no protocol handshake. An agent requests `/skill.md`, parses the YAML frontmatter for `name` and `description`, validates the name against the spec's regex, and reads the Markdown body as instructions.

A minimal valid SKILL.md:

```markdown
---
name: scan-url
description: Scan any URL for AI agent readiness and return a 0-100 score. Use when a user asks how agent-ready a site is or wants to compare protocol support across sites.
---

# Agent Readiness Scan

Use `GET /api/v1/scan?url={url}` for the agent-friendly JSON response.

## Endpoints

- `GET /api/v1/scan?url={url}` — flat JSON for agents
- `GET /api/scan?url={url}` — full HTML report (for humans)
- `GET /api/badge?url={url}` — SVG badge

## Auth

None. All endpoints are free.

## Example

`curl https://agentgrade.com/api/v1/scan?url=https://example.com`
```

That is the entire surface. Agents that find this file know enough to call your service correctly on the first try.

## SKILL.md vs other agent-readability files

| File | Who serves it | What it answers | Format |
|---|---|---|---|
| **SKILL.md** | The service | *How do I use this service?* | Markdown + frontmatter |
| **[OpenAPI](/kb/openapi)** | The service | *What endpoints exist and what's the schema?* | JSON/YAML |
| **[MCP](/kb/mcp) manifest** | The MCP server | *What tools does this server expose over JSON-RPC?* | JSON-RPC |
| **`ai-plugin.json`** | The service | *Plugin metadata for ChatGPT plugin format* (legacy) | JSON |
| **[llms.txt](/kb/llms-txt)** | The service | *What is this site, in prose?* | Markdown |

SKILL.md is the "playbook" layer; OpenAPI is the "schema" layer. The two compose: SKILL.md tells the agent which endpoints to call and when; OpenAPI provides the formal parameter schema. Agents that find both are strictly better off than agents that find either alone.

`ai-plugin.json` predates SKILL.md and was tied to the original ChatGPT plugin format, which OpenAI has since deprecated. SKILL.md is the modern, cross-vendor successor.

## Frontmatter validation

The agentskills.io spec is strict about two fields:

- **`name`** — 1 to 64 characters, lowercase alphanumeric with single hyphens. Must match `^[a-z0-9]+(-[a-z0-9]+)*$`. No leading, trailing, or consecutive hyphens. Good: `scan-url`, `book-flight`, `order-status`. Bad: `ScanUrl`, `-scan`, `scan--url`, `scan_url`.
- **`description`** — 1 to 1024 characters. Lead with the verb the agent should perform ("Scan a URL...", "Book a flight from..."). The description shows up in tool pickers and planner reasoning, so write it for an agent making a snap decision.

Agents and scanners that conform to the spec will reject files with malformed frontmatter — your file effectively becomes invisible to them.

## Who's adopted SKILL.md

The spec moved from a single-vendor convention to an interoperable standard over 2025:

- **Claude Code** ([docs.claude.com/en/docs/claude-code/skills](https://docs.claude.com/en/docs/claude-code/skills)) — Anthropic's coding agent loads SKILL.md files from local directories and uses them to scope tool access.
- **OpenAI Codex** — Adopted the same format for agent skill definitions.
- **Cursor** — Reads SKILL.md from project workspaces for inline agent guidance.
- **GitHub Copilot** — Honors the same frontmatter convention for repository-level agent instructions.
- **Microsoft Agent Framework** — Cross-vendor implementations follow the agentskills.io spec.

Because the format is just Markdown with YAML frontmatter, adoption cost is near zero: every agent that already parses Markdown can read it; every site that already publishes docs can author it.

## How to add SKILL.md to your site

1. **Pick the name.** One verb-noun phrase, lowercase-hyphen, under 64 chars. Match what the agent should "do" with your service. `book-flight` is good; `flights` is too vague.
2. **Write the description.** Two sentences. Sentence 1: what the agent accomplishes. Sentence 2: when to use it (the trigger phrase or context).
3. **Write the body.** Endpoints with HTTP verbs, auth model, one copy-pasteable curl example. Keep it under a screen of text — terse beats exhaustive.
4. **Serve at `/skill.md`.** Static file. `Content-Type: text/markdown`.
5. **Link from llms.txt or `/.well-known/`.** Optional but recommended — gives agents that find your llms.txt first a path to the skill file.

A site with a valid SKILL.md and an [OpenAPI](/kb/openapi) spec is well-equipped for any agent that arrives knowing nothing.

## Common errors scanners flag

- **Missing frontmatter delimiters** — the file does not start with `---`, so the YAML block is not detected.
- **Invalid `name`** — uppercase, underscores, or leading/trailing hyphens. The most common failure.
- **Description too short** — under 1 character (empty) or so short the agent has no signal. Aim for 80-200 chars.
- **Description too long** — over 1024 characters. Move detail into the body.
- **Wrong path** — served at `/skills.md` (plural), `/.well-known/skill.md`, or `/skill/index.md`. The spec is `/skill.md` at the document root.
- **Wrong content-type** — served as `text/html` because a CMS auto-renders Markdown. Serve raw `text/markdown` or `text/plain`.

## FAQ

**Is SKILL.md the same as Anthropic's "Claude Skills"?**
The on-disk format is the same. "Claude Skills" is Anthropic's product name for the feature that consumes SKILL.md files; the file format itself is the cross-vendor agentskills.io spec.

**Do I need both SKILL.md and OpenAPI?**
Ship both if you have an API. SKILL.md answers "how do I use this?" in prose; OpenAPI answers "what is the exact schema?" formally. Agents use OpenAPI to validate requests and SKILL.md to decide whether to call the service at all.

**What replaced `/skills.json`?**
`/skills.json` was an early, hand-rolled manifest format that predated any standard. It has been superseded by SKILL.md for the "how to use" layer and OpenAPI's `x-payment-info` (see [OpenAPI](/kb/openapi)) for declaring paid endpoints. AgentGrade no longer scores `/skills.json`.

**Where should the SKILL.md file live?**
`/skill.md` at the document root. Some agents will also probe `/.well-known/skill.md` as a fallback — publishing both is harmless.

**Can a site have multiple SKILL.md files?**
The convention is one `/skill.md` per origin. Services with multiple distinct surfaces (search vs checkout vs support) typically describe each as a section within one file, or split into sub-services on subdomains.

**Does SKILL.md replace [MCP](/kb/mcp)?**
No — they answer different questions. SKILL.md tells an agent how to use your HTTP service via existing endpoints. MCP defines a JSON-RPC interface where the agent calls your server as a tool over a persistent connection. A site can publish both.

**Does AgentGrade penalize sites that publish SKILL.md without OpenAPI?**
No. SKILL.md is a positive signal on its own. OpenAPI is a separate check.

**Will agents actually read this file?**
Claude Code, Codex, Cursor, and Copilot read SKILL.md files in their workspaces today. Browsing agents that discover your site for the first time are increasingly probing `/skill.md` as part of the discovery handshake, alongside `/llms.txt` and `/openapi.json`.

## Spec maturity

**Cross-vendor standard.** Defined at [agentskills.io](https://agentskills.io/specification). Adopted by Claude Code, OpenAI Codex, Cursor, GitHub Copilot, and Microsoft Agent Framework. Active development; the canonical implementation is well-documented.

## Learn more

- [agentskills.io](https://agentskills.io/specification) — the specification
- [Claude Code skills documentation](https://docs.claude.com/en/docs/claude-code/skills) — Anthropic's adoption
- [OpenAPI](/kb/openapi) — companion schema layer
- [MCP](/kb/mcp) — alternative for JSON-RPC tool servers
- [Agent Readiness](/agent-readiness) — how SKILL.md fits into the broader picture