Rightsize AGENTS.md
Before rewriting, read the writing-for-agents skill. If it is missing locally, fetch https://raw.githubusercontent.com/mattpocock/skills/main/skills/productivity/writing-for-agents/SKILL.md.
Cite for the always-on ignore problem: https://www.humanlayer.dev/blog/writing-a-good-claude-md
Steps
Locate. Open the file the user named. Default: repo-root AGENTS.md, then CLAUDE.md. Treat both as one always-on budget. Open a nested file only when the user named it. Edit .cursor/rules only when the user named them. Rewrite the existing file. Do not regenerate it from /init or a harness template.
Done when the target path is known and the current text is in context.
Scan the environment. README, package manifests, scripts, linters, existing skills, docs indexes. The environment is source of truth.
Done when every block is marked confessed (the repo already states it) or unconfessed (only this file would).
Classify. Label every block keep, pointer, or delete using the taxonomy below. Always-on text must apply to every session. Non-universal lines train the harness to discount the whole file. Create a skill or disclosed doc only when the user asks.
Done when every heading and every bullet has one label.
Rewrite. Replace the file in place. Phrase the target behavior. One meaning, one place. Leading words over restated triads. If AGENTS.md and CLAUDE.md both exist, put shared lines in AGENTS.md and keep CLAUDE.md as @AGENTS.md plus Claude-only notes. If the file is missing, write a thin router: identity plus pointers. If you write a pointer target, point at path or file:line. Do not paste snippets that will rot.
Done when every remaining line is identity, gotcha, guardrail, or a pointer.
Report. What stayed, what became a pointer, what died, line count before and after. Aim under 80 lines. If after is over 300, say so. Name skill candidates. Stop after the report.
Done when every keep, pointer, and delete is named, with before/after line counts.
Taxonomy
Keep (always-on):
- Identity: 1 to 3 sentences for where this repo is. If multiple apps or packages, a one-screen name+path list. Not a tour.
- Gotcha: a landmine or non-standard convention the repo does not confess, including a wrong-default runtime
- Guardrail: a hard safety constraint that judgement cannot replace
- Router pointer: a named doc or skill plus the branch that should open it
- A line that this file stays brief
Pointer (move out of always-on):
- A workflow used on some tasks, not all (verify, review, deploy, auth)
- A long convention that already lives in a doc, or should
- Claude-only notes: live under the
@AGENTS.md import, not copied
Delete:
- Preamble
- Directory overviews and architecture tours (a name+path list is Identity)
- Discoverable env: runtime, package manager, scripts the manifest already names. A wrong-default runtime is a Gotcha.
- Style the linter already enforces
- Overconstrained rules and constraining examples
- README restates,
/init filler, no-ops, repeats
- Sediment: a rule added after one failure that no longer trips the agent
Pointer wording
Front-load the leading word. One trigger per branch. Cut identity the target already carries. Do not add a dump index of docs.
## Testing
Testing or coverage: read `docs/testing.md`.
Target shape
# <repo>
<1 to 3 sentence identity>
- `apps/web` - <one clause>
- `packages/ui` - <one clause>
Keep this file brief. Put task-specific guidance behind a pointer.
## Gotchas
- <landmine or non-standard convention the repo does not confess>
## Guardrails
- <hard safety constraint judgement cannot replace>
## <Branch>
<pointer>
Omit empty Gotchas or Guardrails headings. Omit the name+path list when the repo is one package.
1---2name: ft-rightsize-agents-md3description: Cut always-on AGENTS.md and CLAUDE.md down to identity, gotchas, guardrails, and router pointers. Use when agent instruction files have grown too large or when you want to trim always-on guidance.4---56# Rightsize AGENTS.md78Before rewriting, read the `writing-for-agents` skill. If it is missing locally, fetch https://raw.githubusercontent.com/mattpocock/skills/main/skills/productivity/writing-for-agents/SKILL.md.910Cite for the always-on ignore problem: https://www.humanlayer.dev/blog/writing-a-good-claude-md1112## Steps13141. **Locate.** Open the file the user named. Default: repo-root `AGENTS.md`, then `CLAUDE.md`. Treat both as one always-on budget. Open a nested file only when the user named it. Edit `.cursor/rules` only when the user named them. Rewrite the existing file. Do not regenerate it from `/init` or a harness template.15 Done when the target path is known and the current text is in context.16172. **Scan the environment.** README, package manifests, scripts, linters, existing skills, docs indexes. The environment is source of truth.18 Done when every block is marked confessed (the repo already states it) or unconfessed (only this file would).19203. **Classify.** Label every block keep, pointer, or delete using the taxonomy below. Always-on text must apply to every session. Non-universal lines train the harness to discount the whole file. Create a skill or disclosed doc only when the user asks.21 Done when every heading and every bullet has one label.22234. **Rewrite.** Replace the file in place. Phrase the target behavior. One meaning, one place. Leading words over restated triads. If `AGENTS.md` and `CLAUDE.md` both exist, put shared lines in `AGENTS.md` and keep `CLAUDE.md` as `@AGENTS.md` plus Claude-only notes. If the file is missing, write a thin router: identity plus pointers. If you write a pointer target, point at `path` or `file:line`. Do not paste snippets that will rot.24 Done when every remaining line is identity, gotcha, guardrail, or a pointer.25265. **Report.** What stayed, what became a pointer, what died, line count before and after. Aim under 80 lines. If after is over 300, say so. Name skill candidates. Stop after the report.27 Done when every keep, pointer, and delete is named, with before/after line counts.2829## Taxonomy3031**Keep** (always-on):3233- Identity: 1 to 3 sentences for where this repo is. If multiple apps or packages, a one-screen name+path list. Not a tour.34- Gotcha: a landmine or non-standard convention the repo does not confess, including a wrong-default runtime35- Guardrail: a hard safety constraint that judgement cannot replace36- Router pointer: a named doc or skill plus the branch that should open it37- A line that this file stays brief3839**Pointer** (move out of always-on):4041- A workflow used on some tasks, not all (verify, review, deploy, auth)42- A long convention that already lives in a doc, or should43- Claude-only notes: live under the `@AGENTS.md` import, not copied4445**Delete**:4647- Preamble48- Directory overviews and architecture tours (a name+path list is Identity)49- Discoverable env: runtime, package manager, scripts the manifest already names. A wrong-default runtime is a Gotcha.50- Style the linter already enforces51- Overconstrained rules and constraining examples52- README restates, `/init` filler, no-ops, repeats53- Sediment: a rule added after one failure that no longer trips the agent5455## Pointer wording5657Front-load the leading word. One trigger per branch. Cut identity the target already carries. Do not add a dump index of docs.5859```60## Testing61Testing or coverage: read `docs/testing.md`.62```6364## Target shape6566```67# <repo>6869<1 to 3 sentence identity>70- `apps/web` - <one clause>71- `packages/ui` - <one clause>7273Keep this file brief. Put task-specific guidance behind a pointer.7475## Gotchas76- <landmine or non-standard convention the repo does not confess>7778## Guardrails79- <hard safety constraint judgement cannot replace>8081## <Branch>82<pointer>83```8485Omit empty Gotchas or Guardrails headings. Omit the name+path list when the repo is one package.
cameronapak