MD Compressor

Shrink Markdown to the smallest workable form for agents. Never edit originals — duplicate first, compress the copy only.

End Goal

The machine must still know what to do after compression — at every level, including extreme.

• Always preserve: actionable requirements, constraints, steps, decisions, numbers, commands, paths (per level rules), and skill triggers (name, usable description).
• May be reduced as levels increase: tone, encouragement, examples, edge-case color, and duplicate explanations — some context and “feel” can be lost; that is an expected tradeoff.
• Never acceptable: an agent reading only the compressed copy cannot determine what action to take, what order to do it in, or what must not be violated.
• If executability is at risk: keep the longer form, revert that fragment, or step down one compression level for that line or file.

Heavier compression = fewer tokens, not a different skill. When reporting results, note that heavy / extreme copies may omit nuance but must remain agent-executable.

Non-Negotiable Safety

1. Duplicate before compress — copy the target skill folder or MD file; write all compressed output into the copy.
2. Source stays intact — do not save compression edits to the original path.
3. Confirm target — state source path, copy path, and compression level before editing.

Core Rules

1. Facts are immutable — requirements, constraints, numbers, paths, commands, and decisions stay exact.
2. Level is explicit — default light unless the user asks for medium, heavy, or extreme.
3. Skill = whole package — compress SKILL.md and every .md under references/ in the duplicated folder; copy non-text assets unchanged.
4. Text only — compress Markdown and plain text; skip binaries, images, and non-text assets.
5. No semantic drift — if shortening risks changing meaning or what the agent should do, keep the longer form.
6. Agent-executable over minimal — prefer tokens saved only when the compressed copy still answers: what to do, in what order, under what constraints.
7. Valid skill output — preserve YAML frontmatter keys (name, description); keep description trigger-clear even when shortened.

Compression Levels

Level definitions: references/compression-levels.md.

Workflow

1. Intake — single file, folder, or skill package; pick light, medium, heavy, or extreme.
2. Duplicate — references/safe-copy-workflow.md.
3. Scope files — skill packages: references/skill-package-handling.md.
4. Compress — per-file pass: references/compression-workflow.md.
5. QA — references/quality-checklist.md.

Output Contract

• First line of each compressed file body: Compression: light|medium|heavy|extreme (after frontmatter when present).
• light / medium / heavy: output remains valid Markdown (heavy may be dense but parseable).
• extreme: whitespace-stripped; may be a few very thin lines — facts and literals intact; agent-parseable over human-readable.
• extreme (skill packages): may rename references/*.md to short names and rewrite all internal links; see references/extreme-path-shortening.md.
• Preserve heading hierarchy unless flattening is lossless (light/medium); heavy/extreme may collapse when intent is unchanged.
• Keep external URLs, CLI paths, and fenced code literals intact; internal ref paths may shorten at extreme only.
• Add a one-line abbreviation legend at top only when heavy/extreme uses non-map shorthand (omit legend at extreme if it costs more tokens than it saves).

Reference Index

• Duplicate-first safety and naming: references/safe-copy-workflow.md
• Light / medium / heavy / extreme behavior: references/compression-levels.md
• Skill folder scope and frontmatter: references/skill-package-handling.md
• Per-file compression order: references/compression-workflow.md
• Canonical abbreviations: references/abbreviation-map.md
• Symbol and punctuation by level: references/symbol-and-punctuation-policy.md
• Extreme path shortening: references/extreme-path-shortening.md
• Final QA: references/quality-checklist.md

When To Use This Skill

• Shrinking verbose Markdown or full skill packages for lower context cost.
• Testing how small a skill can get while staying agent-usable.
• Preparing dense handoff or archive copies without touching source skills.