zbeam-token-optimizer

name: zbeam-token-optimizer description: "Full token audit-and-implement cycle. Use when the user asks to reduce token waste, optimize skills, or improve pipeline efficiency."

Token Optimizer

Full audit-and-implement cycle. Measure baseline, research best practices, fix all waste patterns directly in source files, measure after, report actual reduction. Do not produce a report and stop — implement every fix and confirm the numbers before finishing.

Phase 0: Baseline measurement — run BEFORE any edits

This is the number you will compare against after optimization. Without it the report is fiction.

SKILLS_DIR="skills"

echo "=== BASELINE ===" > /tmp/token-baseline.txt
echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /tmp/token-baseline.txt
echo "" >> /tmp/token-baseline.txt

# 1. Description field sizes (loaded every session a skill is available)
echo "--- Description word counts ---" >> /tmp/token-baseline.txt
grep -r "^description:" "$SKILLS_DIR" --include="SKILL.md" -l | while read f; do
  words=$(grep "^description:" "$f" | wc -w)
  echo "$f: $words words" >> /tmp/token-baseline.txt
done

# 2. SKILL.md line counts (loaded on invocation)
echo "" >> /tmp/token-baseline.txt
echo "--- SKILL.md line counts ---" >> /tmp/token-baseline.txt
find "$SKILLS_DIR" -name "SKILL.md" | while read f; do
  lines=$(wc -l < "$f")
  echo "$f: $lines lines" >> /tmp/token-baseline.txt
done

# 3. Totals
total_desc_chars=$(grep -r "^description:" "$SKILLS_DIR" --include="SKILL.md" -h | wc -c)
total_skill_lines=$(find "$SKILLS_DIR" -name "SKILL.md" -exec wc -l {} + | tail -1 | awk '{print $1}')
echo "" >> /tmp/token-baseline.txt
echo "Total description chars (session overhead per skill set): $total_desc_chars" >> /tmp/token-baseline.txt
echo "Total SKILL.md lines (invocation overhead): $total_skill_lines" >> /tmp/token-baseline.txt

cat /tmp/token-baseline.txt

Save these numbers. The report in Phase 5 will compare directly against them.

Phase 1: Research current best practices

Search for the latest Anthropic guidance on token efficiency:

• site:docs.claude.com token efficiency OR prompt caching OR progressive disclosure
• site:claude.com/blog token OR caching OR efficiency 2025 OR 2026

Extract any new patterns or thresholds not already reflected in the skills.

Phase 2: Audit all active skills

Read every SKILL.md in the active pipeline from <available_skills>. For each skill measure:

Size

• Flag any SKILL.md over 300 lines — candidate for reference file extraction
• Flag any reference file over 300 lines without a table of contents

Description bloat

• Count words in each description field
• Flag any over 25 words — trim to ~20, preserving all trigger phrases

Conditional content loaded unconditionally

• Identify sections only needed in specific modes (e.g., monthly vs weekly, Mode A vs Mode B, new page vs update)
• These belong in references/ files loaded on demand, not in the main SKILL.md body

Subagent overuse

• Flag any "always use subagent" instruction that doesn't account for simple cases
• Propose tiered alternative

Output verbosity instructions

• Flag instructions that generate unnecessary narration between tool calls

Phase 3: Implement all fixes

For each issue found, fix it immediately — do not defer:

Description trim: Edit the description field in the SKILL.md frontmatter directly.

Reference file extraction:

1. Create references/[section-name].md with the extracted content
2. Replace the extracted section in SKILL.md with a 2-3 line pointer
3. Pointer format: ## [Section name]\n\nRead \references/[file].md` for [what it contains]. Only needed when [condition].`

Subagent tiering: Edit the instruction in place with a tiered alternative.

Broken content: Fix in place.

After all edits, verify line counts and confirm each file is shorter than before.

Phase 4: Repackage

For every skill that was modified:

1. Run package_skill from the skill-creator directory:

   cd /[path-to]/skill-creator && python3 -m scripts.package_skill [skill-path] [outputs-path]
   

2. Present all updated .skill files for install

Phase 5: After measurement + actual report

Run the same commands from Phase 0 against the now-modified files:

SKILLS_DIR="skills"

echo "=== AFTER ===" > /tmp/token-after.txt
echo "Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /tmp/token-after.txt
echo "" >> /tmp/token-after.txt

echo "--- Description word counts ---" >> /tmp/token-after.txt
grep -r "^description:" "$SKILLS_DIR" --include="SKILL.md" -l | while read f; do
  words=$(grep "^description:" "$f" | wc -w)
  echo "$f: $words words" >> /tmp/token-after.txt
done

echo "" >> /tmp/token-after.txt
echo "--- SKILL.md line counts ---" >> /tmp/token-after.txt
find "$SKILLS_DIR" -name "SKILL.md" | while read f; do
  lines=$(wc -l < "$f")
  echo "$f: $lines lines" >> /tmp/token-after.txt
done

total_desc_chars_after=$(grep -r "^description:" "$SKILLS_DIR" --include="SKILL.md" -h | wc -c)
total_skill_lines_after=$(find "$SKILLS_DIR" -name "SKILL.md" -exec wc -l {} + | tail -1 | awk '{print $1}')
echo "" >> /tmp/token-after.txt
echo "Total description chars: $total_desc_chars_after" >> /tmp/token-after.txt
echo "Total SKILL.md lines: $total_skill_lines_after" >> /tmp/token-after.txt

cat /tmp/token-after.txt

Now diff baseline vs after and produce the real report:

## Token Optimizer Report: [date]

### Baseline vs After
| Metric | Before | After | Δ |
|---|---|---|---|
| Total description chars | [from Phase 0] | [from Phase 5] | [diff] |
| Total SKILL.md lines | [from Phase 0] | [from Phase 5] | [diff] |

### Per-skill changes
| Skill | Before (lines) | After (lines) | Description change |
|---|---|---|---|
| [skill] | [n] | [n] | [n words → n words] |

### Actual session overhead reduction
Description chars saved: [n] chars × [n skills active per session] = [n] chars/session
At ~4 chars/token: **[n] tokens saved per session**

### Files modified
- [list]

### Issues found but not fixable
- [list or "none"]

Save the after-measurement JSON to: data/audit/token-after-[YYYY-MM-DD].json

Constraints

• Edit source files directly — never work on copies
• Never trim content that affects skill correctness — only redundant, conditional, or duplicated content
• If a reference file already exists for a section, check it has a TOC before adding content
• Descriptions must preserve all trigger phrases — shorter but not less accurate
• The skill-creator packager must be run from its own directory for module imports to resolve