Agent Skills

What are Agent Skills?

Agent Skills is a structured list of an AI agent’s specific capabilities (skills), published as an index file at /.well-known/agent-skills/index.json. Each skill has an ID, description, and input/output types. This lets orchestrators select the right agent for a given task.

{
  "skills": [
    {
      "id": "scan-url",
      "name": "Scan URL for agent readiness",
      "description": "Given a URL, returns agent readiness score 0-100 with detailed checks",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "format": "uri" }
        },
        "required": ["url"]
      }
    }
  ]
}

Why do you need Agent Skills?

An orchestrator needs to know exactly what an agent can do before delegating a task to it. Agent Skills is the machine-readable contract between agents.

Unlike OpenAPI (which describes HTTP endpoints), Skills describe high-level tasks in terms that LLM orchestrators understand, within the Google Agent-to-Agent (A2A) Protocol.

Format	Audience	Description level
OpenAPI	HTTP client	Endpoints, parameters, response codes
MCP Tools	MCP client	Tools with JSON Schema
Agent Skills	LLM orchestrator	Tasks in natural language + schema

Without Skills, an orchestrator cannot automatically select an agent — only through manual configuration.

How do you implement Agent Skills?

1. Create the index file /.well-known/agent-skills/index.json:

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

2. Publish a SKILL.md for each skill at the URL listed in the index. The file describes inputs, expected output, and example invocations.

3. Add skills to the A2A Agent Card — orchestrators that support A2A read skills from /.well-known/agent.json.

Nginx — static publishing:

location ^~ /.well-known/agent-skills/ {
    alias /var/www/well-known/agent-skills/;
    add_header Content-Type application/json;
}

For each SKILL.md use Content-Type: text/markdown.

How do we check Agent Skills?

The scanner sends a GET request to /.well-known/agent-skills/index.json and verifies:

1. HTTP 200 — file is accessible
2. Valid JSON — array of objects
3. Required fields — each skill contains name, type, description, url, sha256
4. URL accessibility — the first skill in the list is checked with a HEAD request

pass — HTTP 200, valid JSON, all required fields present. fail — file is inaccessible, structure is invalid, or required fields are missing.