Agent Skills index: what the check tests and how to fix it

Tracked, not scored. Validates /.well-known/agent-skills/index.json: its $schema and each skill's name, type, description, url and digest. Absent is a skip.

Agent Discovery · Tracked, not scored

How common is it?

6% of 1223 measured sites publish a passing result (observed adoption; this check does not change the score).

Latest audit of each site under rubric v3.1. A site with nothing published counts as not passing. A partial result does not count as a pass.

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.

ResultWhen
SkipNo 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-md or archive.
  • 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>"
    }
  ]
}
  1. Write each skill as a SKILL.md with name and description frontmatter. Use lowercase letters, digits and single hyphens in the skill name, as the specification requires.
  2. Compute the digest of the exact file you serve, for example shasum -a 256 SKILL.md, and prefix the hex with sha256:.
  3. 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.
  4. 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.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →