Agent Skills discovery

A well-known URI that lists Agent Skills — short, scoped instructions an AI agent can load to work better with your site. Emerging convention via a Cloudflare-led RFC; still draft, still cheap to ship.

What it is

An Agent Skill is a small Markdown file — a SKILL.md with YAML frontmatter — that gives an AI agent a focused capability: when to use it, how to call your APIs, which conventions to follow. The format originated with Anthropic; the agentskills.io specification documents it.

Agent Skills Discovery is the convention for publishing those skills so any agent can find them. Per the Cloudflare-led discovery RFC (currently draft v0.2.0), publishers ship a JSON index at:

/.well-known/agent-skills/index.json

Each entry in the index has a name, type (skill-md or archive), description, url, and a sha256 digest of the artefact. A top-level $schema field identifies the index version.

This site publishes one such skill: /.well-known/agent-skills/specification-website/SKILL.md, advertised in /.well-known/agent-skills/index.json. It teaches an agent how to query the spec via Markdown endpoints, llms.txt, and the MCP server.

Why it matters

One URL answers "what skills does this site publish for agents?" — no scraping, no per-vendor registry.
Skills are vendor-neutral Markdown. The same file works in Claude, in agent harnesses, and in anything else that loads the format.
The digest field gives clients cheap change detection and integrity verification.
It composes with other agent-readiness signals: a skill can teach an agent to prefer your .md endpoints, hit your MCP server, or follow your structured-data conventions.

Adoption is early. Treat it as a low-cost bet, not a settled standard.

How to implement

Author one or more SKILL.md files. Each MUST start with YAML frontmatter containing name (lowercase, hyphens, 1–64 chars) and description (≤1024 chars, written so an agent can decide whether to load the full body).
Host each skill at /.well-known/agent-skills/<name>/SKILL.md. Serve as text/markdown.
Publish /.well-known/agent-skills/index.json with $schema set to https://schemas.agentskills.io/discovery/0.2.0/schema.json and a skills array. Each entry needs name, type, description, url, and digest.
Compute the digest as sha256:<hex> over the raw bytes of the artefact. Recompute and update the index every time the artefact changes.
Advertise the index in /.well-known/api-catalog and as a Link header: rel="agent-skills"; type="application/json".
Serve both files with CORS open (Access-Control-Allow-Origin: *) so browser-based agents can fetch them.

Common mistakes

Letting the digest drift from the file. A mismatch makes the artefact unverifiable; compliant clients will refuse it.
Writing the description as marketing copy. It is the only thing most agents read — front-load the when to use this signal.
Bundling many unrelated capabilities into one skill. Prefer several small skills with sharp descriptions over one omnibus file.
Forgetting $schema. Without it, clients fall back to v0.1.0 parsing and your entries may be ignored.
Hosting SKILL.md with the wrong content type. text/html will confuse agents that fetch it directly.

Verification

curl -sI https://example.com/.well-known/agent-skills/index.json — confirm 200, Content-Type: application/json.
Parse the JSON and verify $schema matches the v0.2.0 URI.
For each entry, fetch the url, hash the bytes, and confirm the result equals the digest.
Validate with isitagentready.com — checks.discovery.agentSkills.status should report pass.