What this check tests
This is a tracked check: it does not change your score. The audit requests /.well-known/agent-skills/index.json. Like other well-known files it only counts when the answer is a 200 with a JSON content type and a body different from the site's response to a random well-known path.
| Result | When |
|---|---|
| Skip | No index served |
| Fail (0) | Larger than 256 KB; not a JSON object; a $schema other than https://schemas.agentskills.io/discovery/0.2.0/schema.json; skills missing, not an array or empty; or any skill entry invalid |
| Partial (50) | Every entry is valid but $schema is missing |
| Pass (100) | $schema is the v0.2.0 URI and every entry is valid |
Each entry is checked for:
name: 1 to 64 characters, lowercase letters and digits in words separated by single hyphens.type:skill-mdorarchive.description: non-empty and at most 1024 characters.url: non-empty, resolving (against the index URL) to an http(s) address that is not the index itself.digest:sha256:followed by 64 lowercase hex characters.
The check validates the index only. It does not download the skills or recompute the digests.
Why it matters to agents
The index is a single, predictable place where an agent or tool can learn which skills your domain publishes, before it fetches any of them. The skill files themselves use the SKILL.md format from the Agent Skills specification: a folder whose SKILL.md carries a name and a description in frontmatter, followed by instructions.
The discovery document is a draft RFC (version 0.2.0 on the verification date), hosted on GitHub. It is not an IETF or W3C standard, and v0.2.0 renamed the path from /.well-known/skills/ to /.well-known/agent-skills/, so expect it to keep changing. Treat publishing an index as an early step, not an established requirement.
How to fix it
Only if you publish skills: serve the index as application/json and list one entry per skill.
{
"$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
"skills": [
{
"name": "order-lookup",
"type": "skill-md",
"description": "Look up an Example Co order by number and report its status.",
"url": "/.well-known/agent-skills/order-lookup/SKILL.md",
"digest": "sha256:<64 lowercase hex characters>"
}
]
}
- Write each skill as a
SKILL.mdwithnameanddescriptionfrontmatter. Use lowercase letters, digits and single hyphens in the skill name, as the specification requires. - Compute the digest of the exact file you serve, for example
shasum -a 256 SKILL.md, and prefix the hex withsha256:. - Put the files under
/.well-known/agent-skills/and the index at/.well-known/agent-skills/index.json. Recompute the digest whenever a file changes. - Make sure a request for a random path under
/.well-known/returns 404, not a page.
A missing $schema gives a partial: add the line above to move to pass. More on the file format: SKILL.md for AI agents. Related: A2A agent card and MCP server card; browser-page tools are covered by WebMCP declarative and WebMCP imperative.