mk:context-audit

/mk:context-audit — Context Window Structural Audit

Read-only audit of .claude/ structural overhead. Surfaces what is loaded into every host-runtime session and how much of the context window it consumes, then recommends the highest-leverage trims.

When to Use

Three concrete triggers:

1. Pre-add capacity check — before adding a new agent, skill, or rule file,

confirm the project is below the 25% structural-overhead threshold.

1. Post-degradation diagnostic — when sessions feel slow, off-topic, or

over-compacted, audit to see if structural overhead has grown past 10%.

1. Periodic health audit — quarterly or on model upgrades, confirm

the always-on bundle still pays its keep (paired with the dead-weight audit in harness-rules.md Rule 7).

Context vs Cost (Boundary)

| Concern | Mechanism | Unit | | ------------------------------- | -------------------------------------------------------- | ------------- | | Monetary cost | /mk:budget + harness/scripts/budget-tracker.sh | USD | | Window utilization (this skill) | /mk:context-audit + scripts/inventory-context.sh | tokens / % |

The three concerns are deliberately separate. This skill measures only what is statically loaded into every session — the always-on bundle. Conversation history, tool output, and active edits live elsewhere.

Workflow

The slash command runs the pipeline:

SCAN_ROOT="${1:-$PWD}"
bash .claude/skills/context-audit/scripts/inventory-context.sh "$SCAN_ROOT" \
  | bash .claude/skills/context-audit/scripts/estimate-tokens.sh \
  | bash .claude/skills/context-audit/scripts/format-audit-report.sh

Output is markdown, printed to terminal. The skill does NOT write any files.

Steps:

1. Inventory — inventory-context.sh walks .claude/ and emits raw

byte/line counts per category (CLAUDE.md chain, agents, skills, rules, commands, MCP) as JSON.

1. Estimate — estimate-tokens.sh enriches the inventory with

estimated_tokens (chars/4 heuristic, mirrors budget-tracker.cjs) and computes totals including structural_overhead_pct against a 200K window.

1. Format — format-audit-report.sh emits a 5-section markdown report:

header, summary table, top consumers, recommendations, footer.

1. Banner — the formatter selects a banner based on

structural_overhead_pct:

• < 10% → Healthy
• 10–25% → Watch
• ≥ 25% → Action recommended

Output Format

# Context Audit — <scan_root>
*Scanned at <timestamp> · model window 200K tokens · banner: <Healthy|Watch|Action>*

## Summary
| Category | Components | Bytes | Tokens | % of Window |
| ...      | ...        | ...   | ...    | ...          |

## Top Consumers
1. <component> ~<tokens> (<path>)
... (top 10)

## Recommendations
1. <priority finding> — saves ~<tokens>
... (sorted by token impact, descending)

## How to Act
- Cost: see `/mk:budget`
- Runtime trim: see `mk:lazy-agent-loader`

The 10% / 25% thresholds are the canonical source of truth for token-overhead banners — see references/token-cost-model.md. They are NOT linked to MEOWKIT_BUDGET_* env vars (those are USD amounts, not token percentages).

Integration Points

• Reuses, does not duplicate: packages/cli/src/orchviz/token-estimator.ts

is the canonical chars/4 source. Shell scripts inline the same heuristic with a citation comment, avoiding a Node bridge that would require dist/.

• Reads, does not write: .claude/memory/cost-log.json,

.claude/, .mcp.json. No file writes anywhere.

• No env vars introduced. Window size is hard-coded 200K; override deferred

until a real 1M-context use case appears.

• Discovery: via keywords: frontmatter and a cross-reference from

/mk:budget. There is no separate routing rule.

Gotchas

(none yet — grow from observed failures)

Related Rules

• .claude/rules/skill-authoring-rules.md — discovery + Gotchas section requirements
• .claude/rules/injection-rules.md Rule 11 — Skill Rule of Two; this skill

scores 2 of 3 (untrusted SCAN_ROOT input + filename inventory may surface sensitive paths) so paths are canonicalized via realpath and never executed.