Proposal: AGENTS.md v1.1: Making Implicit Semantics Explicit, Clarifying Scope, and Recommendation for Progressive Disclosure

# Preamble (or, why this proposal?)

AGENTS.md has achieved broad adoption, but many of its most important behaviors are currently implicit. Tool authors and end users rely on shared assumptions about how AGENTS.md files are discovered, layered, and prioritized, yet those assumptions are undocumented.

This proposal makes those implicit conventions explicit, without introducing breaking changes.

Specifically, it aims to:

* Codify existing best practices (hierarchical scope, precedence, progressive disclosure)
* Establish a shared understanding of how agents should handle AGENTS.md files
* Clarify that AGENTS.md is primarily about **behavioral expectations, rules, and constraints**
* Position AGENTS.md as complementary to—rather than competing with—SKILL.md

The goal is alignment and predictability, not enforcement.

# AGENTS.md v1.1 (Draft Proposal)

> A simple, open format for guiding AI agents with contextual instructions and behavioral expectations.

Think of AGENTS.md as a **README for agents**: a dedicated, predictable place to provide the context, conventions, and constraints that help AI coding agents work effectively in your project.

```md
# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
```

---

## Overview

README.md files are for humans: quick starts, project descriptions, and contribution guidelines.

AGENTS.md complements this by providing the extra context that AI coding agents need—build commands, testing conventions, code style preferences, and behavioral constraints that might clutter a README or aren't relevant to human contributors.

**Why a separate file?**

- **Gives agents a clear, predictable place for instructions.** Agents know to look for AGENTS.md files and can load them based on where they're operating.
- **Keeps READMEs focused on human contributors.** Agent-specific details don't dilute documentation meant for people.
- **Enables contextual guidance.** Different parts of a codebase can have different instructions, and AGENTS.md files can be placed throughout a project hierarchy.

AGENTS.md is an open format that works with any agent or tool that chooses to support it. Rather than introducing a proprietary configuration file, we chose a name and format that could work for anyone.

---

## Philosophy

AGENTS.md is guided by a small set of design principles:

### README for Agents

The guiding metaphor is simple: AGENTS.md is a README, but for agents instead of humans. It should contain the kind of information you'd tell a new teammate who happens to be an AI—how things work around here, what to watch out for, and what's expected.

### Guidance, Not Governance

AGENTS.md files are a lightweight communication channel for humans to provide contextual guidance to agents. The format describes behavioral expectations and preferences. An AGENTS.md file is advice from the project maintainer—agents should generally follow it, but the specification does not attempt to mandate or enforce perfect compliance, both with respect to the specification itself and with respect to instructional guidance found within an AGENTS.md file.

### Implementation Agnosticism

AGENTS.md does not prescribe how agent or harness authors should implement support for the format. Whether adherence to the specification is achieved through probabilistic prompting, deterministic harness mechanisms, or other approaches is left to implementers. The specification describes what should generally happen, not how or when it must happen.

### Intuitive and Pragmatic

While this specification takes a stance on expected behaviors—how multiple AGENTS.md files interact, how guidance accumulates, how agents should discover and load instructions—we are committed to conventions that are intuitive, simple, and align with what most people would expect anyway. If you've never read this specification but guessed how AGENTS.md files should work in a nested directory structure, you'd probably guess correctly. The specification codifies common sense rather than inventing new paradigms.

---

## How AGENTS.md Works

AGENTS.md files use the filesystem hierarchy to provide contextual, layered guidance. Understanding four key concepts will help you write effective AGENTS.md files and implement robust support for them.

### Jurisdiction

An AGENTS.md file applies to all files and subdirectories within its containing folder. A file at `./frontend/AGENTS.md` provides guidance for everything under `./frontend/`, but has no bearing on `./backend/` or other sibling directories.

```
project/
├── AGENTS.md                  # Applies to entire project
├── frontend/
│   ├── AGENTS.md              # Applies to frontend/ and below
│   └── components/
│       └── Button.tsx         # Governed by frontend/AGENTS.md
├── backend/
│   ├── AGENTS.md              # Applies to backend/ and below
│   └── api/
│       ├── AGENTS.md          # Applies to api/ and below
│       └── routes.ts          # Governed by backend/api/AGENTS.md
└── README.md
```

Jurisdiction is strictly ancestor-based. When an agent operates on a file, only AGENTS.md files in that file's directory or parent directories apply.

### Accumulation

Guidance accumulates as you traverse the directory tree. A local AGENTS.md file extends and builds upon the guidance in ancestor AGENTS.md files rather than replacing it entirely.

For example, if the root AGENTS.md establishes project-wide conventions (code style, commit message format) and `./frontend/AGENTS.md` adds React-specific guidance, an agent working in `./frontend/` should consider both sets of guidance together.

### Precedence

When guidance conflicts, more specific instructions take precedence over more general ones. Local AGENTS.md files override ancestor AGENTS.md files.

More broadly, the precedence chain in an agentic system that recognizes the AGENTS.md format would typically be as follows:

```
Highest priority
    ↓   LLM System Prompt
    ↓   Agent System Prompt  
    ↓   User Prompt
    ↓   Local AGENTS.md
    ↓   Ancestor AGENTS.md files (nearest first)
Lowest priority
```

User instructions override AGENTS.md guidance. A child AGENTS.md file can explicitly disable or modify guidance inherited from an ancestor. The specific syntax for expressing overrides is left to file authors.

### Implicit Inheritance

Guidance in an ancestor AGENTS.md file is implicitly inherited by all AGENTS.md files beneath it. There is no need for child AGENTS.md files to restate guidance already declared in ancestors—agents should treat the guidance as cumulative.

This means a leaf AGENTS.md file can be small and focused, containing only what's specific to that directory. Project-wide conventions belong in the root AGENTS.md.

---

## FAQ

### How does AGENTS.md relate to README.md?

When in use for a project, AGENTS.md is the primary source of behavioral guidance for agents. README.md is not a peer to AGENTS.md for agents; it is a fallback.

### How does AGENTS.md relate to SKILL.md?

AGENTS.md focuses on **behavior** (rules, constraints, workflows).
SKILL.md focuses on **capabilities** (what an agent knows how to do).

AGENTS.md can technically describe skills, but it is not optimized for that purpose. When both formats are used, AGENTS.md should avoid detailing skills and may reference SKILL.md instead.

The two formats are intended to be complementary.

---

## Specification

### Filename

The canonical filename is `AGENTS.md` (plural, uppercase, with `.md` extension). Implementations may support aliases (such as `AGENT.md`) for compatibility, but `AGENTS.md` is the standard.

### Format

AGENTS.md files are Markdown documents. The body content has no required structure—use whatever headings and organization best communicate your guidance.

### Optional Frontmatter

AGENTS.md files may optionally include YAML frontmatter to support progressive disclosure and efficient context management. Frontmatter enables agents and harnesses to build lightweight indexes of available guidance without loading full file contents upfront.

Frontmatter is optional because AGENTS.md files rely primarily on positional context—the path itself serves as the identifier. Frontmatter fields like `description` and `tags` aid in *selection* (helping agents decide when to load a file's full contents), but they're not required because filesystem position often provides sufficient context. Requiring frontmatter would break backwards compatibility with existing AGENTS.md files and add friction for simple use cases where the path alone is descriptive enough.

```md
---
description: React component conventions and testing patterns for the frontend.
tags: [react, components, vitest, frontend]
---

# Component Structure
...
```

#### Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `description` | No | A concise summary (recommended under 200 characters) of the guidance this file contains. |
| `tags` | No | A list of keywords that help agents identify when this guidance may be relevant. |

Unrecognized frontmatter fields should be ignored for forward compatibility.

#### When Frontmatter Helps

Frontmatter becomes valuable when:

- Filesystem position alone is ambiguous
- A project contains many AGENTS.md files
- The guidance within is specialized enough to warrant explicit description
- You want to aid agent discovery without requiring full file loads

### Validation

A valid AGENTS.md file:

- Is named `AGENTS.md` (case-sensitive, unless an implementation supports aliases)
- Contains valid Markdown
- If frontmatter is present, uses standard YAML frontmatter syntax (triple-dash `---` delimiters) with valid YAML

---

## For File Authors

### What to Include

AGENTS.md can contain any guidance that helps an agent work effectively in your project. Common sections include:

**Project context** — Brief orientation to what this part of the codebase does, key architectural decisions, or important background.

**Build and development commands** — How to install dependencies, run the development server, build for production.

**Testing instructions** — How to run tests, testing conventions, what to test.

**Code style and conventions** — Formatting preferences, naming conventions, patterns to follow or avoid.

**Constraints and boundaries** — Files or directories not to modify, actions requiring confirmation, security considerations.

**Workflow preferences** — Branch naming, commit message format, PR conventions.

### Best Practices

**Keep files focused.** A single AGENTS.md file should remain readable and digestible. As a guideline, aim for under 500 lines. If guidance becomes extensive, consider splitting across multiple AGENTS.md files in subdirectories or referencing external documentation.

**Put general guidance at the root.** Project-wide conventions, code style, and universal constraints belong in the root AGENTS.md. Use nested files for directory-specific guidance.

**Be specific and actionable.** Vague guidance is hard for agents to follow. Prefer concrete instructions over general principles.

**Update as your project evolves.** Treat AGENTS.md as living documentation. When conventions change, update the relevant AGENTS.md files.

### Examples

#### Root-Level AGENTS.md

```md
# Overview

This is a TypeScript CLI tool for processing markdown files.

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
```

#### Nested AGENTS.md With Frontmatter

`apps/frontend/AGENTS.md`

```md
---
description: React + TypeScript frontend app built with Vite.
tags: [frontend, react, vite]
---

# Overview

Main user-facing frontend package. Built with React, TypeScript, and Vite inside the monorepo.

## Dev environment tips
- Install deps: `pnpm install --filter frontend`
- Start dev server: `pnpm dev` (or `pnpm turbo run dev --filter frontend`)
- Default dev URL: `http://localhost:5173`
- Use configured path aliases instead of deep relative imports.

## Code style
- Function components and hooks only.
- TypeScript strict mode; avoid `any`.
- Keep components small and focused.
- Follow ESLint and Prettier defaults.

## Testing instructions
- Run all tests: `pnpm test`
- From repo root: `pnpm turbo run test --filter frontend`
- Single test: `pnpm vitest run -t "<test name>"`
- Add or update tests for changed components.

## PR instructions
- Title format: `[frontend] <Title>`
- Run `pnpm lint` and `pnpm test` before committing.
- Include screenshots for UI changes.
```

---

## For Implementers

This section provides guidance for agent and harness authors implementing AGENTS.md support.

### Progressive Disclosure

Rather than loading all AGENTS.md content upfront, agents benefit from discovering and loading files progressively based on where they are operating. This keeps context usage efficient and guidance relevant.

**Recommended approach:**

1. **Index** — At session start, scan for AGENTS.md files and extract paths and any frontmatter metadata.
2. **Inject index** — Provide the agent with a lightweight index of available AGENTS.md files.
3. **Load on demand** — Instruct the agent to load AGENTS.md files as needed for the task at hand.

### Index Format

When injecting an index of available AGENTS.md files into agent context, include the path and any available frontmatter. The specific format is left to implementers. Example formats:

**JSON:**

```json
[
  {
    "path": "AGENTS.md"
  },
  {
    "path": "frontend/AGENTS.md",
    "description": "React frontend conventions and component patterns.",
    "tags": ["react", "frontend", "components"]
  },
  {
    "path": "backend/AGENTS.md",
    "description": "REST API endpoint conventions and patterns.",
    "tags": ["backend", "api", "rest", "express"]
  }
]
```

**XML:**

```xml
<available_agents_files>
  <file>
    <path>AGENTS.md</path>
  </file>
  <file>
    <path>frontend/AGENTS.md</path>
    <description>React frontend conventions and component patterns.</description>
    <tags>react, frontend, components</tags>
  </file>
  <file>
    <path>backend/api/AGENTS.md</path>
    <description>REST API endpoint conventions and patterns.</description>
    <tags>backend, api, rest, express</tags>
  </file>
</available_agents_files>
```

**Markdown:**

```md
## Available AGENTS.md Files

- `AGENTS.md`
- `frontend/AGENTS.md`
  - Description: React frontend conventions and component patterns.
  - Tags: react, frontend, components
- `backend/AGENTS.md`
  - Description: REST API endpoint conventions and patterns.
  - Tags: backend, api, rest, express
```

### Probabilistic vs Deterministic Enforcement

While adherence to the AGENTS.md specification is often achieved probabilistically through prompting, harness authors may implement deterministic enforcement of certain directives where appropriate. For example, by injecting applicable AGENTS.md files into context when certain tools are invoked.

### Compaction and Summarization

This specification does not mandate how to handle compaction and summarization of AGENTS.md files. However, the following suggestions are provided for consideration:

#### What to Preserve During Compaction

When AGENTS.md content is compacted or summarized, implementations should prioritize preserving guidance that materially affects agent behavior.

**Preserve first:**

* Explicit constraints and prohibitions (“must not,” “do not,” “always”)
* Behavioral requirements (tests, workflows, review steps)
* Scope-specific overrides and deviations from ancestor guidance
* Required commands, flags, or execution ordering
* Architectural boundaries or invariants that affect correctness

**Lower priority and safe to compact or omit:**

* Explanatory or motivational prose
* Redundant inherited guidance
* Long examples or tutorials
* Non-critical stylistic preferences
* Information implied by directory structure or task context

When space is constrained, favor fewer, more directive instructions over broader but weaker guidance.

#### Avoid Duplicate Representations

An implementation should not retain both a summarized and a full representation of the same AGENTS.md file in context at the same time. If an AGENTS.md file has been compacted or summarized, implementers should either prevent the full file from being loaded again, or replace the summary with the full contents if the file becomes highly relevant later as the agent progresses through the task.

#### Allow Discard and Reload Based on Relevance

If context compaction determines that an AGENTS.md file is no longer relevant to the agent’s current scope of work, it may be discarded. If that file becomes relevant again later as the agent progresses, it should be reloaded and made available to the agent at that time.

---

## About

AGENTS.md emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory.

The format is stewarded by the Agentic AI Foundation under the Linux Foundation, with a commitment to maintaining AGENTS.md as an open standard that benefits the entire developer community.

---

## Changelog

### v1.1 (Proposal)

This proposal codifies implicit assumptions that the community has broadly adopted while preserving full backwards compatibility. All existing AGENTS.md files remain valid.

**Clarifications:**

- Explicit documentation of jurisdiction, accumulation, precedence, and inheritance semantics
- Recognition of three primary audiences: agents, file authors, and implementers
- Acknowledgement that agentic systems are inherently probabilistic and adherence to the specification represents expectations, not guarantees

**Additions:**

- Optional YAML frontmatter (`description`, `tags`) to support progressive disclosure
- Guidance for implementers on index formats and progressive loading
- Design principles section articulating the spec's philosophy

**Unchanged:**

- Filename convention (`AGENTS.md`)
- Markdown format with no required structure
- Flexibility in content and organization


Field	Required	Description
`description`	No	A concise summary (recommended under 200 characters) of the guidance this file contains.
`tags`	No	A list of keywords that help agents identify when this guidance may be relevant.

Proposal: AGENTS.md v1.1: Making Implicit Semantics Explicit, Clarifying Scope, and Recommendation for Progressive Disclosure #135

Description

Preamble (or, why this proposal?)

AGENTS.md v1.1 (Draft Proposal)

Overview

Philosophy

README for Agents

Guidance, Not Governance

Implementation Agnosticism

Intuitive and Pragmatic

How AGENTS.md Works

Jurisdiction

Accumulation

Precedence

Implicit Inheritance

FAQ

How does AGENTS.md relate to README.md?

How does AGENTS.md relate to SKILL.md?

Specification

Filename

Format

Optional Frontmatter

Frontmatter Fields

When Frontmatter Helps

Validation

For File Authors

What to Include

Best Practices

Examples

Root-Level AGENTS.md

Nested AGENTS.md With Frontmatter

For Implementers

Progressive Disclosure

Index Format

Probabilistic vs Deterministic Enforcement

Compaction and Summarization

What to Preserve During Compaction

Avoid Duplicate Representations

Allow Discard and Reload Based on Relevance

About

Changelog

v1.1 (Proposal)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions