Maintaining AGENTS.md

AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding.

File Setup Create AGENTS.md at project root Create symlink: ln -s AGENTS.md CLAUDE.md Before Writing

Discover local skills to reference:

find .claude/skills -name "SKILL.md" 2>/dev/null ls plugins//skills//SKILL.md 2>/dev/null

Read each skill's frontmatter to understand when to reference it.

Writing Rules Headers + bullets - No paragraphs Code blocks - For commands and templates Reference, don't duplicate - Point to skills: "Use db-migrate skill. See .claude/skills/db-migrate/SKILL.md" No filler - No intros, conclusions, or pleasantries Trust capabilities - Omit obvious context Required Sections Package Manager

Which tool and key commands only:

Package Manager

Use pnpm: pnpm install, pnpm dev, pnpm test

Commit Attribution

Always include this section. Agents should use their own identity:

Commit Attribution

AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

Example: Co-Authored-By: Claude Sonnet 4 <noreply@example.com>

Key Conventions

Project-specific patterns agents must follow. Keep brief.

Local Skills

Reference each discovered skill:

Database

Use db-migrate skill for schema changes. See .claude/skills/db-migrate/SKILL.md

Testing

Use write-tests skill. See .claude/skills/write-tests/SKILL.md

Optional Sections

Add only if truly needed:

API route patterns (show template, not explanation) CLI commands (table format) File naming conventions Anti-Patterns

Omit these:

"Welcome to..." or "This document explains..." "You should..." or "Remember to..." Content duplicated from skills (reference instead) 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:

Co-Authored-By: (the agent model's name and attribution byline)

API Routes

[Template code block]

Database

Use db-migrate skill. See .claude/skills/db-migrate/SKILL.md

Testing

Use write-tests skill. See .claude/skills/write-tests/SKILL.md

CLI