Agent Skills Discovery: How AI Agents Find Your Skills

Short answer: an Agent Skill is a folder with a SKILL.md file: YAML frontmatter with a name and a description, then markdown instructions that teach an AI agent one specific task. To let agents find your skills without manual setup, publish an index at /.well-known/agent-skills/index.json, served as Content-Type: application/json. Each entry has five required fields: name, type, description, url and digest (the file's SHA-256).

What a skill is, and why it needs an index

The Agent Skills format was developed by Anthropic and released as an open standard at agentskills.io. A skill teaches an agent a procedure: deploy an app, run a scan, use one API correctly. Agents load skills in three stages, called progressive disclosure:

1. At startup, only the name and description — about 100 tokens per skill.
2. When a task needs the skill, the whole SKILL.md — under 5,000 tokens is recommended.
3. Files in scripts/, references/ and assets/, only when a step asks for them.

That way an agent can know hundreds of skills without filling its context.

The open problem was finding them. Users had to download and install skills by hand. Cloudflare's Agent Skills Discovery via Well-Known URIs (draft v0.2.0, updated 12 March 2026) puts the list at one fixed path, as an API catalog does for APIs (see our API catalog guide) and llms.txt does for content.

What an Agent Skills index looks like

This is our own index, fetched on 23 October 2026 (the skill file itself: SKILL.md):

GET /.well-known/agent-skills/index.json
Content-Type: application/json

{"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
 "skills": [
  {"name": "citestat-seo-audit",
   "type": "skill-md",
   "description": "Audit a web page's SEO and AI-search readiness with the CiteStat API: ...",
   "url": "https://citestat.com/.well-known/agent-skills/citestat-seo-audit/SKILL.md",
   "digest": "sha256:6dd30b6f0489348cfd7ec111098168dd15794c4cf42044a7c568d7eb964a5090"}
 ]}

The main rules in the spec:

• $schema names the version. An agent must read it first, and must not process an index with a $schema it does not know.
• name: 1–64 characters of lowercase letters, digits and hyphens, with no leading, trailing or double hyphen. It must match the skill's folder name.
• type is skill-md (one SKILL.md file) or archive (a .tar.gz or .zip with SKILL.md at its root).
• description is at most 1,024 characters and should match the SKILL.md frontmatter: what the skill does and when to use it.
• url may be relative or absolute, even on another host.
• digest is sha256: plus 64 lowercase hex characters. An agent must check the download against it and must not use a file that does not match.

Why the digest is the rule that matters most

A wrong web page makes an agent answer wrongly. A wrong skill makes an agent act wrongly, because a skill is instructions the agent will follow. So the spec treats skills like code. A client must:

• verify the digest before it uses a file, and an archive's digest before it unpacks it;
• reject archives with .. paths or links that point outside the skill folder;
• not run files in scripts/ by default;
• and, the spec recommends, trust only an allowlist of origins.

For a publisher this means: edit SKILL.md and forget to recompute the digest, and every compliant agent will reject that skill.

We checked 8 sites for Agent Skills indexes

On 23 October 2026 we ran the CiteStat scan's own judge (packages/core/agent-skills.ts) on 8 sites. For each index that passed, we also downloaded every listed file and computed its SHA-256 — the step the spec requires of an agent:

Site	Index	Digests verified
developers.cloudflare.com	Pass — 19 skills (11 SKILL.md, 8 archives)	19/19
vercel.com	Pass — 9 skills (3 SKILL.md, 6 archives), files hosted on github.com	9/9
blog.cloudflare.com	Pass — 1 skill	1/1
citestat.com	Pass — 1 skill	1/1
docs.stripe.com	Old v0.1.0 format at /.well-known/skills/ — 10 skills, no digests	—
docs.claude.com	None	—
github.com	None	—
erpfit.com	None	—

On 23 October 2026, 4 of the 8 sites published a valid v0.2.0 index (30 skills in all), and every one of the 30 files matched its digest. The other findings:

• Vercel's files live on GitHub Releases, not on vercel.com, and come back as application/octet-stream. The spec allows another host, but it says servers MUST send SKILL.md as text/markdown or text/plain and archives as application/gzip or application/zip. The digests still verify, so a lenient client works; an agent with an origin allowlist must also trust github.com.
• Stripe publishes 10 skills in the old v0.1.0 format: the old path, a files array, no digests. The spec says v0.2.0 is not backward-compatible, and a v0.2.0 agent looks only under /.well-known/agent-skills/, so those skills go unfound — and without digests they could not be verified anyway.

Which agents read the index today?

As of 23 October 2026 we found no major agent that documents fetching /.well-known/agent-skills/index.json on its own. The spec is still a Cloudflare draft. On 30 June 2026 a contributor wrote in the repository (issue #13) that the plan is to adopt it formally into the Agent Skills specification. Publishing now costs one JSON file; the payoff depends on that adoption.

Our own mistake

Until 23 October 2026 the CiteStat scan got this check wrong in both directions. It passed any JSON at /.well-known/agent.json (actually an A2A protocol agent card), agent-skills.json or ai-plugin.json (ChatGPT plugins, retired in 2024), and never read the real path. The result: developers.cloudflare.com with 19 skills and Vercel with 9 were reported as having none, while citestat.com — which had no skill at the time — passed on its agent.json. We rebuilt the judge on the v0.2.0 spec and published our skill citestat-seo-audit. Its digest is computed from the exact bytes the server sends, and an automated test runs the scan's judge on our own index.

How to publish a skill in four steps

1. Write SKILL.md. YAML frontmatter with a name (matching the folder) and a description that says what the skill does and when to use it. The body holds the steps, example commands and common errors. Keep it under 500 lines.
2. Place the file at /.well-known/agent-skills/<name>/SKILL.md, served as text/markdown.
3. Compute the digest: shasum -a 256 SKILL.md, then write sha256:<hex> into the index.
4. Write the index index.json with the v0.2.0 $schema and a skills array, served as application/json. If you can, generate the digest in your build so it never drifts from the file.

If an agent has nothing to operate on your site — no API, no CLI, no workflow — leave this out. A skill that only restates your marketing copy teaches an agent nothing.

What CiteStat checks

On the Agent Readiness card the scan reads /.well-known/agent-skills/index.json. It passes when the index is v0.2.0 and every entry has all five fields in a valid form. An entry with a missing field, a malformed digest, an unknown $schema or no skills array is a medium finding. The old v0.1.0 format, the wrong media type or no index at all is low. None of it changes the headline SEO score. You can run the check on your own site for free, 10 scans a day; if you check client sites every week, the Pro plan gives 100 scans a day for 500,000₫/month (excl. VAT) — see pricing.

Frequently asked questions

How are Agent Skills different from an MCP server?

An MCP server gives an agent tools it can call. A skill is written instructions: when to act, the steps, examples. They complement each other — a skill can teach an agent to use your API or MCP server correctly.

Which sites should publish an Agent Skills index?

Sites with a product an agent operates for its user: an API, a CLI, a deploy platform, developer tools. A site that is only content to read does not need one; llms.txt and markdown fit it better. That is why the CiteStat scan reports a missing index only as a low finding.

What is the digest for?

The digest is the SHA-256 of the skill file. The spec requires an agent to check the download against it and not to use a file that does not match. A skill is instructions the agent will follow, so a file altered in transit or on a CDN must not get through. Every edit to SKILL.md needs a new digest.

Do Agent Skills improve Google rankings?

Google's documentation does not mention Agent Skills at all. An index helps agents that act for a user, not a search ranking. The CiteStat scan shows it on the Agent Readiness card only; your headline SEO score stays the same.

Sources: Agent Skills Discovery via Well-Known URIs (Cloudflare, draft v0.2.0, updated 12 March 2026) · Agent Skills specification (agentskills.io) · RFC 8615 (Well-Known URIs). Data for the 8 sites and 30 digests: fetched 23 October 2026.