# Agents Md

> Create, verify, and improve AGENTS.md files. Minimal, focused, progressive disclosure. Fixes bloat, contradictions, stale info.

- Skill: `dimitrigilbert/agents-md` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add dimitrigilbert/agents-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dimitrigilbert/agents-md/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dimitrigilbert (https://skillmd.com/u/dimitrigilbert)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dimitrigilbert/agents-md

---


This skill provides expert guidance for creating, verifying, and improving AGENTS.md files - the open standard format for guiding AI coding agents.

## What is AGENTS.md?

AGENTS.md is a simple, open format for guiding coding agents, used by over 60k open-source projects. Think of it as a README for agents: a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project.

**Key principle:** Unlike README.md (which is for humans), AGENTS.md contains the extra, detailed context coding agents need: build steps, tests, conventions, and instructions that might clutter a README.

**Learn more:** https://agents.md/ | https://www.aihero.dev/a-complete-guide-to-agents-md

## Quick Start

### When users want to create an AGENTS.md file

Start by asking these clarifying questions:

1. **Project type:** Monorepo or single package?
2. **Tech stack:** What languages/frameworks?
3. **Package manager:** npm, pnpm, yarn, bun, or something else?
4. **Build/test commands:** Any non-standard commands?
5. **Specific concerns:** Any patterns you want to encourage or avoid?

Then create a minimal AGENTS.md following the template below.

### When users want to verify an existing AGENTS.md

Run through the verification checklist (see [Verification](#verification) below).

### When users want to improve an existing AGENTS.md

Assess the file and suggest progressive disclosure refactoring (see [Improvement](#improvement) below).

## Core Principles

### 1. Minimal Root AGENTS.md

The root AGENTS.md should be as small as possible. Every token gets loaded on every request, so keep only what's relevant to **every single task**.

**Essential elements only:**
- One-sentence project description (acts as a role-based prompt)
- Package manager (if not npm; or use corepack for warnings)
- Non-standard build/typecheck commands
- Links to progressive disclosure files

### 2. Progressive Disclosure

Instead of cramming everything into AGENTS.md, give the agent only what it needs right now, and point to other resources when needed.

**Example - Don't do this:**
```markdown
## Code style

- Always use const instead of let
- Use interface instead of type when possible
- Prefer functional patterns
- No semicolons
- Single quotes only
- ... (50 more lines)
```

**Do this instead:**
```markdown
For TypeScript conventions, see docs/TYPESCRIPT.md
```

**Benefits:**
- TypeScript rules only load when the agent writes TypeScript
- Other tasks don't waste tokens
- File stays focused and portable across model changes

### 3. Describe Capabilities, Not File Structure

File paths change constantly. Documenting structure leads to stale information that actively poisons context.

**Don't:**
```markdown
Authentication logic lives in src/auth/handlers.ts
```

**Do:**
```markdown
Authentication uses JWT tokens with refresh token rotation.
Look for modules matching **/auth/**/*.ts for implementation.
```

### 4. Nested AGENTS.md for Monorepos

Place AGENTS.md files in subdirectories - they merge with the root level.

| Level | Content |
|-------|---------|
| **Root** | Monorepo purpose, navigation, shared tools |
| **Package** | Package purpose, tech stack, specific conventions |

**Root AGENTS.md:**
```markdown
This is a monorepo containing web services and CLI tools.

Use pnpm workspaces to manage dependencies.

See each package's AGENTS.md for specific guidelines.
```

**Package AGENTS.md (packages/api/AGENTS.md):**
```markdown
This package is a Node.js GraphQL API using Prisma.

Follow docs/API_CONVENTIONS.md for API design patterns.
```

## Content Recommendations

When creating or improving AGENTS.md content, recommend project-specific guidance that promotes code quality. Keep these in the root file only if they apply to every task; otherwise link to focused progressive disclosure files such as `docs/QUALITY.md`, `docs/TYPESCRIPT.md`, `docs/TESTING.md`, `docs/ARCHITECTURE.md`, or `docs/FRONTEND.md`.

### Code Quality

- Stay DRY: reuse existing utilities, components, and patterns instead of duplicating logic.
- Do not reinvent the wheel: prefer established project dependencies and existing modules when they fit.
- Prefer modular architecture with small, cohesive units and clear boundaries.
- Do not create god components, god functions, or oversized files; split responsibilities when code becomes hard to reason about.
- Prioritize quality over speed; a task is not complete if it leaves avoidable design, type, or test debt.

### Type Safety

- In typed languages, maintain full type safety.
- Do not use `any`, `as any`, or `: any`; use precise types, generics, discriminated unions, or schema-derived types instead.
- Framework-generated files are exempt when the framework owns the generated typing.

### Validation & Testing

- Typecheck, build, and relevant tests must pass when work is done; if they do not pass, the work is not done.
- If verification cannot be run, document why and what remains unverified.
- Encourage comprehensive testing for meaningful behavior, including edge cases and regressions.
- Do not run the dev server when the user already runs it; use build, typecheck, tests, and static checks instead.

### Frontend Architecture

- Build frontend UI from small, reusable components with clear responsibilities, then compose them into larger sections and pages.
- Prefer reusable, focused components over large one-off components.
- Include global error boundaries for frontend applications so unexpected UI failures degrade safely.

## Templates

### Minimal Single-Package AGENTS.md

```markdown
# AGENTS.md

[One-sentence description of what this project is]

## Package Manager

This project uses [pnpm/yarn/bun]. [Optional: brief note if workspaces/monorepo]

## Build & Test

- Build: `command here`
- Test: `command here`
- Typecheck: `command here` (if non-standard)

## Progressive Disclosure

- [Domain-specific]: [path/to/file.md]
```

### Minimal Monorepo Root AGENTS.md

```markdown
# AGENTS.md

This is a monorepo containing [brief description of packages].

## Package Manager

Use [pnpm workspaces/yarn workspaces] to manage dependencies.

## Navigation

- Use `pnpm --filter <package_name>` to run commands in specific packages
- Each package has its own AGENTS.md with specific guidelines

## Packages

- [`package-name`](packages/package-name): [brief purpose]
- [`package-name`](packages/package-name): [brief purpose]
```

### Package-Level AGENTS.md (Monorepo)

```markdown
# AGENTS.md

[One-sentence description of this package]

## Tech Stack

- [Framework]
- [Language]
- [Key libraries]

## Commands

- Build: `command here`
- Test: `command here`
- Dev: `command here`

## Progressive Disclosure

- [Domain]: [path/to/file.md]
```

## Verification

When verifying an existing AGENTS.md, check for these issues:

### Bloat Indicators

- [ ] File is longer than 50-75 lines
- [ ] Contains detailed coding style rules that belong in separate files
- [ ] Documents file paths extensively
- [ ] Has extensive examples that should be in documentation
- [ ] Contains git workflow instructions that belong in CONTRIBUTING.md

### Contradiction Detection

Look for conflicting instructions:
- [ ] "Use functional patterns" vs "Use classes for X"
- [ ] "Prefer composition" vs "Use inheritance for Y"
- [ ] "Always use X" vs "In cases of Y, use Z"

### Stale Information Risks

- [ ] Specific file paths (especially src/ directories)
- [ ] Lists of files or modules
- [ ] Version-specific toolchain commands
- [ ] Outdated architecture descriptions

### Best Practices Compliance

- [ ] Has one-sentence project description
- [ ] Specifies package manager (if not npm)
- [ ] Links to progressive disclosure files
- [ ] Includes or links to code-quality guidance covering architecture, type safety, testing, and frontend expectations when applicable
- [ ] Uses conversational tone (not "ALWAYS", "MUST", "NEVER")
- [ ] Describes capabilities, not structure

## Improvement

### Refactoring Bloated AGENTS.md

Use this process to refactor a bloated AGENTS.md:

1. **Find contradictions**: Identify conflicting instructions and ask which to keep
2. **Extract essentials**: Keep only what belongs in root AGENTS.md
3. **Group the rest**: Organize remaining instructions into logical categories
4. **Create file structure**: Set up progressive disclosure hierarchy
5. **Flag for deletion**: Remove redundant, vague, or obvious instructions

**Prompt template to use:**
```text
I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

1. **Find contradictions**: Identify any instructions that conflict with each other.
   For each contradiction, ask me which version I want to keep.

2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **Group the rest**: Organize remaining instructions into logical categories
   (e.g., TypeScript conventions, testing patterns, API design, Git workflow).

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")
```

### Creating Progressive Disclosure Files

**Suggested structure:**
```
docs/
├── QUALITY.md          # Cross-cutting code quality expectations
├── TYPESCRIPT.md       # TypeScript patterns and conventions
├── TESTING.md          # Testing strategies and frameworks
├── FRONTEND.md         # Component architecture, reuse, error boundaries
├── API_CONVENTIONS.md  # API design patterns (if applicable)
├── ARCHITECTURE.md     # High-level architecture (capabilities, not file paths)
└── Git workflow items → CONTRIBUTING.md
```

**Each file should:**
- Be focused on one domain
- Link to related files for navigation
- Describe principles, not prescriptions
- Include examples where helpful

## Common Issues & Solutions

| Issue | Solution |
|-------|----------|
| Agent uses wrong package manager | Explicitly specify: "This project uses pnpm" |
| Agent generates wrong commands | List non-standard build/test commands |
| File gets too large | Apply progressive disclosure - move domain rules to separate files |
| Instructions conflict | Review for contradictions and resolve |
| Agent looks in wrong places | Describe capabilities, not file paths |
| Mixed conventions over time | Treat AGENTS.md as living documentation, review periodically |

## AGENTS.md vs CLAUDE.md

**Claude Code** uses `CLAUDE.md` instead of `AGENTS.md`. To maintain compatibility:

```bash
# Create a symlink from AGENTS.md to CLAUDE.md
ln -s AGENTS.md CLAUDE.md
```

Both files serve the same purpose - customize how AI coding agents behave in your repository.

## Tools Supporting AGENTS.md

AGENTS.md is an open standard supported by many tools:
- OpenAI Codex, Jules (Google), Factory, Aider, goose, opencode
- VS Code, Devin (Cognition), Cursor, RooCode, Gemini CLI
- GitHub Copilot coding agent, Windsurf (Cognition), and more

See https://agents.md/ for the full list.

## Your Approach

1. **Start minimal**: Begin with essential information only
2. **Apply progressive disclosure**: Move domain-specific rules to separate files
3. **Avoid file paths**: Describe capabilities, not structure
4. **Keep it conversational**: Use natural language, not rigid commands
5. **Review periodically**: Treat as living documentation
6. **Use nested files**: For monorepos, place AGENTS.md in subdirectories
7. **Link, don't duplicate**: Point to other resources instead of repeating

## Progressive Disclosure

**Deep dive on specific topics:**
- **Verification checklist**: [VERIFICATION.md](references/VERIFICATION.md)
- **Refactoring guide**: [REFACTORING.md](references/REFACTORING.md)
- **Template gallery**: [TEMPLATES.md](references/TEMPLATES.md)
- **Monorepo patterns**: [MONOREPO.md](references/MONOREPO.md)
- **Common anti-patterns**: [ANTI_PATTERNS.md](references/ANTI_PATTERNS.md)