compress-skills

Files (1)

• SKILL.md

SKILL.md (first lines)

# Compress Skills

Shrink the tokens a skill costs when loaded, with zero loss of value: every trigger, step, guardrail, tool name, threshold, and output spec survives. This is **compression, not redesign** — never add features or change behavior.

## How skills spend context (optimize the right layer)

- **Frontmatter `description`** — loads into *every* session; drives auto-invocation. Keep all trigger phrases/keywords/scenarios. You may tighten wording, never drop a trigger. Editing it is high-risk; touch it last and least.
- **SKILL.md body** — loads on every invocation. **Primary target.**
- **Reference files** (`references/*.md`, `REFERENCE.md`, recipes) — load only when opened. Move occasionally-needed detail here to shrink the mandatory body.

## Process

1. **Scope.** List the target skills. `wc -c` each file for a baseline. Skip files gitignored as private unless the user names them. Skip already-minimal files (< ~1 KB with no redundancy) — report "already minimal" rather than risk value.
2. **Optimize.** One skill → do it inline with the rulebook below. Many → fan out one subagent per skill (or small group), run in parallel.
3. **Verify** every result (checklist below) — centrally, don't trust a subagent's self-report.
4. **Report** before/after bytes and % per file and total, what was cut, and any risk.

### Optimization rulebook (also the subagent brief)

1. Cut redundancy, repetition, restatement, filler. Same instruction/guardrail twice → keep once.
2. Collapse near-duplicate examples to the single most instructive one. Long worked examples are the biggest waste — trim hard, keep one.
3. Prose → tight imperative bullets/steps. Drop hedging and obvious explanation.
4. PRESERVE EVERY actionable step, guardrail, tool/function name, exact command/flag/syntax, code/CSS/design-token value, ordering constraint, output-format spec, edge case, and threshold/number. When in doubt, keep it.
5. Move genuinely-optional detail from the body into a reference file the skill points to — never fragment tightly-coupled instructions.
6. Keep all frontmatter keys valid (`---` delimited) and every trigger phrase in `description`. Keep markdown well-formed. Match the author's voice.
7. No new features, no behavior change, no restyling beyond compression.

### Fan-out for a suite

Give each subagent: the rulebook above, the "how skills spend context" note, its assigned absolute file paths, and the report format. Run them in parallel. Then aggregate and verify centrally.

## Verify (every skill, deterministically)

- Frontmatter still opens/closes with `---` and has `name` + `description`.
- `git diff` the `description:` lines — expect byte-identical except intentional, trigger-preserving rewordings.
- `grep` the load-bearing tokens (tool names, enums, thresholds, output-section headers, commands) — all still present.
- Re-`wc -c`; confirm a real drop.
- Read through any file cut > ~30% to confirm no capability was dropped.

## Guardrails

- **Triggers are sacred.** A dropped trigger phrase silently breaks discovery. Diff descriptions to prove they're intact.
- **Don't touch protected literals** — code, HogQL/SQL, CSS/color/radius/shader values, exact commands/flags/paths stay byte-for-byte.
- **Leave already-tight files alone.** Trimming a 500 B skill risks value for no real saving.
- **Respect `.gitignore`.** Private, local-only skills stay untouched unless the user names them.
- **Report honestly.** Give per-file numbers, flag anything uncertain, and don't inflate the reduction.

## Report format

Per file: `<path>: <before>B → <after>B (−XX%)`, a TOTAL line, 3–6 bullets on what was cut/moved and why value survives, and a RISK line. A shareable summary (e.g. display.dev) is optional — only when asked.

From therapys/dotagents, MIT.

More from therapys/dotagents