brewcode:text-optimize
Scannednpx machina-cli add skill kochetkov-ma/claude-brewcode/text-optimize --openclawFiles (1)
SKILL.md
6.5 KB
Text & File Optimizer
Step 0: Load Rules
REQUIRED: Read
references/rules-review.mdbefore 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) |
Source
git clone https://github.com/kochetkov-ma/claude-brewcode/blob/main/brewcode/skills/text-optimize/SKILL.mdView on GitHub Overview
Optimizes text and documents for LLM token efficiency, helping you prune prompts and verbose content. It supports light, medium, and deep modes to clean up structure and aggressively compress content while preserving meaning. Use it to shrink token usage while preserving essential information.
How This Skill Works
The tool loads target files or folders and applies mode-specific transformations aligned with the Rule IDs (C, T, S, R, P). Light mode cleans structure and flow without touching layout; Medium provides balanced restructuring; Deep aggressively rephrases and compresses content. Users should review diffs before applying changes to ensure accuracy and style alignment.
When to Use It
- Optimizing prompts for LLM token budget and faster responses.
- Reducing tokens in existing docs or READMEs without sacrificing meaning.
- Compressing verbose content into concise, actionable guidance.
- Preparing files for ingestion by multi-step LLM workflows (agents/skills).
- Reformatting structured content (tables, bullets) to meet token-efficient writing rules.
Quick Start
- Step 1: Run the skill on your target file(s) or directory, e.g., /brewcode:text-optimize path1.md
- Step 2: Choose a mode with -l, -d, or omit for Medium; review the proposed diffs.
- Step 3: Apply the changes and re-run if needed to validate token savings and content integrity.
Best Practices
- Read references/rules-review.md before optimizing to follow established guidelines.
- Choose mode carefully (-l, default, -d) to fit your optimization goal.
- Favor table/bullet structures and inline code to maximize token savings (T.1, T.2, T.3, T.4, T.7).
- Review diffs in Deep mode and verify that critical meaning and tone are preserved.
- Test prompts after optimization to ensure behavior and intent remain correct.
Example Use Cases
- Compress a long prompt to minimize token usage for a Claude-style API call.
- Trim a product README to core steps and essential usage examples.
- Condense API docs for quick runtime integration without losing required details.
- Streamline a training guide into concise prerequisites and steps.
- Clean up a skill's SKILL.md to improve parsing, consistency, and reference integrity.
Frequently Asked Questions
Add this skill to your agents
