# agents.md

**Tell AI agents what they can do on your website.**

[![Version](https://img.shields.io/badge/version-1.0.0--draft-blue)]()
[![License](https://img.shields.io/badge/license-CC0-green)]()

## The Problem

| File | What it tells agents |
|------|---------------------|
| robots.txt | What you **cannot access** |
| llms.txt | What **content matters** |
| **???** | What you **can do** |

## The Solution

Create `/.well-known/agents.md`:

```markdown
# My Site

An online bookstore.

## Can
- Search catalog
- Read book details
- Check availability

## Cannot
- Place orders (requires human)

## Contact
hello@mysite.com
```

That's it. Plain text. Human readable. Machine parseable.

## With MCP Gateway

Point agents to your [MCP](https://modelcontextprotocol.io/) server for structured tool access:

```yaml
---
version: "1.0"
mcp:
  endpoint: https://mysite.com/.well-known/mcp
  transport: streamable-http
  auth: oauth2
---
# My Site

An online bookstore.

## Can
- Search and browse
- Check prices
- Place orders (authenticated)

## Contact
hello@mysite.com
```

## How It Works

```
Agent requests /.well-known/agents.md
              │
              ├─► Basic: reads text, understands capabilities
              │
              └─► Advanced: connects to MCP gateway for tools
```

## Documentation

- **[Specification](./spec/README.md)** - Full protocol spec (v1.0.0-draft)
- **[Examples](./examples/)** - Real-world examples
- **[FAQ](./docs/FAQ.md)** - Common questions
- **[Changelog](./CHANGELOG.md)** - Version history

## Quick Comparison

| Aspect | robots.txt | llms.txt | agents.md |
|--------|------------|----------|-----------|
| Purpose | Crawl control | Content summary | Capabilities |
| Format | Custom | Markdown | Markdown + YAML |
| MCP | No | No | Yes |

## Status

**v1.0.0-draft** - First public draft release

Feedback welcome via issues.

## Related Standards

- [robots.txt](https://www.rfc-editor.org/rfc/rfc9309) - RFC 9309 (1994)
- [llms.txt](https://llmstxt.org/) - Jeremy Howard (2024)
- [AGENTS.md](https://agents.md/) - OpenAI/Sourcegraph (2025)
- [MCP](https://modelcontextprotocol.io/) - Anthropic (2024)

## License

CC0 1.0 Universal - Public Domain