1---
2name: initialising-and-updating-agents-md
3description: Analyses a codebase and creates or updates AGENTS.md to help future agents work effectively. Use when asked to initialise, generate, or update an AGENTS.md file, or when the user says "init agents", "generate agents.md", or wants to document a project for agent use.
4license: GPL-3.0-or-later
5metadata:
6 author: Amolith <amolith@secluded.site>
7---
8
9Analyse the codebase and produce an `AGENTS.md` that documents what an agent _cannot discover on its own_ by reading the code.
10
11Research from ETH Zurich shows that auto-generated AGENTS.md files _reduce_ task success by ~3% and inflate costs by 20%+ because they duplicate what agents already find by reading the repo. Human-written files help only when they contain non-discoverable information. The key filter for every line: **can an agent figure this out by reading the code? If yes, don't write it.**
12
13## Precondition
14
15Check whether the directory is empty or contains only config files (e.g. `.gitignore`, `.editorconfig`, lock files). If so, stop and tell the user:
16
17> Directory appears empty or only contains config. Add source code first, then run this command to generate AGENTS.md.
18
19## Discovery
20
211. **Directory contents**: Run `ls` to get the lay of the land
222. **Existing rule files**: Check for and read any that exist:
23 - `.cursor/rules/*.md`, `.cursorrules`
24 - `.github/copilot-instructions.md`
25 - `claude.md`, `CLAUDE.md`
26 - `agents.md`, `AGENTS.md`
273. **Project type**: Identify from config files and directory structure (e.g. `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`)
284. **Commands**: Find build/test/lint/run commands from config files, scripts, Makefiles, CI configs — especially single-file and single-test variants
295. **Source patterns**: Read representative source files to identify non-obvious conventions
306. **Existing AGENTS.md**: If one exists, read it — you're improving, not starting from scratch
31
32## What belongs in AGENTS.md
33
34Agents can grep the entire codebase before you finish typing your prompt. They don't need a map — they need to know where the landmines are.
35
36**Include (non-discoverable):**
37
38- Commands that differ from convention — `uv` instead of `pip`, `bun` instead of `npm`, custom test runners, single-file lint/typecheck variants
39- Gotchas that break silently — "run tests with `--no-cache` or fixtures give false positives"
40- Non-obvious constraints — "the `legacy/` directory is deprecated but three production modules import from it; don't delete anything in it"
41- Tooling the agent should prefer — custom scripts, linters, formatters that aren't obvious from config
42- Project-specific guidance from existing rule files discovered during step 2
43
44**Omit (discoverable):**
45
46- Codebase overviews and directory listings — the agent reads these itself
47- Tech stack and framework descriptions — visible in config files
48- Code style details — agents are in-context learners; they'll match existing patterns. Use linters and formatters instead.
49- Architecture explanations — agents infer this from the code
50- Anything the agent would find by reading the README, config files, or source
51
52## Progressive disclosure
53
54For monorepos or large projects, don't stuff everything into one root file. Place focused `AGENTS.md` files at the relevant directory level:
55
56```
57AGENTS.md # repo-wide: tooling, gotchas, commands
58services/api/AGENTS.md # API-specific: custom middleware pattern, DB migration gotchas
59packages/ui/AGENTS.md # UI-specific: design token locations, component patterns
60```
61
62Agents read the nearest file in the directory tree, so the closest one takes precedence.
63
64## Output principles
65
66- **Short.** Every line goes into every agent session. Aim for under 60 lines; under 30 is better. Each line must justify its token cost.
67- **Landmines, not maps.** Document what will trip the agent up, not what it can see for itself.
68- **Commands first.** Put executable commands early — agents reference them often. Prefer single-file variants (`npm run tsc --noEmit path/to/file.tsx`) over project-wide builds.
69- **Living document.** Treat it like a bug tracker, not a wiki. When the agent trips on something non-obvious, add a line. When you fix the root cause, delete the line.
70- **Only document what you observe.** Never invent commands, patterns, or conventions.
71- **Preserve existing content** when updating. Merge new findings; don't discard prior work without reason.