optimize-agent-instructions

name	optimize-agent-instructions
description	Optimize project agent instruction files. Use for optimize/improve/clean up/review Claude.md or making persistent CLAUDE.md or AGENTS.md guidance more concise, concrete, and reliable; not for ordinary docs or code reviews.
argument-hint	[--accept] [path-to-CLAUDE.md or AGENTS.md]
argument-choices	--accept

Optimize agent instructions

Analyze and rewrite the project's agent instruction files to maximize agent instruction-following while minimizing context waste. Treat flags such as --accept as flags, not paths. If a non-flag path is given in $ARGUMENTS, use that file; otherwise, look for CLAUDE.md or AGENTS.md in the current project root (or .claude/CLAUDE.md or AGENTS.md).

Use this skill for persistent agent instructions: CLAUDE.md or AGENTS.md, .claude/CLAUDE.md or AGENTS.md, CLAUDE.local.md, and .claude/rules/**/*.md. If --accept is present in $ARGUMENTS, apply all high-confidence changes without asking for confirmation. Otherwise, present the analysis and proposed rewrite, then wait for approval.

Use the canonical placement policy in agents/instruction-placement.org from the dotfiles repo root when deciding whether guidance belongs in an instruction file, skill, hook, linter, reference doc, or project brief.

Background: why this matters

Claude Code or Codex loads CLAUDE.md or AGENTS.md files, imports, local memories, and rules as context rather than enforced configuration. They are high-leverage because they shape every relevant session, but the instruction budget is finite: frontier thinking models reliably follow ~150-200 instructions total, and Claude Code or Codex's system prompt already consumes ~50 of those. Every line in persistent instructions competes for the remainder.

Long, vague, stale, or non-universal instructions consume context and reduce adherence. The goal is not to make instructions clever; it is to keep them scoped, concrete, current, and easy for the agent to verify.

Phase 1: Read and measure

1. Read the target CLAUDE.md or AGENTS.md in full
2. Resolve and read all @-imported files, noting import depth and size
3. Read the Claude Code or Codex instruction sources that affect the target: .claude/CLAUDE.md or AGENTS.md if separate, CLAUDE.local.md if present, and .claude/rules/**/*.md if present
4. Treat local or personal instruction files as private context: use them to detect conflicts, but do not quote sensitive content or copy local-only rules into shared files unless the user explicitly targets those files
5. Count:
   • Total lines (target: under 200; absolute max: 300)
   • Discrete instructions/rules (target: under 100, accounting for system prompt's ~50)
   • @-imports, rules files, and their sizes

Phase 2: Evaluate every instruction

For each discrete instruction or rule, evaluate against these criteria. Use subagents in parallel when the active agent environment supports them; otherwise divide the sections explicitly in your own notes.

Criterion 1: Universal applicability

"Would this instruction be useful in every single session, regardless of what task the user is working on?"

Instructions that only matter for specific tasks (e.g., database schema conventions, deployment procedures, API endpoint patterns) should be moved to .claude/rules/ files with paths frontmatter, skills, or referenced docs — not in the root instruction file or AGENTS.md. The root file must contain only universally applicable guidance.

Criterion 2: Specificity and verifiability

"Is this concrete enough that compliance is unambiguous?"

Good: "Use 2-space indentation", "Run npm test before committing", "API handlers live in src/api/handlers/" Bad: "Format code properly", "Test your changes", "Keep files organized", "Write clean code", "Be more natural"

Vague instructions waste budget and may be interpreted differently every time. Either make them concrete or cut them.

Criterion 3: Pointer vs. copy

"Does this embed information that exists authoritatively elsewhere?"

Prefer @path/to/file imports or file:line references to authoritative source code over pasting snippets that become stale. CLAUDE.md or AGENTS.md should point to the truth, not duplicate it.

Criterion 4: Linter's job

"Is this a code style rule that a linter or formatter could enforce deterministically?"

Never send an LLM to do a linter's job. LLMs are comparably expensive and incredibly slow compared to traditional tools for style enforcement. Style rules in CLAUDE.md or AGENTS.md bloat context and degrade instruction-following across the board. Move these to linter configs, pre-commit hooks, or Claude Code or Codex stop hooks.

Criterion 5: Default behavior

"Would the active agent do this anyway without being told?"

the active agent system prompt and training already establish many behaviors. Instructions that restate defaults consume tokens without changing anything. If removing the instruction wouldn't change behavior, it's dead weight.

Examples of likely defaults: don't mix unrelated changes in a commit, use descriptive variable names, don't introduce security vulnerabilities.

Criterion 6: Conflicts

"Does this contradict another instruction in CLAUDE.md or AGENTS.md, rules files, or the system prompt?"

Contradictions cause arbitrary behavior — the active agent picks one at random. Review for direct contradictions, semantic tension, and instructions that give different guidance for the same situation.

Criterion 7: Operational vs. reference

"Is this operational (trigger → action) or reference (a fact to look up)?"

Operational content — procedures the agent must execute correctly (commands, workflows, behavioral rules shaped like "when the user says X, do Y") — belongs in a skill, not an @-import or linked doc. Skills load their description into the system reminder, match against the user's request via keyword triggers, and carry a "BLOCKING REQUIREMENT" to invoke when they match. @-imports and linked docs expand inline but can be skimmed past, especially when the user's phrasing doesn't explicitly cue the reference.

Reference content — facts, lookups, infrequent data the agent retrieves on demand (calendar links, token rotation commands, architectural background) — belongs in an @-import or linked doc. No procedure to trigger; the agent reads when it needs the info.

Diagnostic: if removing the content from CLAUDE.md or AGENTS.md and not putting it in a skill would cause the agent to silently skip an expected action, it's operational → skill. If it would only cause the agent to ask the user for the fact, it's reference → @-import.

Criterion 8: Instruction positioning

"Are the most critical instructions positioned for maximum attention?"

LLMs bias toward instructions at the beginning and end of a block. The most important rules should be at the top and bottom; less critical guidance goes in the middle. Check whether the current ordering reflects actual priority.

Phase 3: Evaluate structure

WHAT / WHY / HOW coverage

A good CLAUDE.md or AGENTS.md covers three dimensions:

• WHAT: technology stack, project structure, codebase topology — a map so the agent knows where to find things. Especially important for monorepos.
• WHY: what the project does and the role of each component. Without this, the agent can't make judgment calls.
• HOW: build tooling, test commands, verification procedures — execution instructions the agent needs to do meaningful work.

Check which dimensions are covered, which are missing, and which are over-represented.

Progressive disclosure

Content that doesn't need to be in every session should be externalized. Match the externalization mechanism to the content type (see Criterion 7):

• Operational content (trigger → action procedures, behavioral rules tied to user intent) → skills. Skills are the only mechanism with keyword-triggered auto-loading and a blocking invocation requirement. @-imports are unreliable for operational content — the agent may fail to attend to it when the triggering situation arises.
• File-type-specific conventions → .claude/rules/ with paths frontmatter. Auto-loaded when the agent touches matching files.
• Reference material (facts, lookups, infrequent data) → separate docs referenced with @ imports.
• Lengthy architectural explanations → standalone files with brief CLAUDE.md or AGENTS.md pointers (agent pulls on demand).

CLAUDE.md or AGENTS.md should list available resources with one-line descriptions so the agent knows they exist, not embed their full contents.

Anti-pattern to flag: See [context/foo.md](context/foo.md) with no surrounding context, pointing to operational content. Plain links are the weakest externalization — weaker than @-imports, which at least expand inline. If the target is operational, convert it to a skill. If it's reference, at minimum use an @-import.

Markdown structure

• Uses headers and bullets to group related instructions (Claude scans structure like a reader)
• No dense paragraphs of prose — bullets are more reliably followed
• Logical grouping: related rules are adjacent, not scattered

Phase 4: Output and applied-mode closeout

For analysis-only runs, provide the full report below. For --accept runs, apply the safe edits first, then give a concise closeout with before/after metrics, files changed, verification performed, commit hash if committed, and unresolved issues. Do not paste a full rewritten CLAUDE.md or AGENTS.md after applying it unless the user asks.

1. Metrics

Metric	Current	Target	Status
Total lines	N	< 200	ok/over
Instruction count	N	< 100	ok/over
Imports/rules	N	—	—

2. Per-instruction analysis

A table with columns: Instruction (short), Universal?, Specific?, Pointer?, Not linter?, Not default?, No conflict?, Right placement?, Positioned?. Mark failures.

3. Structural assessment

• WHAT/WHY/HOW coverage gaps
• Progressive disclosure opportunities (instructions that should be externalized)
• Positioning issues (critical rules buried in the middle)
• Markdown structure issues

4. Proposed changes

For each change, state:

• What to cut, move, merge, rewrite, or add
• Where it goes (stays in CLAUDE.md or AGENTS.md, moves to .claude/rules/, becomes a skill, becomes an @-import)
• Why

5. Rewritten CLAUDE.md or AGENTS.md

A complete rewritten version with:

• Dead weight removed
• Non-universal instructions externalized
• Vague instructions made specific or cut
• Style rules removed (moved to linter/hook)
• Pointers replacing embedded copies
• Critical instructions at top and bottom
• Clear WHAT/WHY/HOW structure
• No new rules added — only consolidation and restructuring

Show a diff summary of what changed.

6. Externalized files

For each file that needs to be created (.claude/rules/*.md, imported docs), provide the full content. In --accept mode, create or edit those files directly and summarize them in the closeout.

Phase 5: Verification

When edits are applied:

1. Re-read every changed instruction file for consistency and scope drift
2. Recount lines, discrete instructions, imports, and rules for the edited instruction set
3. Verify all @ imports and rules paths resolve, and confirm no private/local-only instruction was copied into a shared file unintentionally
4. Run project-specific checks or docs-sync checks when available
5. Inspect git diff and git status --short before committing or reporting completion

Guidelines

• Don't add content. This skill optimizes existing instructions — it consolidates, restructures, externalizes, and cuts. It does not invent new rules.
• Preserve intent. Every instruction that survives should mean the same thing it meant before. Rewriting for clarity is fine; changing the rule is not.
• Respect intentional overrides. Some instructions deliberately override the active agent system prompt defaults (e.g., "commit all changes immediately" overrides the default "only commit when asked"). These are high-value — flag them as intentional overrides, don't cut them.
• Hooks trump instructions. If a hook mechanically enforces a rule, the CLAUDE.md or AGENTS.md statement is redundant unless it provides context the hook can't (explaining why).
• Context skills trump CLAUDE.md or AGENTS.md for scoped rules. If a rule only applies in certain contexts (e.g., Elisp conventions), it belongs in a context skill or .claude/rules/, not the root instruction file or AGENTS.md.
• Ask before applying unless --accept is present. In --accept mode, apply only high-confidence, scope-preserving edits; report risky or broad changes as unresolved issues instead of half-applying them.