An oversized AGENTS.md is one that makes the agent read things it doesn't need: file trees it could list itself, long examples, and rules that only apply to one folder. The fix is a pruning pass. Cut anything the agent can read from the repo, move area-specific rules into nested AGENTS.md files next to that code, move step-by-step how-to into skills or linked docs, and keep the root file as a short contract: how to build, how to verify, and what not to touch. There is no documented length limit for AGENTS.md. The "under 500 lines" number you may have seen is Cursor's guidance for rules, not a cap on AGENTS.md.
Who this is for
Your AGENTS.md started as a page and is now a wall. The agent still ignores half of it, and every new rule makes the file harder to keep accurate.
Where the 500-line number comes from
Cursor's rules documentation lists best practices for rules, including "Keep rules under 500 lines" and splitting large rules into multiple, composable rules. The same page says Cursor supports AGENTS.md in the project root and in subdirectories. It does not set a line or token limit for AGENTS.md. Use the 500-line advice as a sensible reference point for focus, not as a rule the tool enforces.
Decide where each section goes
| What's in the file | Keep at root? | Better home |
|---|---|---|
| Build, test, and verify commands | Yes | — |
| Hard constraints (don't edit generated code, no new deps without asking) | Yes | — |
| Decisions the agent can't infer from code | Yes | — |
| File trees, dependency lists, code it can open | No | Delete; the agent reads the repo |
| Rules for one package or folder | No | A nested AGENTS.md in that folder |
| Step-by-step how-to for a recurring task | No | A skill, or a doc the file links to |
| Long code examples | No | An example file in the repo, linked by path |
| Background and history | No | A README or design doc, linked |
A trimmed root file
# AGENTS.mdBuild and verify - Install: `pnpm install` - Before finishing: `pnpm lint && pnpm test`
Boundaries - Don't edit files under `generated/`. - Ask before adding a dependency. - Secrets come from env vars like `API_KEY=your-key-here`; never commit real values.
Where to look - Package-specific rules: `packages/*/AGENTS.md` - Release steps: `docs/release.md` ```
Everything else either lives next to the code it governs or sits one link away.
Pitfalls
- Treating 500 lines as a hard limit. It's guidance for rules. A 300-line file full of things the agent can infer is still too long.
- Copying root rules into every nested file. Duplicates drift apart. Keep shared rules at the root and put only folder-specific rules in the nested file.
- Moving a rule out and losing it. If you move a section into a doc, link to it from AGENTS.md so the agent can still find it.
- Pasting whole examples. Point to a real file in the repo instead. It stays current when the code changes.
How to check it
- For every section, ask: could the agent work this out by reading the repo? If yes, cut it.
- Give the agent a routine task in each area you touched. Confirm it still runs the right verify commands.
- Confirm it still respects the same boundaries, such as leaving generated files alone.
- Open each nested AGENTS.md and check it doesn't repeat the root.
For what belongs in the file in the first place, see the AGENTS.md guide for Cursor, Claude Code, and Codex. For nested files, see the nested AGENTS.md monorepo playbook and what belongs in AGENTS.md vs README.
Where ShipKits fits
The Operator Pack ($47) is markdown seats + skills + install.sh — not a hosted app, not a chatbot. Seven named seats, three skills, an ops playbook and a token-cost playbook. Done means a file, PR, or URL. Its AGENTS.md templates start short and split by area, so you begin with the layout this post trims toward. Soft path: start at /free. Cheat Sheet for the skim checklist mindset.
Soft next step
Do one pruning pass this week: cut what the agent can infer and move one folder's rules into a nested file. Soft ladder: /free, then the Operator Pack ($47). Related: AGENTS.md guide, nested AGENTS.md, AGENTS.md vs README.