Skip to content

DISC-014Find

Agent Skills index published

Whether your shop publishes an Agent Skills index listing written instructions that agents can load.

What we check

We look for an Agent Skills index at /.well-known/agent-skills/index.json, as described in the Agent Skills Discovery RFC v0.2.0 (Cloudflare, a draft dated 2026-03-12). The index builds on the Agent Skills format (SKILL.md files). It needs a "$schema" that points to the agentskills.io discovery schema and a non-empty "skills" array. Each entry needs name, type, description, url and a digest that starts with "sha256:". If the index is missing there, we also read the older path /.well-known/skills/index.json.

Why it matters

Agent Skills are written instructions an agent can load, for example how to place an order, start a return or track a parcel with your shop. An index at a known address lets a shopper's agent find and follow them instead of guessing.

How we check

We read the current path first and the older path only if the first is absent. PASS: an index at the current path with the discovery $schema, at least one skill, complete entries, served as application/json. WARN: the body is not JSON; the $schema is missing or is not the agentskills.io discovery schema; no skills are listed; an entry is incomplete or its digest does not start with "sha256:"; the media type is wrong; or the index exists only at the older path, which v0.2.0 clients do not read. We do not download the schema or the skill files. FAIL: both paths return 404 or 410, or return your site's ordinary HTML page. SKIPPED: bot management answered, your robots.txt disallows the path for our crawler, or the server returned a status such as 429 or a 5xx.

How to fix it

  1. If you have written instructions for agents (how to order, return or track), publish them as Agent Skills (SKILL.md files).
  2. List them at /.well-known/agent-skills/index.json with "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json" and a "skills" array.
  3. Give each entry name, type ("skill-md" or "archive"), description, url and digest ("sha256:" followed by the hex hash of the file). Serve the index as application/json.
  4. If you publish at /.well-known/skills/index.json today, move the index to the new path.

What good looks like

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "start-a-return",
      "type": "skill-md",
      "description": "How to start a return at Example Shop.",
      "url": "https://example.com/.well-known/agent-skills/start-a-return/SKILL.md",
      "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
  ]
}

Sources