← Knowledge Base

Skill file (SKILL.md)

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 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:

---
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	The service	What endpoints exist and what's the schema?	JSON/YAML
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	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) — 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 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) 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?

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. 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 — the specification
• Claude Code skills documentation — Anthropic's adoption
• OpenAPI — companion schema layer
• MCP — alternative for JSON-RPC tool servers
• Agent Readiness — how SKILL.md fits into the broader picture

Related: What is AI agent readiness?