On Jan 18, 2026, Matt Pocock posted this on X:
Bad AGENTS.md files can make your coding agent worse and cost you tokens. Here's a prompt you can use to clean them up:
I want you to refactor my AGENTS.md file to follow progressive disclosure principles.
Follow these steps:
1. **Find contradictions**: Identify any instructions that conflict with each other. For each contradiction, ask me which version I want to keep.
2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
- One-sentence project description
- Package manager (if not npm)
- Non-standard build/typecheck commands
- Anything truly relevant to every single task
3. **Group the rest**: Organize remaining instructions into logical categories (e.g., TypeScript conventions, testing patterns, API design, Git workflow). For each group, create a separate markdown file.
4. **Create the file structure**: Output:
- A minimal root AGENTS.md with markdown links to the separate files
- Each separate file with its relevant instructions
- A suggested docs/ folder structure
5. **Flag for deletion**: Identify any instructions that are:
- Redundant (the agent already knows this)
- Too vague to be actionable
- Overly obvious (like "write clean code")
Same prompt can be applied to CLAUDE.md and other AI guidelines files.
Here's the link to the original tweet.
Matt's full tutorial: A Complete Guide To AGENTS.md
