Token Audit — Repository Context Optimization Skill

Token Audit — Repository Context Optimization

Purpose

When Pantheon is installed in a new repository, run this skill to audit and optimize all AI context files for token efficiency.

Step 1: Discover Context Files

Scan the repository for ALL files that contribute to AI context:

# Auto-loaded files (every invocation)
AGENTS.md
CLAUDE.md
.gemini/AGENTS.md
.github/copilot-instructions.md
.github/instructions/*.md
.claude/CLAUDE.md
.cursor/rules/*.mdc
.windsurfrules
.kilocode/rules/*.md
.clinerules
.opencode/agents/*.agent.md

# Memory bank
docs/memory-bank/*.md
docs/adr/*.md

# Skills (lazy-load)
.github/skills/*/SKILL.md
.claude/skills/*/SKILL.md
.opencode/skills/*/SKILL.md

Step 2: Build Redundancy Map

Read all discovered files and map what information appears where:

| Information | Found in files | Lines duplicated | |---|---|---| | Tech stack | AGENTS.md, 00-overview.md, copilot-instructions.md | ~15 | | Run commands | AGENTS.md, 03-tech-context.md, commands.md | ~10 | | Agent roles | AGENTS.md, copilot-instructions.md, zeus.agent.md | ~20 | | CI/CD rules | AGENTS.md, copilot-instructions.md, .github/workflows | ~12 | | Coding standards | copilot-instructions.md, instructions/*.md | ~25 |

Step 3: Measure Baseline

Count lines and estimate tokens:

# Auto-loaded context (every invocation)
wc -l AGENTS.md .github/copilot-instructions.md /memories/repo/*.md 2>/dev/null

# On-demand context (read by agents)
wc -l docs/memory-bank/*.md 2>/dev/null

# Skills (lazy-load)
find .github/skills .claude/skills .opencode/skills -name "SKILL.md" 2>/dev/null | xargs wc -l 2>/dev/null

# Agent definitions
wc -l .github/agents/*.agent.md .opencode/agents/*.agent.md .claude/agents/*.agent.md 2>/dev/null

Estimate: 1 line ≈ 4 tokens (markdown average)

Step 4: Identify Red Flags

Check for content that should NOT be auto-loaded. Use specific patterns, not generic keywords:

[ ] Wave delivery tables: Wave 1:, Wave 2:, ## Wave, wave-by-wave (NOT "DAG Waves" pattern)
[ ] Delivery history: delivered:, what was delivered, delivery history, delivery log
[ ] Progress metrics: [0-9]+% complete, commit count, commits: [0-9] (NOT in progress-log.md)
[ ] Last-updated dates: **Last Updated**:, <!-- last.updated: (git has this)
[ ] Cleanup logs: deleted X lines of dead code, legacy cleanup, cleaned up X
[ ] Duplicated tech stack: same phrase in >3 files (use long phrases, not single words)
[ ] Files exceeding line limits: AGENTS.md >80, memory-bank >100
[ ] Empty or near-empty files that waste discovery overhead

Skip files where the keyword is expected:

progress-log.md → skip "progress" checks
active-context.md → skip "wave" checks (may reference wave patterns legitimately)
Architecture docs → skip "DAG Waves" (it's a pattern name, not historical content)

Step 5: Recommendations

Generate a structured report:

Immediate Actions (high impact)

Consolidate duplicated files — merge files with >50% content overlap
Remove historical content — move delivery logs, wave tables to git/issues
Compress verbose sections — convert prose to tables (40-60% token savings)
Delete derivable content — router lists, entity tables that exist in code

Structural Changes (medium impact)

Create lazy-load skills — move operational procedures from auto-loaded files to skills/
Set up memory bank — 3 files max: project.md, active-context.md, progress-log.md
Shorten descriptions — agent/command/skill descriptions under 100 chars

Ongoing (maintenance)

Set line limits — AGENTS.md < 80, memory-bank files < 100
Re-audit after major changes — run this skill quarterly or after big features

Step 6: Apply Optimizations

If user approves, execute:

Merge redundant files
Delete historical content
Compress verbose sections (prose → tables)
Create skills for heavy operational content
Set up optimized memory bank structure
Update cross-references

Output Format

## Token Audit Report

### Baseline
- Auto-loaded: X lines (~Y tokens)
- On-demand: X lines (~Y tokens)
- Skills: N files, X lines total
- Agents: N files, X lines total
- **Total baseline: ~Y tokens per invocation**

### Redundancy
- X instances of duplicated content found
- Estimated waste: ~Y tokens per invocation

### Red Flags
- X files with historical content
- X files with derivable content (exists in code)
- X files exceeding line limits

### Recommended Actions
1. [action] — saves ~Y tokens
2. [action] — saves ~Y tokens
...

### Projected After Optimization
- Auto-loaded: X lines (~Y tokens) — **Z% reduction**

Agent Skills: Token Audit — Repository Context Optimization

Install this agent skill to your local

Skill Files