# 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.

```json
{
  "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`:

```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](/glossary/a2a-agent-card)** — orchestrators that support A2A read skills from `/.well-known/agent.json`.

**Nginx — static publishing:**

```nginx
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.

[← All glossary terms](/en/glossary)