The file is markdown with YAML frontmatter. Parse the frontmatter for structured channel data, read the prose for routing rules.

### Creating an Agent Contact Card

Create a markdown file with YAML frontmatter:

Host this at `/.well-known/agent-card` on the user's domain.

## Format Details

### Required Fields

| Field | Description |
|-------|-------------|
| `version` | Spec version. Currently `"1"` |

### Recommended Fields

| Field | Description |
|-------|-------------|
| `human_contact` | Phone/email for humans to reach the human |
| `channels` | Contact channels for agents (see below) |

### Optional Fields

| Field | Description |
|-------|-------------|
| `name` | Display name for this agent configuration |
| `last_updated` | ISO date when card was last modified |
| `capabilities` | What this agent can do (e.g., `["scheduling", "accepts_ical"]`) |
| `agents` | Named agents if multiple (see Multi-Agent section) |

### Channels

Channel names are freeform. Common ones:

- `email` - Email address
- `discord` - Discord username
- `webhook` - HTTP endpoint for structured messages
- `signal` - Signal phone number
- `telegram` - Telegram username

For webhooks, provide details:

### Multi-Agent Setups

List multiple specialized agents:

The markdown body should explain routing between them.

## Privacy Tiers

Different URLs for different access levels:

| Tier | URL Pattern | Access |
|------|-------------|--------|
| Public | `/.well-known/agent-card` | Anyone |
| Named | `/.well-known/agent-card/{name}` | Know the name |
| Private | `/{random-uuid}/agent-card.md` | Shared URL only |

Each tier can expose different channels and capabilities.

## Discovery Methods

1. **Well-known URL**: Check `https://domain/.well-known/agent-card`
2. **vCard extension**: Look for `X-AGENT-CARD` field in contact cards
3. **Ask the human**: Request the URL directly

## Reading an Agent Card

When you fetch an agent card:

1. Parse YAML frontmatter for structured data
2. Read markdown body for natural language routing rules
3. Choose appropriate channel based on your purpose
4. Follow any authentication requirements mentioned

## Test It

Here's a live demo you can test:

---
version: "1"
human_contact: "+1 555 123 4567"
channels:
  email: "[email protected]"
  discord: "my-agent#1234"
  webhook:
    url: "https://example.com/agent/incoming"
    method: "POST"
    format: "JSON with 'message' field"
capabilities:
  - scheduling
  - accepts_ical
---

# My Agent

If you're a human, call the number above.

If you're an agent:
- For scheduling requests, use Discord
- For urgent matters, email with "URGENT" in subject
- Response time: within a few hours

channels:
  webhook:
    url: "https://example.com/agent/incoming"
    method: "POST"
    auth: "Bearer token in Authorization header"
    format: "JSON with 'message' and 'from' fields"

agents:
  - name: "Calendar Agent"
    handles: ["scheduling", "availability"]
    channel: discord
    id: "cal-agent#1234"
  - name: "Support Agent"
    handles: ["technical questions"]
    channel: webhook
    id: "https://example.com/support"