Compress Skill
Overview
Compression is a structured reduction — not indiscriminate cutting. Every compression must preserve behavioral fidelity: if a fresh agent reads the compressed skill, they must produce the same behavior as with the original.
Core principle: Compress prose, never compress rules. Signal tables, validation checks, rationalization tables, and red flags are behavioral content. Exposition, examples, commentary, and duplicate explanations are compression targets.
Core Pattern
Compression Categories
Every compression operation belongs to one of these categories. Enumerate opportunities first, then categorize:
| Category |
Signal |
Operation |
Example |
| Merge |
Two sections say the same thing in different words |
Combine into one section; keep the clearer version |
Overview says "only for docs/planning/research" and When To Use repeats it verbatim |
| Fold |
Adjacent sections share a parent concept; the smaller one is elaboration, not a distinct topic |
Inline the smaller section into the larger one |
"Ladder Is Recursive" (9 lines of philosophy) → inlined as 3 lines in Inference Ladder |
| Trim |
Prose is verbose but instruction is simple; filler words surround a command |
Cut filler; keep the instruction, remove the commentary |
"The next thing you should do after this is to enumerate the cases" → "Enumerate cases" |
| Prune |
Multiple checks test the same underlying property |
Keep the strongest check; drop redundant ones |
"Did my concept stay stable?" and "Did the concept drift?" — same test, keep one |
| Unify |
Multiple cases teach the same lesson — good examples, bad examples, rationalizations, red flags |
Keep the canonical case that captures the generalization; drop variants |
Three mistake rows all restating "treated example marker as closure" → keep the clearest one |
Compression Workflow
- Enumerate opportunities. Read the skill end-to-end. List every specific compression you see — don't categorize yet. "Merging paragraph X with Y" is an opportunity.
- Categorize. Assign each opportunity to Merge, Fold, Trim, Prune, or Unify. If an opportunity doesn't fit cleanly, reconsider — you might be about to cut behavioral content.
- Sort by safety. Trims are safest (cut commentary). Merges are safe (keep behavioral). Folds need care (preserve both messages). Unifies need judgment (same lesson?). Prunes risk data loss. Do trims and merges first; re-read after folds, unifies, and prunes.
- Apply in order. Execute trims → merges → folds → unifies → prunes. This avoids compressing something that later operations would eliminate anyway.
- Validate. Run the acid test on the result.
The Acid Test
For every compression, ask: "If I gave this compressed skill to a fresh agent, would they produce the same behavior as with the original?"
- No → revert the compression
- Yes, but only because surrounding context compensates → the skill is fragile; keep the original
- Yes, the instruction is intact → proceed
Safety Rules
Never compress:
| Content Type |
Reason |
| Signal tables (Closure Signals, Openness Signals, Confidence Gates) |
These encode behavioral rules in compact form. Removing rows removes rules. |
| Rationalization Prevention tables |
Each row counters a specific rationalization. Remove one, the loophole reopens. |
| Validation checklists |
Multiple checks test different failure modes. Pruning is possible only when checks genuinely overlap. |
| Red Flags lists |
Each flag is a self-check trigger. |
| Conflicting Signals / resolution hierarchies |
These are decision trees, not prose. |
| Adding or expanding content |
Compression = reduction. Replacing short text with long text, adding missing rules mid-compression, or "improving" instead of shortening is not compression. Note underspecification; fix separately. |
Safe to compress:
- Duplicate sentences across sections (merge)
- Verbose framing around simple instructions (trim)
- Examples that are longer than the pattern they illustrate (trim)
- "Philosophical" paragraphs that don't encode a behavioral rule (fold or cut)
- Commentary: "This is important because..." — unless the "because" encodes a rule not stated elsewhere
Quick Reference
| If you see |
Do this |
| Same sentence in two sections |
Merge — keep one copy |
| Small section elaborating a parent concept |
Fold — inline it |
| "The next thing you should do is..." |
Trim — just say what to do |
| Two validation checks asking the same thing |
Prune — keep the stronger one |
| Multiple cases teaching the same lesson |
Unify — keep canonical, drop variants |
| A code example longer than the rule it teaches |
Trim — single-line example |
| Any behavioral table row |
Never touch unless genuinely redundant |
Do NOT Compress
- Skills under 200 words — they're already at target
- Skills where every section teaches something distinct
- When you can't distinguish behavioral content from exposition (read more carefully)
Common Mistakes
| Mistake |
Fix |
| Cutting a "redundant" sentence that actually encodes a rule not stated elsewhere |
Before cutting, verify: is this rule encoded anywhere else in the skill? If not, keep it. |
| Merging sections that serve different purposes |
"When to Use" and "Triggers" may overlap but answer different questions. Check audience intent before merging. |
| Pruning validation checks because they "feel similar" |
Two checks that feel similar may catch different failure modes. Only prune when the underlying test is identical. |
| Compressing signal tables |
These are data, not prose. Never compress. |
| Over-applying to a skill that doesn't need it |
If the skill is already ≤ 200 words, compression causes harm — you'll cut behavioral content to meet an imaginary target. |
1---2name: skill-compression3description: Use when skill documents are too long, bloated with repetitive prose, or the user asks to compress/shorten/tighten/trim a SKILL.md. Also use when a skill has overlapping sections, duplicate explanations, or verbose examples that inflate word count without adding behavioral content.4license: CC-BY-SA-4.05---67# Compress Skill89## Overview1011Compression is a structured reduction — not indiscriminate cutting. Every compression must preserve behavioral fidelity: if a fresh agent reads the compressed skill, they must produce the same behavior as with the original.1213**Core principle:** Compress prose, never compress rules. Signal tables, validation checks, rationalization tables, and red flags are behavioral content. Exposition, examples, commentary, and duplicate explanations are compression targets.1415## Core Pattern1617### Compression Categories1819Every compression operation belongs to one of these categories. Enumerate opportunities first, then categorize:2021| Category | Signal | Operation | Example |22|---|---|---|---|23| **Merge** | Two sections say the same thing in different words | Combine into one section; keep the clearer version | Overview says "only for docs/planning/research" and When To Use repeats it verbatim |24| **Fold** | Adjacent sections share a parent concept; the smaller one is elaboration, not a distinct topic | Inline the smaller section into the larger one | "Ladder Is Recursive" (9 lines of philosophy) → inlined as 3 lines in Inference Ladder |25| **Trim** | Prose is verbose but instruction is simple; filler words surround a command | Cut filler; keep the instruction, remove the commentary | "The next thing you should do after this is to enumerate the cases" → "Enumerate cases" |26| **Prune** | Multiple checks test the same underlying property | Keep the strongest check; drop redundant ones | "Did my concept stay stable?" and "Did the concept drift?" — same test, keep one |27| **Unify** | Multiple cases teach the same lesson — good examples, bad examples, rationalizations, red flags | Keep the canonical case that captures the generalization; drop variants | Three mistake rows all restating "treated example marker as closure" → keep the clearest one |2829### Compression Workflow30311. **Enumerate opportunities.** Read the skill end-to-end. List every specific compression you see — don't categorize yet. "Merging paragraph X with Y" is an opportunity.322. **Categorize.** Assign each opportunity to Merge, Fold, Trim, Prune, or Unify. If an opportunity doesn't fit cleanly, reconsider — you might be about to cut behavioral content.333. **Sort by safety.** Trims are safest (cut commentary). Merges are safe (keep behavioral). Folds need care (preserve both messages). Unifies need judgment (same lesson?). Prunes risk data loss. Do trims and merges first; re-read after folds, unifies, and prunes.344. **Apply in order.** Execute trims → merges → folds → unifies → prunes. This avoids compressing something that later operations would eliminate anyway.355. **Validate.** Run the acid test on the result.3637### The Acid Test3839For every compression, ask: **"If I gave this compressed skill to a fresh agent, would they produce the same behavior as with the original?"**4041- No → revert the compression42- Yes, but only because surrounding context compensates → the skill is fragile; keep the original43- Yes, the instruction is intact → proceed4445### Safety Rules4647**Never compress:**4849| Content Type | Reason |50|---|---|51| Signal tables (Closure Signals, Openness Signals, Confidence Gates) | These encode behavioral rules in compact form. Removing rows removes rules. |52| Rationalization Prevention tables | Each row counters a specific rationalization. Remove one, the loophole reopens. |53| Validation checklists | Multiple checks test different failure modes. Pruning is possible only when checks genuinely overlap. |54| Red Flags lists | Each flag is a self-check trigger. |55| Conflicting Signals / resolution hierarchies | These are decision trees, not prose. |56| Adding or expanding content | Compression = reduction. Replacing short text with long text, adding missing rules mid-compression, or "improving" instead of shortening is not compression. Note underspecification; fix separately. |5758**Safe to compress:**5960- Duplicate sentences across sections (merge)61- Verbose framing around simple instructions (trim)62- Examples that are longer than the pattern they illustrate (trim)63- "Philosophical" paragraphs that don't encode a behavioral rule (fold or cut)64- Commentary: "This is important because..." — unless the "because" encodes a rule not stated elsewhere6566## Quick Reference6768| If you see | Do this |69|---|---|70| Same sentence in two sections | **Merge** — keep one copy |71| Small section elaborating a parent concept | **Fold** — inline it |72| "The next thing you should do is..." | **Trim** — just say what to do |73| Two validation checks asking the same thing | **Prune** — keep the stronger one |74| Multiple cases teaching the same lesson | **Unify** — keep canonical, drop variants |75| A code example longer than the rule it teaches | **Trim** — single-line example |76| Any behavioral table row | **Never touch** unless genuinely redundant |7778## Do NOT Compress7980- Skills under 200 words — they're already at target81- Skills where every section teaches something distinct82- When you can't distinguish behavioral content from exposition (read more carefully)8384## Common Mistakes8586| Mistake | Fix |87|---|---|88| Cutting a "redundant" sentence that actually encodes a rule not stated elsewhere | Before cutting, verify: is this rule encoded anywhere else in the skill? If not, keep it. |89| Merging sections that serve different purposes | "When to Use" and "Triggers" may overlap but answer different questions. Check audience intent before merging. |90| Pruning validation checks because they "feel similar" | Two checks that feel similar may catch different failure modes. Only prune when the underlying test is identical. |91| Compressing signal tables | These are data, not prose. Never compress. |92| Over-applying to a skill that doesn't need it | If the skill is already ≤ 200 words, compression causes harm — you'll cut behavioral content to meet an imaginary target. |
Arcadi4