Brewcode:Text Optimize

Name: Brewcode:Text Optimize
Author: kochetkov-ma

kochetkov-ma/claude-brewcode

13 installs
29 repo stars
Updated August 2, 2026
kochetkov-ma/claude-brewcode

Optimize text and documentation for LLM token efficiency using 52 smart deduplication and lossy compression rules.

About

brewcode:text-optimize reduces token count in documentation and code comments using 52 smart rules. A solo builder reaches for it when managing context windows, preparing long docs for LLM input, or shrinking CLAUDE.md and README files without losing essential information.

52 token optimization rules
Smart deduplication
Aggressive lossy compression
Preserves semantic meaning

Brewcode:Text Optimize by the numbers

13 all-time installs (skills.sh)
Ranked #2,148 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/kochetkov-ma/claude-brewcode --skill brewcodetext-optimize

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/kochetkov-ma/claude-brewcode/brewcode%3Atext-optimize.svg)](https://skillselion.com/skills/kochetkov-ma/claude-brewcode/brewcode%3Atext-optimize)

Installs	13
repo stars	★ 29
Last updated	August 2, 2026
Repository	kochetkov-ma/claude-brewcode ↗

What it does

Optimize text and documentation for LLM token efficiency using 52 smart deduplication and lossy compression rules.

What you get

optimized text
reduced documentation

Files

SKILL.mdMarkdownGitHub ↗

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).

Mode	Flag	Scope
Light	`-l`, `--light`	Text cleanup only — structure, lists, flow untouched
Medium	_(default)_	Balanced restructuring — all standard transformations
Deep	`-d`, `--deep`	Max density — rephrase, merge, compress aggressively

Rule ID Quick Reference

Category	Rule IDs	Scope
Claude behavior	C.1-C.6	Literal following, avoid "think", positive framing, match style, descriptive instructions, overengineering
Token efficiency	T.1-T.8	Tables, bullets, one-liners, inline code, abbreviations, filler, comma lists, arrows
Structure	S.1-S.8	XML tags, imperative, single source, context/motivation, blockquotes, progressive disclosure, consistent terminology, ref depth
Reference integrity	R.1-R.3	Verify file paths, check URLs, linearize circular refs
Perception	P.1-P.6	Examples near rules, hierarchy, bold keywords, standard symbols, instruction order, default over options

ID-to-Rule Mapping

ID	Rule	ID	Rule
C.1	Literal instruction following	C.2	Avoid "think" word
C.3	Positive framing (do Y not don't X)	C.4	Match prompt style to output
C.5	Descriptive over emphatic instructions	C.6	Overengineering prevention
T.1	Tables over prose (multi-column)	T.2	Bullets over numbered (~5-10%)
T.3	One-liners for rules	T.4	Inline code over blocks
T.5	Standard abbreviations (tables only)	T.6	Remove filler words
T.7	Comma-separated inline lists	T.8	Arrows for flow notation
S.1	XML tags for sections	S.2	Imperative form
S.3	Single source of truth	S.4	Add context/motivation
S.5	Blockquotes for critical	S.6	Progressive disclosure
R.1	Verify file paths	R.2	Check URLs
R.3	Linearize circular refs	P.1	Examples near rules
P.2	Hierarchy via headers (max 3-4)	P.3	Bold for keywords (max 2-3/100 lines)
P.4	Standard symbols (→ + / ✅❌⚠️)
S.7	Consistent terminology	S.8	One-level reference depth
P.5	Instruction order (anchoring)	P.6	Default over options

Mode-to-Rules Mapping

Mode	Applies	Notes
Light	C.1-C.6, T.6, R.1-R.3, P.1-P.4	Text cleanup only — no restructuring
Medium	All rules (C + T + S + R + P)	Balanced transformations
Deep	All rules + aggressive rephrasing	Merge sections, max compression

Usage Examples

Command	Description
`/brewcode:text-optimize`	Optimize ALL: `CLAUDE.md`, `.claude/agents/.md`, `.claude/skills/*/SKILL.md`
`/brewcode:text-optimize file.md`	Single file (medium mode)
`/brewcode:text-optimize -l file.md`	Light mode — text cleanup only, structure untouched
`/brewcode:text-optimize -d file.md`	Deep mode — max compression, review diff after
`/brewcode:text-optimize path1.md, path2.md`	Multiple files — parallel processing
`/brewcode:text-optimize -d agents/`	Directory — all `.md` files with specified mode

File Processing

Input Parsing

Input	Action
No args	Optimize ALL: `.claude/agents/.md`, `.claude/skills/*/SKILL.md`, `CLAUDE.md`
Single path	Process directly
`path1, path2`	Parallel processing

2-Phase Execution

Phase 1: Analysis — Parallel Explore agents

Task(subagent_type: "Explore", prompt: "Analyze {file}: structure, dependencies, cross-refs, redundancies")

Phase 2: Optimization — Parallel text-optimizer agents

Context: BC_PLUGIN_ROOT is available in your context (injected by pre-task.mjs hook). Use it to access plugin resources.

Task(subagent_type: "text-optimizer", prompt: "FIRST: Read $BC_PLUGIN_ROOT/skills/text-optimize/references/rules-review.md for validation rules. THEN optimize {file} using {mode} mode. Apply transformations, verify refs, output report with metrics.")

Spawn parallel: For multiple files, spawn ALL agents in ONE message for speed.

Quality Checklist

Before

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

During — Apply by Mode

Check	Light	Med	Deep
C.1-C.6 (Claude behavior)	Yes	Yes	Yes
T.6 (filler removal)	Yes	Yes	Yes
T.1-T.5, T.7-T.8 (token compression)	-	Yes	Yes
S.1-S.8 (structure/clarity)	-	Yes	Yes
R.1-R.3 (reference integrity)	Yes	Yes	Yes
P.1-P.4 (LLM perception)	Yes	Yes	Yes
Aggressive rephrasing	-	-	Yes
No information loss	Yes	Yes	Yes

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)

Anti-Patterns

Avoid	Why
Remove all examples	Hurts generalization (P.1)
Over-abbreviate	Reduces readability (T.5 caveat)
Generic compression	Domain terms matter
Over-aggressive language	Opus 4.5 overtriggers (C.5)
Flatten hierarchy	Loses structure (P.2)
"Don't do X" framing	Less effective than "Do Y" (C.3)
Overengineer prompts	Opus 4.5 follows literally (C.6)
Overload single prompts	Divided attention, hallucinations (S.3)
Over-focus on wording	Structure > word choice (T.1)

Text & File Optimizer

Optimize any text, file, or folder for maximum clarity and efficiency when working with Claude 4.x / Opus 4.5. Reduces tokens by restructuring prose to tables, removing filler, and applying best practices for LLM consumption.

Quick Start

/brewcode:text-optimize [options] [file or folder]

Modes

Mode	Flag	Best For
Light	`-l`	Text cleanup only — removes filler, fixes tone, keeps structure
Medium	_(default)_	Balanced — converts tables, removes redundancy, merges duplicates
Deep	`-d`	Maximum compression — aggressive rephrasing, review diff after

Examples

# Medium mode (default)
/brewcode:text-optimize CLAUDE.md

# Light mode — safe for critical files
/brewcode:text-optimize -l CLAUDE.md

# Deep mode — max compression
/brewcode:text-optimize -d agents/my-agent.md

# Multiple files in parallel
/brewcode:text-optimize path1.md, path2.md

# Whole directory
/brewcode:text-optimize -d agents/

What It Does

Converts verbose prose to dense tables (3x more efficient)
Removes filler words and passive language
Restructures lists for clarity
Converts code blocks to inline code when appropriate
Merges redundant sections
Verifies all file references are valid
Reports token savings

Output

Each optimization generates a report showing:

Token reduction percentage
Transformations applied
Any issues found and fixed
Cross-reference verification status

Tips

Start light (-l) on important docs to review changes
Use medium (default) for general documentation
Use deep (-d) for large prompts where tokens matter most
Always review deep mode results before accepting

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

ID	Rule	Notes
C.1	Literal Instruction Following	Claude 4.x does exactly what asked. Precise, explicit instructions required
C.2	Avoid "think" Word	Opus 4.5 sensitive to "think" when extended thinking disabled. Alternatives: "consider", "evaluate", "believe"
C.3	Positive Framing	Tell Claude what to do, not what not to do. ❌ "Do not use markdown" → "Write in flowing prose". More examples: "Don't use mock data" → "Use only real production data"; "Avoid creating new files" → "Apply all fixes to existing files only"; "Never use ellipsis" → "Use only complete sentences and periods"
C.4	Match Prompt Style to Output	Formatting in prompt influences response. Less markdown in prompt → less markdown in output
C.5	Descriptive Over Emphatic Instructions	Opus 4.5/4.6 overtrigger with aggressive language. "Use this tool when..." not "CRITICAL: You MUST..."
C.6	Overengineering Prevention	Opus 4.5 tends to overengineer. Add explicit constraints about minimal complexity
C.7	Avoid ALL-CAPS Emphasis in Claude 4.x	Claude 4.x is more responsive to system prompts than previous versions. Aggressive capitalization ("CRITICAL:", "MUST", "NEVER") causes the model to overapply the rule. Use normal-toned instructions instead. Source: Anthropic Claude 4 best practices
C.8	Prompt Format Influences Output Format	If your prompt is written in prose, Claude responds in prose. If your prompt uses dense markdown, Claude uses dense markdown. Write the format you want to receive. Source: Anthropic Claude 4 best practices

T - Token Efficiency

ID	Rule	Notes
T.1	Tables over Prose	Multi-column data is more token-efficient in tables. Single-column → use bullets instead. Exception: Markdown table syntax (`
T.2	Bullets over Numbered	`-` (1 char) vs `1.` (3 chars). ~5-10% savings. Keep numbers when order matters
T.3	One-liners for Rules	`❌ bad → good` is self-documenting. Complex rules still need explanation
T.4	Inline Code over Blocks	Code blocks add markers + newlines. Inline `code` for <3 lines. Multi-line needs blocks for readability
T.5	Standard Abbreviations	Tables/technical contexts only. Allowed: impl, cfg, args, ret, env, prod, dev, repo, docs. Anti-pattern: Do NOT abbreviate domain terms, variable names, or constraint language in instructions. Shortening "authentication" to "auth" can cause 30+ point accuracy drops on specific tasks (DETAIL Matters, arXiv:2512.02246) because the model uses the statistically dominant meaning of the abbreviation
T.6	Remove Filler Words	Cut: "please note", "it's important", "as mentioned", "basically"
T.7	Comma-separated Inline Lists	`a, b, c` instead of bullet list when items are short, order irrelevant. Use for 3-7 short items
T.8	Arrows for Flow Notation	`A → B → C` instead of prose descriptions of sequences. Dense, scannable. Caveat: each symbol (→,
T.10	Strip Whitespace from Code in Prompts	Code in prompts (C/Java/C#): strip whitespace and indentation before embedding. arXiv:2508.13666 shows 11-22% fewer input tokens (Java: 18.7%, C++: 13.4%, C#: 11.7%) with <1.6% quality impact on Claude and GPT-4o. Python excluded — whitespace is syntactically required. Not for Gemini — significant degradation

S - Structure

ID	Rule	Notes
S.1	XML Tags for Sections	`<rules>...</rules>`, `<examples>...</examples>`. Clear parsing boundaries. Injection safety: XML tags are the only reliable way to prevent `{{VARIABLE}}` template substitution content from being confused with instructions. Without XML tag boundaries, injected user content can look like instructions to the model
S.2	Imperative Form	"Do X" not "You should do X". Removes 2nd person pronouns
S.3	Single Source of Truth	Merge duplicate content. Repetition wastes tokens, causes contradictions. Strategic 2x max OK
S.4	Add Context/Motivation	Providing context helps Claude understand goals. "Text-to-speech will read this, so avoid ellipses"
S.5	Blockquotes for Critical	Use `>` for warnings, critical notes. Visual hierarchy in markdown
S.6	Progressive Disclosure	Show minimum needed, reference details elsewhere. SKILL.md <500 lines
S.7	Consistent Terminology	One term per concept. Avoid synonyms ("config file" vs "configuration document")
S.8	One-Level Reference Depth	All refs link directly from main file. No chaining main→advanced→details

R - Reference Integrity

ID	Rule	Notes
R.1	Verify File Paths	Use Read/Glob to confirm. Broken refs cause tool failures
R.2	Check URLs	Validate accessible URLs. Skip auth-gated URLs
R.3	Linearize Circular Refs	A→B→C→A becomes A→B→C with forward-reference note

P - Perception

ID	Rule	Notes
P.1	Examples Near Rules	Place inline, not in appendix. Proximity improves pattern recognition
P.2	Hierarchy via Headers	Max 3-4 levels deep. Structured documents improve retrieval
P.3	Bold for Keywords	High-signal definitions only. Max 2-3 per 100 lines. Prefer XML tags or headers
P.4	Standard Symbols	→ (flow), + (and), / (or). Dense formats only (tables, compact lists), NOT in prose
P.5	Instruction Order (Anchoring)	Place critical constraints BEFORE options/examples. First-position = strongest anchoring
P.6	Default Over Options	Recommend ONE default, mention exceptions only. Too many options cause decision paralysis

L - LLM Comprehension

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

ID	Rule	Notes
L.1	Critical Info at START or END, Not Middle	"Lost in the Middle" — middle content receives 40-50% less attention. Sandwich pattern (beginning + end) outperforms middle-only placement. Source: TACL 2024
L.2	Documents First, Query Last	Long-context ordering: documents/context first, then query/instructions last. Counterintuitive: putting the query at the END (not beginning) improves quality by up to 30% on multi-document inputs. Source: Anthropic official
L.3	Explicitly Request Conciseness	Conciseness is NOT Claude's default — always state "Skip preamble" explicitly. Without explicit instruction, responses are 3-5x longer than needed. Source: Anthropic docs
L.4	Quote-First Grounding	Instruct to extract relevant quotes before answering. Reduces hallucination by forcing the model to locate specific content first. Pattern: "Find relevant quotes → place in `<quotes>` → answer based only on those quotes." Source: Anthropic cookbook
L.5	Add WHY to Instructions	Claude generalizes the reason to edge cases. "Never use ellipsis because TTS won't pronounce it" → Claude also avoids other TTS-incompatible symbols. "Never use ellipsis" alone gives no generalization. Source: Anthropic Claude 4 best practices
L.6	Reiterate Critical Constraint at END	Position effect amplifies with context length — constraints closest to the end have highest compliance rate. Source: Brex Prompt Engineering Guide + Anthropic
L.7	Prompt Repetition for Non-Reasoning Models	Repeat the entire prompt once. Google Research (arXiv:2512.14982): wins 47/70 benchmark-model combinations with 0 losses. Extreme case: 21% to 97% accuracy. Causal LMs benefit because the second pass has full first-pass context. Only for non-reasoning models — reasoning models already repeat internally

Rules NOT Recommended

Avoid	Reality
Remove all emojis	Status emojis are dense, meaningful
Always use tables	Single-column data denser as bullets
Compress everything	Domain terms need full form first time
Remove all examples	Claude generalizes better with examples (P.1)
Non-standard abbreviations	Stick to T.5 allowed list
Overload single prompts	Multiple tasks in one prompt divide attention → hallucination
Over-focus on wording	Structure and format matter more than specific word choice

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.