---
name: compress-skill
description: 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.
license: CC-BY-SA-4.0
---

# 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

1. **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.
2. **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.
3. **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.
4. **Apply in order.** Execute trims → merges → folds → unifies → prunes. This avoids compressing something that later operations would eliminate anyway.
5. **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. |