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 Which tool and key commands only: ```markdown ## Package Manager Use **pnpm**: `pnpm install`, `pnpm dev`, `pnpm test` ``` ### File-Scoped Commands Per-file commands are faster and cheaper than full project builds. Always include when available: ```markdown ## 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 Always include this section. Agents should use their own identity: ```markdown ## 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. ## 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 ```markdown # 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) ``` ## 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.