agents-md

Maintaining AGENTS.md

AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.

When to Use

• The user asks to create, update, or audit AGENTS.md or CLAUDE.md.

• The project needs concise, high-signal agent instructions derived from the actual toolchain and repo layout.

• Existing agent documentation is too long, duplicated, or drifting away from real project conventions.

File Setup

1. Create AGENTS.md at project root
2. Create symlink: ln -s AGENTS.md CLAUDE.md

Before Writing

Analyze the project to understand what belongs in the file:

1. Package manager — Check for lock files (pnpm-lock.yaml, yarn.lock, package-lock.json, uv.lock, poetry.lock)
2. Linter/formatter configs — Look for .eslintrc, biome.json, ruff.toml, .prettierrc, etc. (don't duplicate these in AGENTS.md)
3. CI/build commands — Check Makefile, package.json scripts, CI configs for canonical commands
4. Monorepo indicators — Check for pnpm-workspace.yaml, nx.json, Cargo workspace, or subdirectory package.json files
5. Existing conventions — Check for existing CONTRIBUTING.md, docs/, or README patterns

Writing Rules

• Headers + bullets — No paragraphs

• Code blocks — For commands and templates

• Reference, don't embed — Point to existing docs: "See CONTRIBUTING.md for setup" or "Follow patterns in src/api/routes/"

• No filler — No intros, conclusions, or pleasantries

• Trust capabilities — Omit obvious context

• Prefer file-scoped commands — Per-file test/lint/typecheck commands over project-wide builds

• Don't duplicate linters — Code style lives in linter configs, not AGENTS.md

Required Sections

Package Manager

## Package Manager
Use pnpm: pnpm install, pnpm dev, pnpm test

File-Scoped Commands

## File-Scoped Commands
| Task | Command |
|------|---------|
| Typecheck | pnpm tsc --noEmit path/to/file.ts |
| Lint | pnpm eslint path/to/file.ts |
| Test | pnpm jest path/to/file.test.ts |

Commit Attribution

## Commit Attribution
AI commits MUST include:

Example: Co-Authored-By: Claude Sonnet 4 <[email protected]>

Key Conventions

Optional Sections

Add only if truly needed:

• API route patterns (show template, not explanation)

• CLI commands (table format)

• File naming conventions

• Project structure hints (point to critical files, flag legacy code to avoid)

• Monorepo overrides (subdirectory AGENTS.md files override root)

Anti-Patterns

Omit these:

• "Welcome to..." or "This document explains..."

• "You should..." or "Remember to..."

• Linter/formatter rules already in config files (.eslintrc, biome.json, ruff.toml)

• Listing installed skills or plugins (agents discover these automatically)

• Full project-wide build commands when file-scoped alternatives exist

• Obvious instructions ("run tests", "write clean code")

• Explanations of why (just say what)

• Long prose paragraphs

Example Structure

# Agent Instructions
Package Manager
Use pnpm: pnpm install, pnpm dev
Commit Attribution
AI commits MUST include:

## File-Scoped Commands
| Task | Command |
|------|---------|
| Typecheck | pnpm tsc --noEmit path/to/file.ts |
| Lint | pnpm eslint path/to/file.ts |
| Test | pnpm jest path/to/file.test.ts |
API Routes
[Template code block]
CLI
| Command | Description |
|---------|-------------|
| pnpm cli sync | Sync data |

Limitations

• Use this skill only when the task clearly matches the scope described above.

• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.