Agents Md

AGENTS.md

Audit, evaluate, create, and maintain AGENTS.md files across a repository to optimize project memory and context for AI assistants.

Use the open AGENTS.md format reference at https://agents.md/ for baseline conventions: AGENTS.md is plain Markdown with no required fields. Nested files can scope instructions by directory but are optional (root file is sufficient). Repo evidence and explicit user instructions still govern the concrete content you write.

Quick start

Run this flow to check or create AGENTS.md: 1. Scan for existing AGENTS.md and CLAUDE.md files, and check if CLAUDE.md is already a symbolic link pointing to AGENTS.md. 2. Ask the user (via interactive prompts or user questions) if they want to maintain Claude Code compatibility. If `CLAUDE.md` is already a symbolic link pointing to `AGENTS.md`, skip this step and automatically proceed under the assumption that compatibility is desired. 3. Choose the target AGENTS.md explicitly before editing. 4. Generate or improve AGENTS.md with build/test/run commands, code styles, and workflows. 5. If Claude compatibility is active or selected, establish/verify the symbolic link from CLAUDE.md to AGENTS.md and explain it in AGENTS.md.

Workflows

1. Discovery & Quality Assessment

Check for file locations:

find . -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.md" 2>/dev/null | head -50

Evaluate existing files using references/quality-criteria.md rubrics. Output a Quality Report before editing.

Choose the target AGENTS.md explicitly:

• If exactly one AGENTS.md exists, use it.
• If multiple files exist, prefer the nearest AGENTS.md that governs the user's requested path or current working directory; otherwise ask before editing.
• In nested repositories or monorepos, the closest AGENTS.md to the edited files has precedence for that subtree (nested files are optional).
• If none exists, create the root AGENTS.md unless the user requested a narrower package/module path.

2. Interactive Compatibility Check

Before writing:

• Check if `CLAUDE.md` is already a symbolic link to `AGENTS.md` (e.g., using ls -la CLAUDE.md or checking file properties).
• If already a symbolic link: Skip the confirmation prompt entirely and automatically proceed under the assumption that compatibility is desired.
• If `CLAUDE.md` already exists and is not the intended symlink: Do not replace it blindly. Read it, summarize any unique instructions, propose how to migrate them into AGENTS.md, and ask for explicit approval before moving or replacing the file.
• Otherwise: Prompt the user:

"Do you want to maintain Claude Code compatibility? (This will symlink CLAUDE.md to AGENTS.md and add an explanation block)"

3. Creation & Updates

• Build/update AGENTS.md following templates in references/templates.md.
• If compatibility is active or selected:
• Create the symlink only when CLAUDE.md is absent or already the intended symlink.
• If a regular CLAUDE.md exists, preserve its contents until the user approves migration and replacement.
• Add the explanation block to AGENTS.md.
• Add CLAUDE.md overrides (if any) to AGENTS.md or as separate imports.

4. Knowledge Writeback (on problem-solving)

When solving a problem reveals non-obvious knowledge (e.g. a gotcha, hidden config, env var quirk, non-intuitive framework behavior), the agent MUST: 1. Extract reusable insight: Distill the raw finding into a concise, durable rule (not a bug-fix transcript). 2. Propose the writeback: Present the candidate snippet to the user and ask:

"This insight may be worth preserving. Shall I add it to AGENTS.md?"

3. Write on approval only: Update the most relevant AGENTS.md only after explicit user confirmation. 4. Apply quality filters before writing (see references/quality-criteria.md):

• Must be non-derivable from the codebase alone.
• Must not be a drifting metric or overly generic rule.
• Must be concise (prefer one bullet point).

Advanced features

For quality assessment rubrics, detailed grading criteria, and red flags, see references/quality-criteria.md. For complete AGENTS.md starter templates and imports guide, see references/templates.md. For step-by-step mock execution cases and interactive prompts, see references/examples.md.

Examples & Shell Patterns for agents-md

This file documents example flows and mock transcripts for executing the agents-md skill.

---

Example 1: Creating a brand new AGENTS.md with Claude compatibility

Scenario

The codebase does not contain an AGENTS.md or CLAUDE.md. The agent discovers this and guides the user.

Flow

1. Discovery & Assessment The agent runs the discovery command:

   find . -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.md" 2>/dev/null | head -50

No files are found. The agent reports:

AGENTS.md Quality Report: Score: F (No AGENTS.md file found).

2. Compatibility Query The agent prompts the user to determine if they want to maintain Claude Code compatibility:

Interactive Prompt:

"Would you like to maintain compatibility with Claude Code by symlinking CLAUDE.md to AGENTS.md?"

- Option 1 (Recommended): Yes, create CLAUDE.md as a symlink and explain it in AGENTS.md

- Option 2: No, only create AGENTS.md

3. Symlink and File Setup If the user selects "Yes...", the agent runs:

   ln -s AGENTS.md CLAUDE.md

And writes AGENTS.md incorporating the starter template along with the compatibility explanation block:

   # Project Developer Guidelines

   ## Quick Commands
   - Build: npm run build
   - Test: npm test

   ## Claude Code Compatibility

   > [!NOTE]
   > This repository maintains compatibility with Claude Code. The file `CLAUDE.md` is a symbolic link pointing to `AGENTS.md`. 
   > All commands, style guides, and workflows defined in `AGENTS.md` apply to both Antigravity and Claude Code.
   > **DO NOT** delete the `CLAUDE.md` symbolic link or edit it independently; all guidelines must be updated directly in `AGENTS.md`.

---

Example 2: Auditing and Updating an Existing AGENTS.md

Scenario

An AGENTS.md exists but lacks style guides and quick test commands.

Flow

1. Discovery The agent finds ./AGENTS.md.

2. Quality Assessment Report The agent outputs:

### AGENTS.md Quality Report

Current Score: B (75/100)

Gaps Identified:

- Testing commands are listed but missing faster single-file test options.

- Lacks specific guidelines on CSS styles or typescript coding patterns.

3. Apply Improvements The agent keeps existing commands but refines the style instructions and updates AGENTS.md with targeted edits.

---

Example 3: Auditing an Existing AGENTS.md where CLAUDE.md is already a symlink

Scenario

An AGENTS.md exists and CLAUDE.md is already a symbolic link pointing to AGENTS.md.

Flow

1. Discovery & Symlink Verification The agent scans the workspace root and finds ./CLAUDE.md is already a symbolic link to ./AGENTS.md (e.g., using ls -la or checking file properties).

2. Quality Assessment Report The agent evaluates the file and outputs the Quality Report.

3. No Prompt Confirmation The agent skips the interactive query entirely since compatibility is already active.

4. Apply Improvements The agent updates AGENTS.md directly while preserving or standardizing the Claude Code Compatibility section.

---

Example 4: Existing CLAUDE.md is not a symlink

Scenario

A repository has AGENTS.md and a regular CLAUDE.md file with separate instructions.

Flow

1. Discovery & Safety Check The agent detects that CLAUDE.md exists and is not the intended symlink to AGENTS.md.

2. Preserve Before Replacing The agent reads CLAUDE.md, compares it with AGENTS.md, and summarizes unique instructions that would be lost if the file were replaced.

3. Explicit Migration Proposal The agent asks the user whether to migrate the unique instructions into AGENTS.md and replace CLAUDE.md with a symlink.

4. Apply Only After Approval After approval, the agent updates AGENTS.md, moves or removes the old CLAUDE.md according to the agreed plan, and creates the symlink with:

   ln -s AGENTS.md CLAUDE.md

Quality Criteria & Assessment Rubrics for AGENTS.md

This document defines the metrics and evaluation checklist used to assess and score the quality of AGENTS.md (and CLAUDE.md) files in repositories.

---

1. Quality Assessment Checklist

An effective instruction file provides precise, developer-level constraints that the AI cannot guess merely by browsing the codebase.

Evaluation Criteria

---

2. Quality Scores

Grade A (90-100): Highly Actionable & Current

• The file is concise (under 100 lines) and dense.
• Has exact command strings for building, testing, linting, and formatting.
• Documents single-test commands to save agent time and resources.
• Outlines directory layouts and core logic files.
• Up-to-date with current technologies used in the repository.

Grade B (70-89): Minor Gaps

• Commands and basic patterns are well-documented.
• Missing single-file test options or minor architectural pointers.
• Slight verbosity or minor boilerplate.

Grade C (50-69): Basic Information Only

• Contains basic build commands.
• Lacks architecture overview, styles, or linting commands.
• Outdated tech descriptions or minor stale paths.

Grade D (30-49): Sparse & Drifted

• Missing essential run or test commands.
• Contains extremely vague instructions like "write clean code" or "make it perfect".
• Significant parts of the document do not match the current codebase.

Grade F (0-29): Critically Flawed / Missing

• File does not exist, or is completely broken.
• Commands lead to immediate errors upon execution.

---

3. Red Flags & Anti-Patterns (To Be Eliminated)

When auditing AGENTS.md, look for and immediately eliminate these elements:

• Derivable State / Drifting Metrics: Do not hardcode metrics that constantly change, such as:
• "The codebase has 25 unresolved issues"
• "Current test coverage is 85%"

These drift instantly and lead to stale instructions.

• Overly Generic Rules: Avoid boilerplate statements like:
• "Always write comments."
• "Do not introduce syntax errors."
• "Use clean functions."

AI agents already know these by default; putting them in AGENTS.md wastes token space and dilutes critical instructions.

• Stale File Paths: Documenting file-by-file structures. If files are renamed, the document drifts. Link to high-level folders instead.
• Verbose Explanations: Long prose describing concepts (e.g. explaining how React state works). Focus on constraints and rules, not tutorials.

---

4. Knowledge Writeback Criteria

When an agent proposes writing back a newly discovered insight, evaluate it against these gates:

✅ Write-back eligible (must meet ALL)

❌ Do NOT write back

• Step-by-step debugging transcripts ("First I tried X, then Y…")
• One-off workarounds specific to a single bug instance
• Information already derivable from package.json, tsconfig.json, etc.
• Metrics that will drift (counts, percentages, timestamps)

Templates & Formatting for AGENTS.md

This document provides starter structures, formatting rules, and imports configuration for AGENTS.md files.

Reference the open AGENTS.md format at https://agents.md/. AGENTS.md is plain Markdown with no required fields; common useful sections include project overview, build and test commands, code style, testing instructions, and security considerations. In monorepos, nested AGENTS.md files can scope instructions to subprojects (nested files are optional), and the closest AGENTS.md to the edited file wins.

---

1. AGENTS.md Starter Template

Use this starter template when creating a new AGENTS.md file. Adjust the commands and folder layouts depending on the detected build and test frameworks.

# [Project Name] Developer Guidelines

## Quick Commands
- Build: <command> (e.g., npm run build)
- Test: <command> (e.g., pytest)
- Lint/Format: <command> (e.g., npx eslint .)
- Run Dev: <command> (e.g., npm run dev)

## Architecture Overview
- `/src`: Main application logic
  - `/src/components`: UI components
  - `/src/hooks`: Custom React hooks
- `/tests`: Automated test suites

## Code Style & Conventions
- <Language/framework conventions verified from repo files, e.g. package manifests, config files, and existing code>
- <Formatting/linting conventions backed by config or nearby code>
- <Module boundaries or file organization rules that are specific to this repository>

## Workflows
- **Testing**: Before submitting a PR, always run tests locally. Prefer testing a single file for speed: `npm run test -- <filepath>`.
- **Git**: Branch name format: `feature/<desc>` or `bugfix/<desc>`.

---

2. Claude Code Compatibility Section

If the user requests compatibility with Claude Code, append this exact section to the bottom of AGENTS.md:

## Claude Code Compatibility

> [!NOTE]
> This repository maintains compatibility with Claude Code. The file `CLAUDE.md` is a symbolic link pointing to `AGENTS.md`. 
> All commands, style guides, and workflows defined in `AGENTS.md` apply to both Antigravity (and other agentic assistants) and Claude Code.
> **DO NOT** delete the `CLAUDE.md` symbolic link or edit it independently; all guidelines must be updated directly in `AGENTS.md`.

Create the symbolic link in the repository root only when CLAUDE.md is absent or already points to AGENTS.md:

ln -s AGENTS.md CLAUDE.md

If CLAUDE.md already exists and is not the intended symlink, do not replace it blindly. Read it, preserve any unique instructions, propose a migration into AGENTS.md, and ask for explicit approval before moving or replacing the file.

---

3. Advanced Imports and References

To maintain modularity and avoid overloading AGENTS.md with every detail, use imports for auxiliary guidelines (supported by agent systems including Claude Code):

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

• @path/to/file tells the agent to load the referenced file on-demand.
• Keep references to auxiliary files separated to save context token usage.

---

4. Lessons Learned Section (Optional)

Add this section to AGENTS.md only when the project has accumulated non-obvious institutional knowledge discovered through problem-solving. Keep it short and prune stale entries regularly.

## Lessons Learned
- <Short rule or gotcha, e.g. "Running `npm test` without `--forceExit` hangs in CI due to an open DB connection in `src/db/client.ts`">
- <Another non-obvious constraint discovered in practice>

[!TIP]

This section is a quality signal: if it grows beyond 5–7 bullets, consider promoting entries to

the relevant section (Commands, Architecture, etc.) and deleting them here.