Agent Skills — /.well-known/agent-skills/index.json
TL;DR
An Agent Skill is a SKILL.md file: a name, a one-line description and instructions an AI agent loads when a task matches. The Agent Skills Discovery RFC (Cloudflare, v0.2.0, March 2026) gives a site one place to list the skills it publishes: /.well-known/agent-skills/index.json. An agent reads the index, installs a skill, and checks the file against the sha256 digest in the index.
Explain Simply
A shop pins a list of how-to cards by the door: how to order, how to return, how to track a parcel. A robot assistant reads the list, takes the card it needs, and checks the card's seal so it knows nobody swapped it.
The index (RFC v0.2.0):
GET /.well-known/agent-skills/index.json
Content-Type: application/json
{"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
"skills": [
{"name": "code-review",
"type": "skill-md",
"description": "Review code for bugs. Use when …",
"url": "/.well-known/agent-skills/code-review/SKILL.md",
"digest": "sha256:<64 lowercase hex>"}
]}The rules that matter:
- $schema is required and names the version; a client should not process an index with a $schema it does not know.
- Every entry needs all five fields. name: 1-64 characters, a-z, 0-9 and single hyphens. type: skill-md (one SKILL.md) or archive (.tar.gz or .zip with SKILL.md at the root). description: up to 1024 characters, saying what the skill does and when to use it. url: where the artifact is, resolved against the index URL. digest: SHA-256 of the artifact's bytes.
- A client MUST verify the digest and MUST NOT use content that fails it — an entry without a digest is unusable.
- The SKILL.md itself starts with YAML frontmatter holding name and description (agentskills.io specification).
Not a skills index: /.well-known/agent.json is the old path of an A2A agent card (now agent-card.json), and /.well-known/ai-plugin.json is the ChatGPT plugin manifest, retired in 2024. The v0.1.0 draft used /.well-known/skills/index.json with a files list and no digests; v0.2.0 clients look only at /.well-known/agent-skills/.
⚡Why It Matters
A skill is the cheapest way to teach an agent to use your product correctly: which endpoint, which parameters, what to do on an error. Without an index the agent, or its user, has to find the skill in a GitHub repo. Cloudflare's developer docs, Vercel and Redocly publish one already. A site with no product an agent can act on does not need one — that is why the check is low severity.
🔍How CiteStat Checks
CiteStat fetches /.well-known/agent-skills/index.json, and if that is missing, the v0.1.0 path /.well-known/skills/index.json. It passes on a v0.2.0 index served as application/json whose every entry has a valid name, type, description, url and sha256 digest. Entries that break those rules, an empty list, an unknown $schema or a JSON file with no skills array is a medium finding; a v0.1.0 index or the wrong media type is low. An HTML page at the path counts as no index. The scan reads the index only; it does not download the skills.
CiteStat Score Impact
One of the 9 core checks on the Agent Readiness card (score = core checks passed / 9 × 10). It does not change the headline SEO score.
Fix Difficulty
Editor: Hard | Developer: Easy | AI Agent: Easy