Text Optimizer

Plugin: kochetkov-ma/claude-brewcode

Text Optimizer

Reduces token count in prompts, docs, and agent instructions by 20–40% without losing meaning. Applies 41 research-backed rules across 6 categories: Claude behavior, token efficiency, structure, reference integrity, perception, LLM comprehension.

Benefits: cheaper API calls · faster model responses · clearer LLM instructions · fewer hallucinations

Examples:

/text-optimize prompt.md          # single file, medium mode (default)
/text-optimize -d agents/         # deep mode — all .md files in directory

_Skill text is written for LLM consumption and optimized for token efficiency._

---

Text & File Optimizer

Step 0: Load Rules

REQUIRED: Read references/rules-review.md before ANY optimization.

If file not found -> ERROR + STOP. Do not proceed without rules reference.

Modes

Parse $ARGUMENTS: -l/--light | -d/--deep | no flag -> medium (default).

Rule ID Quick Reference

ID-to-Rule Mapping

Mode-to-Rules Mapping

Usage

File Processing

Input Parsing

Execution Flow

1. Read references/rules-review.md — load all optimization rules 2. Read target file(s) 3. Analyze: identify type (prompt, docs, agent, skill), note critical info and cross-references 4. Apply rules by mode (see Mode-to-Rules Mapping) 5. Edit file with optimized content 6. Generate optimization report

Quality Checklist

Before

• [ ] Read entire text
• [ ] Identify type (prompt, docs, agent, skill)
• [ ] Note critical info and cross-references

During — Apply by Mode

After

• [ ] All facts preserved
• [ ] Logic consistent
• [ ] References valid (R.1-R.3)
• [ ] Tokens reduced

Output Format

## Optimization Report: [filename]

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Lines  | X      | Y     | -Z%    |
| Tokens | ~X     | ~Y    | -Z%    |

### Rules Applied
- [Rule IDs]: [Description of changes]

### Issues Found & Fixed
- [Issue]: [Resolution]

### Cross-Reference Verification
- [x] All file refs valid (R.1)
- [x] All URLs checked (R.2)
- [x] No circular refs (R.3)

---

**Full development platform:** [brewcode](https://github.com/kochetkov-ma/claude-brewcode) — infinite focus tasks, 16 agents, quorum reviews, knowledge persistence.
Install: `claude plugin marketplace add https://github.com/kochetkov-ma/claude-brewcode && claude plugin install brewcode@claude-brewcode`

Anti-Patterns

Text Optimizer

Optimize prompts, CLAUDE.md, agent instructions, and documentation for LLM token efficiency. Applies 41 research-backed rules across 6 categories. Typical savings: 30-50% on prose, 20-30% on technical specs.

Quick Start

1. Install:

   npx skills add kochetkov-ma/claude-brewcode

2. Use via slash command:

   /text-optimizer my-prompt.md
   /text-optimizer my-prompt.md -d      # deep — max compression
   /text-optimizer my-prompt.md -l      # light — cleanup only
   /text-optimizer .claude/agents/      # directory — all .md files in parallel

Or via natural language prompt:

   Optimize my-prompt.md for token efficiency
   Optimize all agent instructions in .claude/agents/

Claude reads 41 rules, analyzes your files, applies transformations, and outputs a before/after report with token counts. For directories — finds all .md files and processes them in parallel.

Why Use This

• Token savings — 30-50% fewer tokens in system prompts means lower cost and more room for context
• Better compliance — rules based on how Claude 4.x actually processes instructions, not intuition
• Research-backed — every rule cites a source (Anthropic docs, arXiv papers, TACL 2024)
• Non-destructive — preserves all facts, logic, and cross-references; only changes form
• Three modes — light cleanup for stable docs, deep compression for cost-critical prompts

Examples

Single file — default medium mode

/text-optimizer CLAUDE.md

Applies all 41 rules with balanced restructuring. Best for most files.

<details> <summary>Optimization: filler removal + positive framing</summary>

Before:

Please note that it's important to remember that the API basically
requires authentication for all endpoints. Do not use markdown
formatting in your responses. You should never create new files
when fixing bugs.

After:

The API requires authentication for all endpoints. Write responses
in flowing prose without formatting. Apply all bug fixes to
existing files only.

Rules: filler removed (T.6), negative "do not" flipped to positive "do Y" (C.3), "you should" dropped for imperative (S.2).

</details>

<details> <summary>Optimization: prose to table</summary>

Before:

The function accepts three parameters: name (string, required),
age (number, optional, defaults to 0), and active (boolean,
optional, defaults to true).

After:

| Param  | Type    | Required | Default |
|--------|---------|----------|---------|
| name   | string  | yes      | —       |
| age    | number  | no       | 0       |
| active | boolean | no       | true    |

Rule: tables over prose for multi-column data (T.1).

</details>

Deep mode — max compression

/text-optimizer system-prompt.md -d

Aggressive rephrasing, section merging, all redundancy eliminated. Review the diff after — deep mode changes structure.

<details> <summary>Optimization: aggressive language toned down</summary>

Before:

CRITICAL: You MUST ALWAYS use this tool IMMEDIATELY when searching.
NEVER under ANY circumstances skip the validation step.

After:

Use this tool when the task involves file search.
Run validation before each deployment.

Rules: descriptive over emphatic (C.5), avoid ALL-CAPS in Claude 4.x (C.7). The model overtriggers on aggressive language — calm instructions get better compliance.

</details>

<details> <summary>Optimization: critical info repositioned</summary>

Before:

Here are the coding guidelines...
[20 pages of context]
...and remember, never expose API keys in logs.

After:

API keys must never appear in logs.

Here are the coding guidelines...
[20 pages of context]

Reminder: API keys must never appear in logs.

Rule: critical info at START and END (L.1). LLMs pay 40-50% less attention to middle content.

</details>

Light mode — safe cleanup

/text-optimizer production-prompt.md -l

Text cleanup only — no restructuring, no section merging. Safe for reviewed, stable documents.

<details> <summary>Optimization: filler and redundancy only</summary>

Before:

It is important to note that you should always make sure to validate
user input. Please remember that basically all external data needs
to be sanitized before processing.

After:

Validate all user input. Sanitize external data before processing.

Rules: filler removed (T.6), imperative form (S.2). Structure and sections stay intact.

</details>

Directory — parallel batch optimization

/text-optimizer .claude/agents/

Scans the directory, finds all .md files, and processes them in parallel. Each file gets its own optimization report. This is the fastest way to optimize an entire agents or skills folder at once.

/text-optimizer -d .claude/rules/

Deep mode on a directory — max compression for all rules files in parallel.

<details> <summary>Example: optimizing 5 agent files at once</summary>

/text-optimizer .claude/agents/

Found 5 files: developer.md, reviewer.md, tester.md, architect.md, bash-expert.md

Processing in parallel...

## Optimization Report: developer.md
| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Lines  | 142    | 98    | -31%   |
| Tokens | ~1850  | ~1190 | -36%   |

## Optimization Report: reviewer.md
| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Lines  | 203    | 131   | -35%   |
| Tokens | ~2640  | ~1580 | -40%   |

... (report for each file)

</details>

Multiple specific files

/text-optimizer CLAUDE.md, .claude/agents/reviewer.md, .claude/rules/testing.md

Comma-separated list — processes each file, generates a report for each.

Natural language

Optimize all agent instructions in .claude/agents/

Claude finds .claude/agents/*.md, applies medium mode to each in parallel.

Insights

Don't abbreviate domain terms

/text-optimizer -d api-docs.md

The optimizer will not shorten "authentication" to "auth" or "configuration" to "config" in instructions — even in deep mode. Why? Shortening domain terms caused 30+ point accuracy drops in benchmarks. The model picks the statistically dominant meaning of the abbreviation, which may not match your intent. Short forms (impl, cfg, env) are only used in tables where context is clear. (arXiv:2512.02246)

  # optimizer keeps full form in instructions:
- Ensure proper auth before accessing the config endpoint
+ Ensure proper authentication before accessing the configuration endpoint

  # but abbreviates in tables where column context disambiguates:
  | Param | Type | Desc |
  | auth  | bool | Enable authentication |

Code in prompts — strip whitespace

/text-optimizer system-prompt-with-code.md -d

If your prompt embeds Java/C++/C# code examples, the optimizer strips indentation — saving 11-22% tokens with under 1.6% quality loss. Python is excluded (whitespace is syntactic). (arXiv:2508.13666)

  # before — 4 levels of indentation:
- public class UserService {
-     public User findById(Long id) {
-         return repository.findById(id)
-             .orElseThrow(() -> new NotFoundException(id));
-     }
- }

  # after — stripped:
+ public class UserService {
+ public User findById(Long id) {
+ return repository.findById(id)
+ .orElseThrow(() -> new NotFoundException(id));
+ }
+ }

Long prompts — put constraints at edges

/text-optimizer long-system-prompt.md

The optimizer moves critical constraints to the beginning and end of the document. LLMs pay 40-50% less attention to content in the middle — the "Lost in the Middle" effect. (TACL 2024)

  # before — buried constraint:
  [page 1: introduction]
  [page 2: guidelines]
- [page 3: ...and never expose API keys in logs.]
  [page 4: examples]

  # after — sandwiched at edges:
+ API keys must never appear in logs.
  [page 1: introduction]
  [page 2: guidelines]
  [page 3: examples]
+ Reminder: API keys must never appear in logs.

RAG / multi-document prompts — query goes last

/text-optimizer rag-prompt-template.md

If your prompt template has {{DOCUMENTS}} and a question, the optimizer reorders: documents first, query last. This improves quality by up to 30% on multi-document inputs. (Anthropic)

  # before:
- Question: {{USER_QUERY}}
- Context: {{DOCUMENTS}}
- Answer based on the context above.

  # after:
+ <context>
+ {{DOCUMENTS}}
+ </context>
+ Question: {{USER_QUERY}}
+ Answer based on the context above.

Templates with variables — XML boundaries added

/text-optimizer prompt-template.md

The optimizer wraps {{VARIABLE}} sections in XML tags. Without boundaries, injected user content can look like system instructions — this is the most reliable prompt injection defense. (Anthropic)

  # before — no boundaries:
- You are a helpful assistant.
- User message: {{USER_INPUT}}
- Respond helpfully.

  # after — XML-wrapped:
+ You are a helpful assistant.
+ <user-message>
+ {{USER_INPUT}}
+ </user-message>
+ Respond helpfully.

Modes In Detail

Light (-l)

Text cleanup without restructuring. Safe for stable, reviewed documents.

Applies: Claude behavior rules (C.1-C.8), filler removal (T.6), reference checks (R.1-R.3), perception basics (P.1-P.4).

Skips: Table/bullet restructuring, XML tags, section merging.

Use for: Production prompts where structure is intentional, docs that have been through review.

Medium (default)

Balanced restructuring — all 41 rules applied with standard transformations.

Applies: All categories (C + T + S + R + P + L).

Use for: Most files — CLAUDE.md, agent instructions, skill definitions, technical docs.

Deep (-d)

Maximum compression. Merges sections, rephrases aggressively, eliminates all redundancy.

Applies: All rules + aggressive rephrasing and section merging.

Use for: Cost-critical system prompts, context-limited scenarios. Review the diff carefully after.

Comparison

Rule Categories

Full rules with research citations: `references/rules-review.md`

Sources

• Claude 4 Best Practices — Anthropic
• Effective Context Engineering — Anthropic
• Claude Code Best Practices — Anthropic
• Lost in the Middle — TACL 2024
• DETAIL Matters — arXiv 2024
• Whitespace Stripping — arXiv 2025
• Prompt Repetition — Google Research 2024
• Brex Prompt Engineering — Brex

Part of Brewcode

This skill is extracted from brewcode — a development platform for Claude Code with infinite focus tasks, 16 agents, quorum reviews, and knowledge persistence.

claude plugin marketplace add https://github.com/kochetkov-ma/claude-brewcode
claude plugin install brewcode@claude-brewcode

License

MIT

LLM Text Optimization and Comprehension Rules

Categorized rules for LLM token efficiency and comprehension optimization with 41 rules across 6 categories. Apply by category. Reference specific IDs in reviews (e.g., "violates T.1").

C - Claude Behavior

T - Token Efficiency

S - Structure

R - Reference Integrity

P - Perception

L - LLM Comprehension

How content is perceived and processed by the LLM — not about token count but comprehension quality.

Rules NOT Recommended

Compression Ratios (Token Efficiency)

These ratios reflect token savings from applying T and S category rules. L category rules improve comprehension quality without necessarily reducing token count.

Sources

• Claude 4 Best Practices
• Context Engineering
• Claude Code Best Practices
• Extended Thinking
• Agent Skills Best Practices
• Skills Activation
• Improving Agents
• Position Bias in LLMs
• Lost in the Middle (TACL 2024)
• Prompt Repetition (arXiv:2512.14982)
• DETAIL Matters (arXiv:2512.02246)
• Whitespace Stripping (arXiv:2508.13666)
• Brex Prompt Engineering Guide