Audit and rewrite AGENTS.md, CLAUDE.md, and other AI agent context files to be minimal and effective. This skill should be used when creating, reviewing, or rewriting context files (AGENTS.md, CLAUDE.md, .cursorrules, etc.) to follow research-backed guidelines that improve agent performance and reduce costs. Based on findings from arxiv.org/abs/2602.11988.
From scott-ccnpx claudepluginhub citadelgrad/scott-cc --plugin beads-epic-builderThis skill uses the workspace's default tool permissions.
references/research-findings.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Audit and rewrite AI agent context files following research-backed principles. Verbose context files hurt agent performance (-2 to -3%) and increase costs (+20%). Minimal, tooling-focused files improve performance (+4%) with lower overhead.
Locate every file that injects context into agent sessions:
# Common context file locations
fd -t f "AGENTS.md|CLAUDE.md|\.cursorrules|\.windsurfrules|copilot-instructions" .
Read each file. Note total word count and section count. Flag any file over 700 words.
Cross-reference content across all context files found. Mark sections that appear in more than one file or that duplicate information already present in README, pyproject.toml, package.json, Dockerfile, or other standard project files.
Common duplication sources:
For every section in every context file, classify it:
| Classification | Action | Examples |
|---|---|---|
| Tooling spec | KEEP | Required CLI tools, package managers, linter commands |
| Build/test command | KEEP | Exact test commands with paths, build commands |
| Non-obvious gotcha | KEEP | "Worker caches env vars", "pitchers stored as P not SP/RP" |
| Operational rule | KEEP (condense) | "Stop after 2-3 failures", "never use pip" |
| Architecture overview | CUT | System diagrams, component descriptions |
| Directory listing | CUT | File tree enumerations, module inventories |
| Duplicated docs | CUT | Content from README, config files, or other context files |
| Tutorial/reference | MOVE to docs/ | MCP tool guides, pipeline authoring references |
| Code examples of patterns | CUT | Agents discover patterns from actual code |
| Tool installation instructions | CUT | One-time setup, not per-session |
Apply these rules when rewriting:
Structure rules:
Content rules — what TO include:
Content rules — what NOT to include:
Multi-file projects: Assign clear responsibilities to each file:
After rewriting, verify:
Read references/research-findings.md for the full experimental data supporting these guidelines, including specific performance numbers and the verbatim conclusion from the paper.