# Agent Skills declaration

> Agent Skills declaration: Offers ready-made capability packages to agent runtimes. The fix: publish an agent skills index.

- Source: /checks/agent-skills
- Site: AgenticWebScore
- Language: English

---
Offers ready-made capability packages to agent runtimes.

| Property | Value |
| --- | --- |
| Check id | `agent-skills` |
| Dimension | Protocol Discovery (25%) |
| Tier | Recommended — pool 20 pts |
| Weight inside tier | 1 |
| Impact | Medium |
| Maturity | Draft — A published specification that is not yet ratified. |
| Conditional | No |
| Publishing skill | `agent-skills` |
| Standards | — |

## What the scanner requests

- `/.well-known/agent-skills/index.json`
- `/.well-known/agent-skills.json`
- `/.well-known/skills.json`

## What is measured

The scanner GETs /.well-known/agent-skills/index.json, /.well-known/agent-skills.json and /.well-known/skills.json and validates the first 200 response as an Agent Skills discovery index. It passes when the index carries a skills array whose entries each supply name, type (skill-md or archive), description, url and a sha256: digest, at least one artifact URL was fetched by the scan, and every artifact URL the scan fetched resolved with an acceptable content type. The scan fetches a sample of up to 10 same-origin artifacts, because the list is target-supplied and an uncapped fetch would let a site dictate the request count; the same-origin URLs beyond that sample are reported in the pass as unsampled rather than quietly counted. An artifact URL on another host is not followed, and it makes the index partial, never passing: the site chose to host it elsewhere, and this scan does not verify what it did not fetch. It partially passes when skills are listed with name, description and url but type or digest is missing, when a fetched artifact returned a non-2xx or the wrong content type, or when any artifact URL is off-origin or was never fetched at all. It fails when no index with a non-empty skills array is served as JSON at the 3 paths, or when a fetched artifact does not hash to the sha256 digest its entry declares. A $schema property is accepted when present but is NOT required: the schema host published for this convention does not resolve, so requiring it would make the check unsatisfiable.

## Reproduce it yourself

You do not have to take our word for any of this. Run the same measurement against your own domain:

```bash
DOMAIN=https://your-domain.example
for p in /.well-known/agent-skills/index.json /.well-known/agent-skills.json /.well-known/skills.json; do printf '%s -> ' "$p"; curl -sS "$DOMAIN$p" | jq -c '{$schema, skills:[.skills[]? | {name,type,url,digest}]}' 2>/dev/null || echo "missing or not JSON"; done
```

## The fix

This is the artifact to ship. It is the complete change, not a description of one.

```json
{
  "skills": [
    {
      "name": "invoice-reconciliation",
      "type": "skill-md",
      "description": "Reconcile invoices against payments and flag unmatched line items.",
      "url": "/.well-known/agent-skills/invoice-reconciliation/SKILL.md",
      "digest": "sha256:9f2c1a4b7d8e0f3a5c6b1d2e4f7089a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6"
    }
  ]
}
```

> An early convention rather than a ratified specification, and it has already renamed its path once. The digest is the SHA-256 of the exact bytes served, so recompute it whenever SKILL.md changes — and keep every artifact on the scanned host, because an off-origin URL is not followed and now makes the whole index partial instead of passing.

## Related checks

| Check | Tier | Impact | Same skill |
| --- | --- | --- | --- |
| `mcp-card` — MCP server card | Essential | High | — |
| `openapi` — OpenAPI definition | Essential | High | — |
| `oauth-discovery` — OAuth discovery documents | Essential | High | — |
| `api-catalog` — API catalog | Recommended | Medium | — |
| `a2a-card` — A2A agent card | Recommended | Medium | — |
| `a2a-signed` — Cryptographically signed agent card | Emerging | Medium | — |
| `auth-md` — /auth.md agent authentication guide | Emerging | Medium | — |
| `webmcp` — WebMCP browser tool declaration | Emerging | Medium | — |