Optimize Prompt Token Efficiency

Iteratively optimize prompt token efficiency by maximizing information density through verification loops. Primary goal: reduce token consumption while preserving all semantic content for AI-consumed prompts (CLAUDE.md, skills, agent prompts, specs).

Overview

This skill transforms verbose prompts into token-efficient versions through:

• Verification First - prompt-token-efficiency-verifier checks for inefficiencies before any changes

• Optimization - Apply targeted compression based on verifier feedback

• Re-verification - Verify compression is lossless, iterate if issues remain (max 5 iterations)

• Output - Atomic replacement only after verification passes

Loop: Read → Verify → (Exit if efficient) → Optimize based on feedback → Re-verify → (Iterate if issues) → Output

Key principle: Don't try to optimize in one pass. The verifier drives all changes - if it finds no inefficiencies, the prompt is already token-efficient.

Workflow

Phase 0: Create Task List (use task management immediately)

Create todos tracking workflow phases. List reflects areas of work, not fixed steps.

Starter todos:

• Input validation
• Initial verification
• (Expand: optimization iterations on INEFFICIENCIES_FOUND)
• Output optimized prompt

Phase 1: Input Validation

Mark "Input validation" todo in_progress .

Step 1.1: Parse arguments

Extract file path from $ARGUMENTS . If no path provided, error with usage instructions.

Step 1.2: Validate file

• Check file exists using Read tool

• Verify supported type: .md , .txt , .yaml , .json

• If unsupported, error: "Unsupported file type. Supported: .md, .txt, .yaml, .json"

Step 1.3: Read and measure original

• Read file content

• Estimate token count: Math.ceil(content.length / 4) (approximate)

• Store original content and token count for comparison

Step 1.4: Store metadata

• original_path : Source file path

• original_content : Full prompt text

• original_tokens : Estimated token count

• working_path : /tmp/optimized-efficiency-{timestamp}.{ext} for iterations

Mark "Input validation" todo completed .

Phase 2: Initial Verification

Mark "Initial verification" todo in_progress .

Step 2.1: Copy to working path

Copy original content to working_path using Write tool (verification needs a file path).

Step 2.2: Run verifier first

Launch prompt-token-efficiency-verifier agent via Task tool BEFORE any optimization:

• subagent_type: "prompt-engineering:prompt-token-efficiency-verifier"

• prompt: "Verify prompt token efficiency. File: {working_path}. Check for redundancy, verbose phrasing, filler words, structural inefficiencies, and compression opportunities. Report VERIFIED if already efficient, or INEFFICIENCIES_FOUND with specific details."

Step 2.3: Handle verifier response

• If "VERIFIED": Mark todo completed, proceed directly to Phase 4 (Output) with message: "Prompt is already token-efficient. No changes needed."

• If "INEFFICIENCIES_FOUND": Mark todo completed, save the issues list, add "Optimization iteration 1" todo and proceed to Phase 3

• If verifier fails or returns unexpected format: Retry once with identical parameters. If retry fails, report error: "Verification failed - cannot proceed without verifier."

Step 2.4: Display verifier findings

If inefficiencies found, show user summary and proceed:

Verifier found {count} token efficiency issues. Proceeding with optimization...

Mark "Initial verification" todo completed .

Phase 3: Optimization Loop (Verifier-Driven)

Mark "Optimization iteration 1" todo in_progress .

Key principle: All fixes are driven by verifier feedback. Do NOT analyze the prompt independently - only fix the specific inefficiencies the verifier reported.

For each iteration from 1 to 5:

Apply compressions from verifier feedback: For each inefficiency in the verifier's report, apply the suggested compression. Write optimized version to working_path.

• Only fix inefficiencies the verifier identified - do not add your own improvements

Re-verify: Launch prompt-token-efficiency-verifier agent via Task tool:

• subagent_type: "prompt-engineering:prompt-token-efficiency-verifier"

• prompt: "Verify compression is lossless. Original file: {original_path}. Compressed file: {working_path}. Compare semantic content - check for missing facts, altered meaning, lost emphasis, removed nuance. Report VERIFIED if lossless, or ISSUES_FOUND with specific gaps."

Handle response:

• If "VERIFIED": mark todo completed, exit loop, proceed to Phase 4

• If "ISSUES_FOUND" and iteration < 5: mark todo completed, save new issues list, add "Optimization iteration {next}" todo, continue to next iteration

• If "ISSUES_FOUND" and iteration = 5: mark todo completed with note about unresolved issues, proceed to Phase 4 with warning

• If verifier fails or returns unexpected format: display error to user, retry once with identical parameters. If retry fails, proceed to Phase 4 with warning: "Verification incomplete - manual review recommended."

Compression Techniques

Apply these techniques to fix inefficiencies flagged by the verifier:

Technique Description Before → After

Redundancy removal Eliminate repeated concepts "It is important to note that you should always remember to..." → "Always..."

Terse phrasing Replace verbose constructions "In order to accomplish this task, you will need to..." → "To do this:"

Filler elimination Remove hedging, qualifiers, throat-clearing "Make sure that you do not forget to include..." → "Include:"

Structural optimization Merge/reorganize sections "First X. After that Y. Then Z." → "Steps: X → Y → Z"

Context-aware abbreviation Abbreviate terms after first mention "Model Context Protocol server" (×10) → "MCP server" (after first)

Dense formatting Use lists, tables, compact notation Prose paragraphs → Tables, bullet lists

Transformation Rules:

• Preserve ALL semantic information - Every fact, instruction, constraint, and example must be present

• Preserve nuance and emphasis - Bold, caps, repetition, ordering that signals priority; intentional hedging (uncertainty was meaningful)

• Restructuring allowed - Reorder, merge sections if it increases density WITHOUT losing priority signals

• Format preservation - Output must be same format as input (markdown stays markdown)

• No reduction target - 10% reduction with nuance preserved > 40% reduction with nuance lost

Avoid creating ambiguity:

• Don't merge conditions with different triggers ("when A, do X; when B, do Y" ≠ "when A/B, do X/Y")

• Keep explicit referents (don't reduce "Use Read tool" to "Use the tool" if context is unclear)

• Don't flatten relationships ("A requires B, C requires D" ≠ "A, C require B, D")

• Ensure scope is clear (qualifier applies to which items?)

Phase 4: Output

Mark "Output optimized prompt" todo in_progress .

Step 4.1: Calculate metrics

• Original token count (from Phase 1)

• Compressed token count: Math.ceil(compressed_content.length / 4)

• Reduction percentage: ((original - compressed) / original * 100).toFixed(0)

Step 4.2: Apply changes (atomic replacement)

If verification passed:

Replace original atomically

mv {working_path} {original_path}

Step 4.3: Display results

If verification passed:

Optimized: {path} Iterations: {count} Original: {original_tokens} tokens Optimized: {compressed_tokens} tokens Reduction: {percentage}%

Changes applied:

• {summary of compressions}

Status: Token-efficient and lossless

If verification failed after 5 iterations:

Optimized with warnings: {path} Iterations: 5 Original: {original_tokens} tokens Optimized: {compressed_tokens} tokens Reduction: {percentage}%

Unresolved issues:

• {list from last verification}

Review the changes manually.

Mark "Output optimized prompt" todo completed . Mark all todos complete.

Key Principles

Principle Rule

Verify first Always run verifier before any optimization; maybe prompt is already efficient

Verifier-driven Only fix inefficiencies the verifier identifies - no independent analysis or improvements

Track progress Use task management to track phases; expand tasks on iteration

Losslessness Never sacrifice semantic information for density; every fact must be preserved

Nuance preservation Keep emphasis, intentional hedging, priority signals; 10% with nuance > 40% without

No ambiguity Compressed must be as unambiguous as original

Verification required Never output without verifier checking

Atomic output Original untouched until verification passes

Edge Cases

Scenario Handling

No input provided Error: "Usage: /optimize-prompt-token-efficiency "

File not found Error: "File not found: {path}"

Unsupported type Error: "Unsupported file type. Supported: .md, .txt, .yaml, .json"

Already efficient Verifier returns VERIFIED on first check → Report: "Prompt is already token-efficient. No changes needed."

Initial verifier fails Retry once; if still fails, Error: "Verification failed - cannot proceed without verifier."

Re-verification fails Display error, retry once; if retry fails, output with warning

YAML/JSON structure Preserve structure validity, compress string values only

Very large file (>50KB) Process as single unit

0-10% reduction Success: "Content was already near-optimal density"

Verification fails 5x Output best attempt with warning

Example Usage

Optimize a verbose CLAUDE.md

/optimize-prompt-token-efficiency CLAUDE.md

Optimize a skill file

/optimize-prompt-token-efficiency claude-plugins/my-plugin/skills/my-skill/SKILL.md

Optimize an agent prompt

/optimize-prompt-token-efficiency agents/code-reviewer.md

Example Output

Optimized: docs/README.md Iterations: 2 Original: 4,250 tokens Optimized: 3,612 tokens Reduction: 15%

Changes applied:

• Removed redundant intro section
• Consolidated overlapping examples
• Tersified verbose instructions
• Preserved emphasis markers and conditional logic

Status: Token-efficient and lossless

Prompt is already token-efficient. No changes needed. Original: 1,995 tokens