$ cat record-types.md

Four built-in types. Custom types welcome. All share a simple base.

// base_fields

Base fields (all records)

Every record in a manifest shares these fields:

Field	Required	Description
type	Yes	One of: `agent`, `mcp`, `skill`, `a2a`, `payment`. The protocol schema is a closed enum at this layer.
id	Yes	Unique within the manifest. Lowercase, hyphens OK.
name	Yes	Display name
description	Yes	What it does, 1-2 sentences
endpoint	Depends	URL to reach the service. Required for `agent`, `mcp`, `a2a`, and `payment`.

Any additional fields beyond the schema-required ones are allowed on a record. The validator only enforces the required set per type; extra keys ride along untouched.

agentAgent

An AI agent that accepts tasks and returns results.

{
  "type": "agent",
  "id": "assistant",
  "name": "My Assistant",
  "description": "A research assistant that can search and analyze documents",
  "endpoint": "https://example.com/agent",
  "protocol": "a2a",
  "capabilities": ["research", "analysis", "summarization"]
}

Field	Description
endpoint	Where to reach the agent
protocol	How to talk to it: `a2a`, `rest`, `graphql`, `websocket`. Default: `a2a`
capabilities	What it can do. Array of keyword strings.
card	URL to a full agent card JSON (for richer metadata)

mcpMCP Server

A Model Context Protocol server that exposes tools to AI applications.

{
  "type": "mcp",
  "id": "db-tools",
  "name": "DataTools",
  "description": "Database query and visualization tools",
  "endpoint": "https://example.com/mcp",
  "transport": "sse",
  "tools": [
    { "name": "query_database", "description": "Execute SQL queries" },
    { "name": "visualize_data", "description": "Generate charts from data" }
  ]
}

Field	Description
transport	How to connect: `sse`, `streamable-http`, `stdio`
endpoint	URL for remote transports (sse, streamable-http). Not needed for stdio.
tools	Array of `{name, description}` — what tools the server provides
install	How to run it locally: `{npm, command}`

skillSkill

A collection of SKILL.md files — instructions that teach AI coding agents how to perform specific tasks.

Collection (multiple skills):

{
  "type": "skill",
  "id": "coding-helpers",
  "name": "Coding Helpers",
  "description": "Skills for linting, testing, and deployment workflows",
  "index": "https://example.com/.agents/skills/index.json"
}

Single skill:

{
  "type": "skill",
  "id": "deploy-helper",
  "name": "Deploy Helper",
  "description": "Guides agents through deployment workflows",
  "skill_md": "https://example.com/SKILL.md"
}

Field	Description
index	URL to an index.json listing multiple skills
skill_md	URL to a single SKILL.md file
skills	Inline skill list: `[{id, name, description, skill_md}]`

One of index, skill_md, or skills must be present.

SKILL.md format:

---
name: lint-fix
description: Auto-fix common linting issues
---

# Lint Fixer

Step-by-step instructions for how agents should use this skill...

Compatible with: Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, GitHub Copilot.

a2aA2A Endpoint

An Agent-to-Agent protocol endpoint, following the A2A specification.

{
  "type": "a2a",
  "id": "task-runner",
  "name": "Task Runner",
  "description": "Executes long-running background tasks with progress reporting",
  "endpoint": "https://example.com/.well-known/agent.json",
  "capabilities": ["long-running-tasks", "file-processing"]
}

Field	Description
endpoint	URL to the A2A agent card or endpoint
capabilities	What it can do. Array of keyword strings.
skills	A2A skills: `[{name, description}]`

paymentPayment

A payment record advertises which agent-payment protocols a service speaks, the methods and assets it accepts, and where to reach it. Used by autonomous agents that need to settle a transaction before continuing a task.

{
  "type": "payment",
  "id": "pay-assistant",
  "name": "Assistant Payment",
  "description": "Payment endpoint for the research assistant agent",
  "endpoint": "https://example.com/pay",
  "protocols": ["x402", "mpp"],
  "methods": ["stripe", "crypto"],
  "assets": ["USDC", "USD"]
}

Field	Required	Description
endpoint	Yes	URL to reach the payment service.
protocols	Yes (non-empty)	Array of agent-payment protocols supported. Common values: `x402`, `mpp`, `a2a-payments`.
methods	Optional	Accepted settlement methods. Array of strings.
assets	Optional	Accepted currencies/tokens, e.g. `"USDC"`, `"USD"`.
api_spec	Optional	URL to an OpenAPI/JSON-Schema document describing the endpoint.

The validator rejects payment records that are missing endpoint or have an empty protocols array.

// optional_fields

Optional fields (any record)

Field	Description
auth	Auth hint: `"none"`, `"api-key"`, `"bearer"`, `"oauth2"`
pricing	Pricing hint: `"free"`, `"freemium"`, `"paid"`
docs	Link to documentation
source	Link to source code
category	Category hint: `"research"`, `"devtools"`, `"data"`, `"automation"`, etc.

// addressing

Record addressing

Every record has a simple address: <domain>/<record-id>

example.com/assistant              # agent
example.com/db-tools               # MCP server
example.com/coding-helpers         # skill collection
example.com/coding-helpers/lint-fix # individual skill
api.example.com/api-tools          # MCP on subdomain

# CLI
$ npx agent-root install example.com/db-tools

# API
GET /api/manifests/example.com/records/db-tools

// next

← Manifests

DNS Records →