---

name: harness-audit description: Use when auditing, mapping, de-bloating, or reorganizing an agent harness - custom instructions, memory/CLAUDE.md/AGENTS.md files, system prompts, skills, permissions, hooks. Inventories every control, maps where/when/what/who/evidence, flags redundancy via One-Rule-One-Home-One-Owner, converts soft reminders into hard checks, and routes specialist context just-in-time to minimize always-on bloat. Triggers include "audit my harness", "map my skills", "reduce context bloat", "why does my agent ignore instructions", "clean up my CLAUDE.md or AGENTS.md", "consolidate skills", "harness map". allowed-tools:

• Bash
• Read
• Grep
• Glob
• Write
• Edit

---

harness-audit

Core principle

The goal is NOT to eliminate context, but to keep always-on context minimal and introduce deep or specialist context at the correct stage of the workflow. Every always-on instruction competes for attention; unused ones are bloat.

Safety gate (non-negotiable)

• Never move, delete, rewrite, or consolidate any instruction or configuration file without first producing a Before/After diff using assets/before-after.template.md and getting explicit user approval: "yes".
• Always Read a file before proposing to change it. The inventory sweep is read-only.
• Cleanup is opt-in per change. Default to propose, not apply.

Phase 1 - MAP (audit)

Run bash scripts/inventory.sh as a read-only sweep of every control location:

• Claude Code: ~/.claude/CLAUDE.md, project-level CLAUDE.md files, ~/.claude/settings.json and settings.local.json (permissions, hooks, env), ~/.claude/skills/*/SKILL.md (name, description, and preamble-tier), ~/.claude/agents/, installed plugins, output styles, and MCP server config.
• Codex: ~/.codex/AGENTS.md, ~/.codex/config.toml, ~/.codex/prompts/, and ~/.codex/agents/.

Build harness-map.json conforming to references/harness-map.schema.json. For each control capture: id, harness, path, load_trigger (one of always, on-skill-match, on-tool, manual), job (one line), owner (user | plugin:NAME | system), evidence (used_recently | referenced_elsewhere | unknown | stale), token_estimate, and tags[].

Validate with:

python3 scripts/validate-map.py harness-map.json references/harness-map.schema.json

Then render assets/MAP.template.md into a MAP.md the user can read in one place.

Phase 2 - ANALYZE

Apply references/audit-rules.md:

• One Rule, One Home, One Owner: Cluster semantically equivalent instructions across all files. For each duplicate cluster, propose one authoritative home and list the redundant copies to remove.
• Layer responsibility: For each instruction or complaint, classify it as likely model-failure or harness-failure. Flag soft reminders the model routinely ignores as candidates to convert into hard checks: schema, permission rule, hook, or strict tool-use gate.
• Bloat score: Rank each always-on control by its always-on cost versus evidence of utility.

Phase 3 - ROUTE (just-in-time loading)

Maintain a router index: a small table mapping task-intent to the reference file to load. The ONLY always-on context this skill adds is this SKILL.md top matter. Keep specialist knowledge—editorial guides, research parameters, and deep rules—in references/, and load it ONLY when the current task matches an intent. Never preload all references.

Phase 4 - CLEANUP (guarded)

For approved consolidations only, present a Before/After using assets/before-after.template.md, require explicit approval, and only then apply the approved change with Edit or Write. After every run, write a diagnostic receipt with python3 scripts/receipt.py, recording model, effort, active skills, tools used, fallbacks, and files changed.

Hard checks vs soft prompts

| Soft prompt | Hard check | |---|---| | “Please keep the map fields consistent.” | Validate harness-map.json against a JSON schema and fail on missing or invalid fields. | | “Remember not to edit protected files.” | Add a permission rule or pre-tool hook that blocks writes to protected paths. | | “Always read files before editing.” | Use a tool gate that permits Edit or Write only after a recorded Read of the target. | | “Run validation when finished.” | Use a validator script or post-tool hook whose nonzero exit blocks completion. |

Prefer a hard check when compliance can be objectively verified; retain soft prompts for judgment that cannot be encoded safely.

Context budgeting

Load deep context at the correct stage, not all upfront. Keep the always-on layer lean and push specialist detail into on-demand references.

Portability (Codex)

In Codex, tool names and invocation differ—see references/codex-tools.md. Invoke the skill in Codex via ~/.codex/prompts/harness-audit.md. Run scripts with the same bash and python3 commands.