From scott-cc
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/scott-cc:context-file-optimizerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
Three layers inform what belongs in a context file:
Understanding how Claude Code loads context determines where content belongs:
| Location | When it loads | Token cost |
|---|---|---|
| Root CLAUDE.md (or @path imports from it) | Every session start, every request | Always paid |
| Subdirectory CLAUDE.md | On-demand, when Claude reads a file in that directory | JIT — only when needed |
| Skill description (one-liner) | Every session start | ~450 tokens, always |
| Skill body | Only when the skill is invoked | JIT — only when needed |
Key implications:
@path imports in CLAUDE.md are organizational only — imported files expand eagerly at launch and cost the same as inline content. They do not defer loading."see docs/foo.md" do not trigger auto-fetch — they are dead text unless Claude actively decides to read the file.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" |
| Code quality standards | KEEP | DRY, KISS, thin handlers, no silent failures, ~20-line functions — project coding rules belong in CLAUDE.md |
| 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 a Skill | MCP tool guides, pipeline authoring references — Skills load JIT; docs/ files don't auto-fetch |
| Code examples of patterns | CUT | Agents discover patterns from actual code |
| Tool installation instructions | CUT | One-time setup, not per-session |
| Behavioral guidelines | CUT (with caution) | Karpathy-style rules — only cut if the project team consistently invokes /karpathy-guidelines; keep them if behavioral consistency matters more than token savings |
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.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub citadelgrad/scott-cc --plugin scott-cc