Skip to main content

​
What is AGENTS.md?

AGENTS.md is a machine-readable markdown file that describes what an AI agent can do with a repository. It’s like a README for machines — where README tells humans how to use your code, AGENTS.md tells autonomous agents what capabilities your code exposes. Think of it as a contract between your repository and any AI system that wants to interact with it.
AGENTS.md follows the Agent-Accessible Interface Format (AAIF) standard, making repositories universally discoverable by autonomous agents.

​
Why AGENTS.md Matters

Without AGENTS.md, AI agents can’t reliably discover or use your repository’s capabilities. They’re left guessing from code comments and documentation written for humans. With AGENTS.md:
  • Agents discover your capabilities automatically — no manual configuration needed
  • Capabilities are described in structured JSON schemas — reducing hallucination and errors
  • Endpoints are documented with precise parameters — agents know exactly how to call your API
  • Authentication requirements are explicit — agents can properly authenticate requests

​
Anatomy of AGENTS.md

Here’s the structure Beacon generates: 
# AGENTS.md — {project-name}

> {One-line description for AI agents}

**Version:** {version}

---

## Authentication

**Type:** `bearer` | `api_key` | `none`

{How agents should authenticate}

---

## Capabilities

What an agent can do with this repository:

### `capability_name`

{Description of what this capability does}

**Input:**

```json
{
  "type": "object",
  "properties": { ... },
  "required": [ ... ]
}
Output: 
{
  "type": "object",
  "properties": { ... }
}
Examples:
  • Example 1
  • Example 2

​
Endpoints

​
GET /path

Endpoint description goes here.
ParameterTypeRequiredDescription
paramstring✅Parameter description

​
Rate Limits

  • Per minute: 60
  • Per day: 10000
Additional notes about rate limiting. 

## Real Example from Beacon

Here's an actual capability from Beacon's own AGENTS.md:

<CodeGroup>

```markdown Capability Definition
### `generate_agents_md`

Scans a repository (local path or GitHub URL) and generates an AGENTS.md file describing its agent-usable capabilities, endpoints, and authentication. It uses various AI providers (Gemini, Claude, OpenAI, Beacon Cloud) for inference.

**Input:**

```json
{
  "properties": {
    "target": {
      "description": "The path to the local repository or a GitHub URL.",
      "type": "string"
    },
    "provider": {
      "description": "The AI provider to use for inference (e.g., 'gemini', 'claude', 'openai', 'beacon-ai-cloud'). Defaults to 'gemini'.",
      "type": "string"
    },
    "api_key": {
      "description": "API key for the chosen AI provider, if not set via environment variable.",
      "type": "string"
    },
    "output": {
      "description": "The path where the AGENTS.md file should be written (default: AGENTS.md).",
      "type": "string"
    }
  },
  "required": ["target"],
  "type": "object"
}
Output: 
{
  "description": "Path to the generated AGENTS.md file.",
  "type": "string"
}
Examples:
  • beacon generate ./my-project
  • beacon generate https://github.com/user/repo --provider openai --api-key sk-...

​
What Makes a Good AGENTS.md?

Beacon’s AI inference engine looks for:
Capabilities should describe what an agent can accomplish, not how the code works internally.Good: “Scans a repository and generates an AGENTS.md file describing its capabilities”Bad: “Calls the scanner module, then the inferrer, then writes a file”
Use JSON Schema to define exactly what data agents need to provide and what they’ll receive back.This eliminates ambiguity and helps agents construct valid requests.
Examples show agents the exact syntax for using your capabilities.Include both simple and complex use cases when applicable.
Be crystal clear about how agents should authenticate:
  • none — no authentication required
  • bearer — requires Bearer token in Authorization header
  • api_key — requires API key (specify where: header, query param, etc.)

​
Key Sections Explained

​
Capabilities vs Endpoints

Capabilities describe high-level actions agents can perform. They might map to:
  • CLI commands (beacon generate)
  • API endpoints (POST /generate)
  • Library functions
  • Background services
Endpoints are the specific HTTP routes your API exposes, complete with methods, paths, and parameters. Beacon generates both when applicable — capabilities for the conceptual actions, endpoints for the concrete API routes.

​
Authentication Section

Defined in src/models.rs:47: 
pub struct Authentication {
    pub r#type: String,
    pub description: Option<String>,
}
This tells agents:
  1. What type of auth is required (bearer, api_key, none)
  2. How to use it (in the description field)
For example, Beacon’s own AGENTS.md specifies: 
**Type:** `none`

The Beacon API endpoints themselves do not require direct client authentication. AI provider API keys (e.g., GEMINI_API_KEY) must be configured as environment variables on the server running the Beacon service.

​
Rate Limits

Defined in src/models.rs:53: 
pub struct RateLimits {
    pub requests_per_minute: Option<u32>,
    pub requests_per_day: Option<u32>,
    pub notes: Option<String>,
}
Helps agents plan their usage and implement backoff strategies. Beacon enforces 20 requests per minute (see src/main.rs:37).

​
How Beacon Generates AGENTS.md

The generation happens in three phases (detailed in How It Works):
  1. Scan — Beacon reads your README, source files, package manifests, and OpenAPI specs (src/scanner.rs)
  2. Infer — An AI model analyzes the context and identifies capabilities, endpoints, and schemas (src/inferrer.rs)
  3. Generate — Beacon renders the structured data into the AGENTS.md format (src/generator.rs)
The rendering logic in src/generator.rs:12 transforms the internal AgentsManifest struct into markdown: 
fn render_markdown(m: &AgentsManifest) -> String {
    let mut out = String::new();
    out.push_str(&format!("# AGENTS.md — {}\n\n", m.name));
    out.push_str(&format!("> {}\n\n", m.description));
    // ... continues building the markdown structure
}

​
Schema Validation

Beacon includes a validator that checks AGENTS.md files against the specification. From the CLI: 
beacon validate ./AGENTS.md
With endpoint reachability checks: 
beacon validate ./AGENTS.md --check-endpoints
The validator ensures:
  • Required sections are present
  • JSON schemas are valid
  • Endpoints follow the correct format
  • (Optionally) declared endpoints are actually reachable

​
Beyond the Spec

While AGENTS.md follows the AAIF standard, Beacon’s implementation is opinionated about what makes repositories truly agent-ready:

Server-Side Capabilities

Beacon specifically looks for REST APIs, background services, and server-side endpoints — not just utility scripts.

Structured Schemas

Always includes JSON schemas for inputs and outputs when possible, reducing agent errors.

Concrete Examples

Generates real usage examples from your CLI commands or API patterns.

Provider Agnostic

Works with any AI provider, so agents aren’t locked into a specific LLM ecosystem.

​
Next Steps

How It Works

Dive into Beacon’s three-phase architecture

Generate Your First AGENTS.md

Create an AGENTS.md for your repository

AI Providers

Choose the right AI provider for your needs

AAIF Specification

Read the full AAIF standard

Build docs developers (and LLMs) love

Get started for freeTalk to us