Record Types — Docs

// base_fields

Base fields (all records)

Every record in a zone file shares these fields:

Field	Required	Description
type	Yes	`agent`, `mcp`, `skill`, `a2a`, or any custom string
id	Yes	Unique within the zone. 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.

Any additional fields are allowed. The protocol is JSON - add what you need.

agent Agent

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)

mcp MCP 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": "@pkg/name", "command": "npx @pkg/name" }`

For stdio transport, consumers use the install field to start the process. For remote transports, they connect to endpoint.

skill Skill

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.

index.json format:

{
  "schema": "agent-skills/1.0",
  "domain": "example.com",
  "skills": [
    {
      "id": "lint-fix",
      "name": "Lint Fixer",
      "description": "Auto-fix common linting issues",
      "skill_md": "https://example.com/.agents/skills/lint-fix/SKILL.md"
    }
  ]
}

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.

a2a A2A 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" }]`

When to use a2a vs agent with protocol: "a2a": Both work. Use type: "a2a" when the A2A protocol is the point. Use type: "agent" when you want to present it more broadly and A2A is just the protocol it happens to use.

custom Custom Types

Any string works as a type. Use the base fields, add whatever you need:

{
  "type": "workflow",
  "id": "data-pipeline",
  "name": "Data Pipeline",
  "description": "ETL workflow for daily data processing",
  "endpoint": "https://example.com/workflows/data-pipeline",
  "trigger": "webhook",
  "steps": 5
}

Registries index custom types. The UI shows them with a generic display. Popular custom types may eventually get dedicated UI.

// optional_fields

Optional fields (any record)

These are common fields you can add to any record. None are required.

{
  "type": "mcp",
  "id": "db-tools",
  "name": "DataTools",
  "description": "Database query tools",
  "endpoint": "https://example.com/mcp",
  "transport": "sse",

  // Optional fields
  "auth": "api-key",
  "pricing": "free",
  "docs": "https://example.com/docs",
  "source": "https://github.com/example/db-tools",
  "category": "data"
}

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.

These are labels, not specs. "auth": "oauth2" means "you'll need OAuth2" — it doesn't define the flow. Link to your docs for details.

// 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

These addresses are used in CLI commands, API URLs, and the registry UI:

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

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

# Registry UI
https://agentroot.io/zone/example.com/db-tools

// next

$ cat record-types.md

Base fields (all records)

Optional fields (any record)

Record addressing