Agent Skills: a registry of what your agent can do

What it is

Agent Skills is a machine-readable index of an agent’s concrete skills at /.well-known/agent-skills/index.json. Each skill is a task with a description and a link to a detailed SKILL.md. Unlike OpenAPI (endpoints) and MCP Tools (tools with a JSON Schema), Skills describe tasks in natural language — in terms an LLM orchestrator understands.

Why it matters for AI agents

Before delegating a task, an orchestrator must know what an agent can actually do. Skills are a machine-readable contract: “here’s the list of what I solve.” Without it, agent selection is manual only. It’s a level above an API: not “what handles do you have” but “what tasks do you close.”

Minimal working example

The index /.well-known/agent-skills/index.json:

[
  {
    "name": "scan-url",
    "type": "skill",
    "description": "Scan a public URL and return an agent-readiness score with a per-check breakdown",
    "url": "https://example.com/.well-known/agent-skills/scan-url.md",
    "sha256": "a3f8c2d1..."
  }
]

For each skill, publish a SKILL.md (at url) with inputs, results, and call examples. Content-Type: text/markdown.

Right vs wrong

Right	Wrong
Index at /.well-known/agent-skills/index.json	An arbitrary path
Each skill: name, type, description, url, sha256	Missing required fields
url points to a real, reachable SKILL.md	A broken link to the skill file
sha256 matches the SKILL.md contents	A mismatched hash — the client won’t trust it

Common mistakes

• Not an array at the top level, or invalid JSON.
• Missing sha256/url — the orchestrator can’t verify/load the skill.
• The SKILL.md is unreachable (404) at the given url.
• Skills not mirrored in the A2A Agent Card — some orchestrators read them from there.

How to verify

The scanner GETs /.well-known/agent-skills/index.json, checks it’s an array with name/type/description/url/sha256 fields, and HEAD-checks the first url. Manually:

curl -s https://example.com/.well-known/agent-skills/index.json | jq .