Skip to content
/
Tier B A13 Methodology

AGENT.md

agent-md · agentmd/agent.md · ★ 80 · last commit 2025-07-10

Primitive shape
No installable primitives
00

Summary

AGENT.md — Summary

Field Value
slug agent-md
display_name AGENT.md
github_url https://github.com/agentmd/agent.md
stars 80
license MIT
language (none — markdown only)
last_commit 2025-07-10
contributors 1 (Geoffrey Huntley, Sourcegraph)
maintainer_status dormant (no commits since July 2025)
version_analyzed "Informational, July 2025"

One-liner

AGENT.md is a competing format specification to AGENTS.md, authored by Geoffrey Huntley at Sourcegraph as an RFC-style document proposing a single universal AGENT.md file that all AI coding tools should read in place of tool-specific config files.

What it is

A single-file specification (the entire project IS the README.md). The repo contains CNAME, LICENSE, and README.md only — no code. The README is written in RFC style with Abstract, Introduction, Specification, Implementation Guidelines, Migration Commands, Tool Integration, and IANA Considerations sections.

The specification is direct competition with AGENTS.md. The author explicitly states: "we like AGENT.md because we own the domain name for https://agent.md and we are committed to keeping it vendor-neutral... but we're willing to compromise."

Status

Dormant. Created July 9, 2025; last commit July 10, 2025. As of the analysis date (May 2026), 10 months with no activity. The project did not gain traction against AGENTS.md (21,710 stars vs 80).

Quality

quality: tier-b — comprehensive RFC-style specification, but project is dormant and did not win the naming war. The specification itself is well-written with clear migration commands. No code primitives to analyze beyond the markdown document.

01

Overview

AGENT.md — Overview

Problem Solved

The same as AGENTS.md, stated differently:

"Right now it's a mess for consumers. They have to maintain separate config files for each tool they want to use: .cursorrules, .windsurfrules, .clauderules, and a dozen other files scattered across tools. Every other day another agent is brought to market with its own convention which worsens the mess."

AGENT.md proposes consolidating all tool-specific instruction files into a single AGENT.md at the project root, with symbolic links pointing from the old tool-specific locations to the new canonical file.

The Specification

The spec is RFC-influenced (uses MUST/SHOULD/MAY from RFC 2119) and defines:

Mandatory

  • File MUST be placed in project root
  • File MUST use Markdown formatting
  • Sections: project structure, build/test/dev commands, code style, architecture, testing, security
  • Support multiple AGENT.md files in subdirectories (more specific overrides general)
  • Merge configurations from multiple files with specificity precedence
  • User-global file at ~/.config/AGENT.md for personal preferences

Optional (MAY)

  • File references using @-mentions (e.g., @filename.md) to include additional context

Migration Strategy

The specification's primary tactical contribution is a per-tool migration command table:

# Claude Code
mv CLAUDE.md AGENT.md && ln -s AGENT.md CLAUDE.md

# Cursor
mv .cursorrules AGENT.md && ln -s AGENT.md .cursorrules

# Windsurf
mv .windsurfrules AGENT.md && ln -s AGENT.md .windsurfrules

# Cline
mv .clinerules AGENT.md && ln -s AGENT.md .clinerules

# GitHub Copilot
mv .github/copilot-instructions.md AGENT.md && ln -s ../../AGENT.md .github/copilot-instructions.md

The approach: rename the canonical file to AGENT.md, symlink old locations to it.

Organizational Backing

  • Author: Geoffrey Huntley
  • Organization: Sourcegraph, Inc.
  • Native support in Amp (Sourcegraph's agent) since 2025-05-07
  • Domain: https://agent.md (owned by Sourcegraph)

Explicit Competitive Positioning

The specification directly names the competition: Gemini CLI, OpenAI Codex, and OpenCode support AGENTS.md — the migration command for those three is ln -s AGENTS.md AGENT.md (the reverse direction), acknowledging that AGENTS.md had already captured those tools.

02

Install Setup

AGENT.md — Install & Setup

Installation

There is no installer. Adoption is:

  1. Create a file named AGENT.md in the project root.
  2. Write markdown content following the recommended structure.
  3. Create symbolic links from tool-specific locations to AGENT.md.

Per-Tool Migration Commands

The specification provides explicit migration commands for every major tool:

# Cline
mv .clinerules AGENT.md && ln -s AGENT.md .clinerules

# Claude Code
mv CLAUDE.md AGENT.md && ln -s AGENT.md CLAUDE.md

# Cursor
mv .cursorrules AGENT.md && ln -s AGENT.md .cursorrules

# Firebase Studio
ln -s AGENT.md .idx/airules.md

# Gemini CLI, OpenAI Codex, OpenCode (these tools use AGENTS.md natively)
ln -s AGENTS.md AGENT.md

# GitHub Copilot
mv .github/copilot-instructions.md AGENT.md && ln -s ../../AGENT.md .github/copilot-instructions.md

# Replit
mv .replit.md AGENT.md && ln -s AGENT.md .replit.md

# Windsurf
mv .windsurfrules AGENT.md && ln -s AGENT.md .windsurfrules

Note: For Gemini CLI, OpenAI Codex, and OpenCode — which natively use AGENTS.md — the migration is a symlink FROM AGENTS.md TO AGENT.md (not the other direction). This acknowledges these tools won't read AGENT.md directly.

  • Amp (Sourcegraph): Native support since 2025-05-07. Multiple AGENT.md files since 2025-07-07.

Runtime Requirements

None. No tooling, no runtime, no dependencies.

Configuration

No configuration system. The format is plain markdown.

Versioning

The document is dated "July 2025" with status "Informational." No semantic versioning.

Hierarchical Setup

For monorepos or multi-component projects:

/
  AGENT.md                  ← global project instructions
  packages/
    frontend/
      AGENT.md              ← frontend-specific (overrides root)
  ~/.config/AGENT.md        ← user-global personal preferences

The specification explicitly mentions user-global AGENT.md at ~/.config/AGENT.md — a feature not mentioned in the AGENTS.md specification.

03

Commands Skills

AGENT.md — Commands & Skills

Commands

None. AGENT.md defines no commands, slash-commands, or CLI primitives.

Skills

None.

Subagents

None.

Hooks

None.

Scripts

None. The repository has no scripts.

@-Mentions (File References)

The specification's one unique primitive beyond base AGENTS.md: AGENT.md files MAY use @-mentions to reference other files.

# MyApp Project

@ARCHITECTURE.md
@docs/conventions.md

When a compatible tool encounters @filename.md, it SHOULD include the referenced file's content as additional context. This allows authors to keep specialized documentation in its own file and reference it from AGENT.md rather than embedding everything.

This feature is defined as MAY (optional) and is only supported by tools that explicitly implement it. Amp supports @-mentions natively.

Recommended Content Sections

The specification lists recommended sections (not required):

  1. Project Overview — brief description, architecture summary
  2. Build & Commands — dev, test, deployment commands
  3. Code Style — formatting, naming, linting conventions
  4. Testing — frameworks, patterns, coverage requirements
  5. Security — data protection, secrets management guidelines
  6. Configuration — environment setup, config management
  7. Git Workflow — commit conventions, branch rules, push restrictions

These sections match the structure shown in the detailed example AGENT.md in the specification.

Behavioral Enforcement

Unlike AGENTS.md (which relies on agent interpretation), AGENT.md's specification uses RFC 2119 language (MUST/SHOULD/MAY) for both the format and for the instructions agents must follow within the file. This is a specification-level difference, though runtime enforcement depends on the agent implementation.

05

Memory State

AGENT.md — Memory & State

State Storage

AGENT.md is the single state file. No additional state management.

File Purpose
AGENT.md Project instructions read by compatible agents
<subdir>/AGENT.md Scoped instructions for subdirectory (optional)
~/.config/AGENT.md User-global personal preferences (optional)

Persistence Model

File-based, version-controlled. Symlinks at old tool-specific locations (CLAUDE.md, .cursorrules, etc.) point back to AGENT.md, allowing multiple tools to share one canonical source.

Cross-Session Handling

Automatic — committed to the repo, always present.

Unique Addition vs AGENTS.md

AGENT.md specifies a user-global location (~/.config/AGENT.md) for personal agent preferences, not tied to any project. This three-tier hierarchy (global → project root → subdirectory) is more complete than the AGENTS.md specification's project-only scope.

@-Mention File Inclusion

AGENT.md supports @-mentions to include other files' content at read time. This enables a composition model where large specifications are split across files:

# MyApp Project
@docs/architecture.md
@docs/testing-guidelines.md

This is the nearest thing AGENT.md has to a structured memory system — not dynamic/searchable, but allows reference-based context expansion beyond the base file.

Memory Classification

  • Type: static-file with optional @-include references
  • Scope: project + optional global user preferences
  • Mutability: human-edited (or agent-edited with write access)
  • Indexing: none
09

Uniqueness

AGENT.md — Uniqueness & Positioning

The AGENTS.md vs AGENT.md Schism

This is the defining context for this framework. The full picture:

Dimension AGENT.md (this framework) AGENTS.md
Stars 80 21,710
Origin Sourcegraph/Amp (Geoffrey Huntley) Codex CLI convention (community)
Organization Sourcegraph, Inc. 20+ community contributors
Status Dormant (last commit: 2025-07-10) Active (last commit: 2026-03-12)
Specification style RFC-style with MUST/SHOULD/MAY FAQ + minimal README
@-mentions Yes (MAY) No
Global user file ~/.config/AGENT.md Not specified
Native tool support Amp only 23+ tools
Domain agent.md (owned by Sourcegraph) agents.md
Migration stance "rename everything to AGENT.md" "rename everything to AGENTS.md"

Who Won

By every measurable signal, AGENTS.md won. The 270x star ratio, 23 tools vs 1, and the AGENT.md specification's own acknowledgment ("Gemini CLI, OpenAI Codex, OpenCode — symlink in reverse direction") confirm this.

The AGENT.md specification was published July 2025. The last commit was July 10, 2025 — one day after creation. The project has been dormant for 10 months as of the analysis date.

Why the Schism Happened

The schism was fundamentally a namespace dispute between:

  • Community-first standard: AGENTS.md emerged organically from Codex CLI adoption
  • Vendor-backed RFC: AGENT.md was a deliberate attempt by Sourcegraph (through Amp) to own the canonical naming

The AGENT.md README explicitly explains the strategic motivation: "we own the domain name for https://agent.md and we are committed to keeping it vendor-neutral." The domain ownership was positioned as a trust signal — neutral infrastructure vs. community convention.

This argument did not persuade the market.

Technical Differentiators

Despite losing the naming war, AGENT.md's specification has two genuine technical contributions over AGENTS.md:

  1. User-global file (~/.config/AGENT.md): AGENTS.md has no concept of user-level preferences separate from project-level instructions. AGENT.md's three-tier hierarchy (global → project → subdirectory) is more complete.

  2. @-mention file inclusion: AGENTS.md has no mechanism to reference external files. AGENT.md's @filename.md pattern enables composable specifications.

Whether these features get implemented by other tools is moot given dormancy, but they represent real design thinking.

The Compromise Signal

The README contains: "we're willing to compromise." This links to an X/Twitter post by sqs (Quinn Slack, Sourcegraph CEO) from around May 2025, before AGENT.md was published. The compromise that was offered (and apparently not accepted) would have resulted in the two camps unifying on one name — either AGENT.md or AGENTS.md. The lack of compromise materialized as AGENT.md publishing their own spec and losing adoption anyway.

Differs From Seeds

No direct seed match. Like AGENTS.md, closest to agent-os (Archetype 4) but even more minimal — agent-os at least has a command-based install system. AGENT.md is the purest possible Archetype 4: a single markdown file with no code primitives whatsoever.

The RFC-style formatting (MUST/SHOULD/MAY, IANA Considerations section) is unique in the Phase D batch corpus — AGENT.md is the only framework that explicitly models itself as an internet standards document. The IANA section acknowledges "this document does not require any IANA actions" but including the section signals intent to participate in standards governance.

Compared to AGENTS.md in the same batch: AGENT.md is more technically rigorous but lost on adoption. This is a classic "better specification, worse timing/positioning" outcome.

Historical Significance

AGENT.md is a useful historical record of the naming competition that happened in mid-2025. The @-mention syntax and user-global file concepts it introduced may eventually influence future format specifications even if AGENT.md itself remains dormant.

04

Workflow

AGENT.md — Workflow

No Workflow Phases

AGENT.md defines no workflow phases. Like AGENTS.md, it is a passive context file read by agents at session start.

Specification-Prescribed Tool Behavior

The spec defines how tools SHOULD behave when consuming AGENT.md:

  1. Parse AGENT.md during project initialization
  2. Extract relevant configuration for the tool's specific use case
  3. Provide fallback behavior when AGENT.md is not present
  4. Respect existing tool-specific config files for backward compatibility

Conflict Resolution

When multiple AGENT.md files exist:

  • More specific files (subdirectories) take precedence over general ones (root)
  • User-global ~/.config/AGENT.md is least specific (global preferences)
  • No spec-defined behavior for intra-file contradictions

Approval Gates

None.

Adoption Path Timeline

  1. Create AGENT.md in project root
  2. Migrate tool-specific files using per-tool symlink commands
  3. All tools now read from single source of truth

Relationship to the AGENTS.md Workflow

For tools that use AGENTS.md natively (Codex, Gemini CLI), the AGENT.md specification's migration command is ln -s AGENTS.md AGENT.md — the spec acknowledges that the AGENTS.md ecosystem has those tools locked in. The reverse migration (mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md) is listed in the AGENTS.md FAQ.

This bidirectional symlink situation means, in practice, developers can use either filename as the canonical source — both specifications accommodate the other through symlink compatibility.

Living Document Model

The spec states content SHOULD evolve with the project, similar to AGENTS.md's "treat as living documentation" guidance.

06

Memory Context

AGENT.md — Memory & Context (Extended)

Three-Tier Hierarchy

AGENT.md defines a three-tier context hierarchy not present in AGENTS.md:

  1. Global: ~/.config/AGENT.md — user's personal preferences (least specific)
  2. Project root: AGENT.md — project-wide instructions
  3. Subdirectory: <subdir>/AGENT.md — subsystem-specific instructions (most specific)

More specific files take precedence over less specific ones. Tools SHOULD merge configurations.

@-Mention Composition

Files can reference other files by name:

@ARCHITECTURE.md
@docs/api-conventions.md

This is a lightweight context-expansion mechanism — instead of a monolithic AGENT.md, authors can maintain specialized docs and compose them by reference.

Context Window Consideration

Like AGENTS.md, AGENT.md provides no guidance on context window management. Large AGENT.md files or deeply nested @-mention chains could consume significant context budget, but the specification does not address this.

Comprehensive Example

The specification includes a detailed example AGENT.md (~60 lines) covering:

  • TypeScript strict mode configuration
  • Specific lint commands and when to run them
  • Test file naming patterns (*.test.ts, *.spec.ts)
  • Git workflow rules (NEVER use git push --force on main)
  • Port assignments for dev services
  • Exact TypeScript conventions (use "URL" not "Url", tabs not spaces for TS but spaces for YAML)

This level of specificity is the specification's recommendation for what belongs in AGENT.md — exact, actionable instructions rather than vague guidance.

Snapshot as of Analysis

The spec's example shows ~/.config/AGENT.md for personal preferences. This feature enables user-specific behaviors (preferred response style, personal coding conventions) that should apply across all projects without modifying project files.

07

Orchestration

AGENT.md — Orchestration

Multi-Agent

No — AGENT.md is a single-file format convention. No orchestration layer.

Orchestration Pattern

None. The format is consumed passively by a single agent.

Execution Mode

Passive context. AGENT.md is read, not executed.

Multi-Model

Not applicable. Format is model-agnostic.

Cross-Tool Portability

By design, AGENT.md aims for maximum portability. However, in practice:

Native support (no symlink needed):

  • Amp (Sourcegraph)

Symlink-supported (works via backward-compatibility links):

  • Claude Code, Cursor, Windsurf, Cline, GitHub Copilot, Firebase Studio, Replit

Reverse direction (AGENTS.md is canonical, AGENT.md symlinks to it):

  • Gemini CLI, OpenAI Codex, OpenCode

The "reverse direction" tools are a significant admission: for those three tools, AGENTS.md has already won, and AGENT.md support requires pointing AGENT.md at AGENTS.md (i.e., the opposite of what the spec proposes).

Amp-Specific Features

Within Amp, AGENT.md supports:

  • Multiple AGENT.md files per repo (since 2025-07-07)
  • @-mention file inclusion
  • User-global ~/.config/AGENT.md

These features are Amp-native and may not be supported in other tools.

Organizational Coordination Claim

The specification states: "The Amp team is working with other agentic coding tool makers to clean up this mess of filenames." As of the analysis date (May 2026), this coordination effort did not result in industry-wide adoption of AGENT.md over AGENTS.md.

08

Ui Cli Surface

AGENT.md — UI / CLI Surface

CLI Binary

None. The specification has no CLI.

Local UI

None. The project has no website beyond the agent.md domain (which hosts the README content at https://agent.md/).

Website

The repository sets a CNAME to agent.md, indicating the README is served at https://agent.md/. Unlike agentsmd/agents.md (which has a full Next.js site with compatibility tables, examples, FAQs), the agent.md website appears to simply render the README.md.

Repository Structure

The entire project is three files:

  • CNAME — DNS configuration pointing to agent.md
  • LICENSE — MIT
  • README.md — the entire specification

This is the minimal viable specification repository — no build system, no tooling, no website code.

Authoring UX

Same as AGENTS.md: open any editor, create AGENT.md, write markdown. No tooling required.

Format Authoring Guidance

The specification provides a ~60-line example AGENT.md that serves as a template. This is more opinionated than AGENTS.md (which shows a minimal 20-line example). The AGENT.md example demonstrates:

  • Exact command-line instructions with flags
  • Port numbers for development services
  • Specific TypeScript configuration rules
  • Git workflow prohibitions (NEVER use git push --force on main)

Observability

None. No audit log, no compliance tracking, no verification that agents followed the instructions.

Related frameworks

same archetype · same primary tool · same memory type

Context-Engineering Handbook ★ 9.0k
A13 Methodology

Provides a first-principles, research-grounded vocabulary and learning path for context engineering — the discipline of designing…

walkinglabs/learn-harness-engineering ★ 6.6k
A13 Methodology

Teach harness engineering from first principles (12 lectures + 6 projects) and provide a scaffolding skill (harness-creator) that…

Awesome Harness Engineering (walkinglabs) ★ 2.7k
A13 Methodology

Curate the authoritative reference list of articles, benchmarks, and tools for harness engineering — the practice of shaping the…

cline-memory-bank (nickbaumann98) ★ 581
A13 Methodology

Custom instructions + 6-file hierarchical Markdown memory bank so Cline maintains full project context across sessions, with a…

FPF (First Principles Framework) ★ 372
A13 Methodology

Provides a formal pattern language for making reasoning explicit, traceable, and publishable in mixed human/AI engineering work —…

nexu-io/harness-engineering-guide ★ 134
A13 Methodology

Provide a practical, code-first reference guide to harness engineering — from first principles to production patterns —…