# AX-SYS-07: Publish a capability index agents can find

> Discovery and navigation · intermediate · AX-SYS-07

Provide a root-level, machine-readable index of what an agent can do, with metadata on every resource.

## Why

Agents discover features through structured indexes, not visual menus. The canonical AX framework (agentexperience.ax — Agent Accessibility) states that agents must have a clear path to capability discovery without relying on visual UX. The Google A2A protocol formalizes this with Agent Cards at `/.well-known/agent.json`, now in production at 150+ organisations. The llms.txt standard provides a complementary content-level index.

## Do

Serve a `/.well-known` capability manifest.

## Don't

Hide capabilities behind JS navigation.

## Artifact

Serve at `/.well-known/agent-capabilities.json`:

```json
{
  "name": "Acme",
  "description": "Acme helps teams do X.",
  "auth": { "type": "bearer", "scopes_url": "/docs/scopes.md" },
  "actions": [
    { "name": "search_orders", "method": "GET", "path": "/v1/orders",
      "scopes": ["orders:read"], "description": "Find a customer's orders by email or order ID." },
    { "name": "create_refund", "method": "POST", "path": "/v1/refunds",
      "scopes": ["refunds:write"], "consequential": true,
      "description": "Issue a refund. Irreversible. Supports dry_run." }
  ],
  "docs": "/llms.txt"
}
```

## Citations

1. [agentexperience.ax — Principles of AX](https://agentexperience.ax/concepts/principles-of-ax/) — Agent Accessibility: agents must be able to discover service capabilities without relying on visual navigation designed for humans
2. [Mathias Biilmann — One Year of AX](https://biilmann.blog/articles/one-year-of-ax/) — Context pillar: does the LLM know about your product and have the right context to use it?
3. [Google A2A Protocol](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) — Agent Cards at /.well-known/agent.json are the A2A mechanism for DNS-addressable capability discovery

---
Source: Agent Experience Principles (axprinciples.com)