Skill Zipper

SKILL.md

---
name: skill-zipper
description: >
  COMPRESSES an existing skill LOSSLESSLY for token efficiency, reliability, and
  trigger accuracy. Use when a skill is too long, needs token reduction or
  splitting, has vague rules, or fails to trigger: "$skill-zipper". WITHOUT
  losing content; not build (engineer), audit (guidance), or scaffold
  (skill-creator).
---

# skill-zipper

Restructure an existing Claude Code skill without losing content. The five
operations are **Compress**, **Encapsulate**, **Enrich**, **Harden**, and
**Retrigger**; analyze which apply, then propose a plan.

A comprehensive pass refines **every part** — the `description`, SKILL.md, and
every `rules/`/`references/` file — **and the load architecture** (always-loaded
vs on-demand). The `description` is highest-leverage: it sits in the skills index
on EVERY turn and Claude Code **truncates it past 1024 chars**. `measure_tokens.py`
sizes it and emits Architecture flags — never ship what the flags call BAD.

Before reasoning about any of these, **read `rules/progressive-disclosure-model.md`**
to internalize what "always-loaded" vs "on-demand" means and the role of
each directory (`rules/`, `references/`, `assets/`, `scripts/`). Without
that model the token-cost reasoning below is meaningless.

Direct user mode: always show a plan first and wait for "go" before writing.
Pipeline mode: if invoked by **skill-conductor** as **Stage Z**, the user's
end-to-end pipeline request is the approval. Use only conservative lossless
writes, then report token impact and diff evidence.

---

## Step 1: Read the skill (every part)

Ask for the skill directory path (or accept it if already provided).

Run `scripts/measure_tokens.py <skill_dir>` **first** and capture: the
**description** char/token size, the always-loaded vs on-demand split, and the
**Architecture flags** block (description over-limit, always-loaded budget,
oversized parts, orphans). The flags tell you which parts need work.

Then read, to refine **every part** (not just SKILL.md):
- `SKILL.md` — required (stop if missing), **including its frontmatter `description`**.
- All `rules/*.md` and `references/*.md` bodies — candidates for Compress / merge /
  dedup; a `references/` file may duplicate SKILL.md content.
- `scripts/`, `assets/`, `schemas/` — note what exists; read a body only when a
  flag (oversized / orphan) or the analysis points at it.

Print a one-line inventory + the description size + always-loaded/on-demand totals
+ any Architecture flags.

## Step 2: Analyze each dimension

Load `rules/diagnosis-rubric.md` for smoke-test thresholds and the
priority matrix. Then load `rules/operation-analysis.md` for the
per-operation signal lists.

Walk through each of the 5 operations (Compress / Encapsulate / Enrich /
Harden / Retrigger) and capture candidates per the rules file.

## Step 3: Present the plan

Load `rules/plan-template.md`. Render the plan using the exact format
in that file. End with the confirmation prompt and wait for "go".

## Step 4: Write the files

Once the user approves, load `rules/write-procedure.md`. Follow the
3-step write order (snapshot → new files → SKILL.md). If the user
requested a dry-run, use the dry-run procedure in that same file.

## Step 5: Verify

Load `rules/verification-checklist.md`. Run both scripts (lossless
diff + token impact), classify any LOST / REWRITTEN lines, and print the done
summary.

---

## Losslessness rules

The restructure is lossless when removed SKILL.md lines appear elsewhere
verbatim, or are explicitly classified as Harden/Retrigger rewrites or Enrich
extractions; every new rules file is referenced from SKILL.md; rewrites preserve
intent; and `diff_lossless.py` exits 0 or all LOST / REWRITTEN lines are
classified.

If the user asks you to delete a section with no destination, propose a
destination first. If no destination makes sense, suggest keeping the
section in SKILL.md even if it's long — losslessness trumps brevity.

---

## Modules

| File | When to load |
|------|--------------|
| `rules/progressive-disclosure-model.md` | Always — sets the mental model for what "always-loaded" vs "on-demand" means, and the role of each directory. Without this you can't reason about token cost. |
| `rules/diagnosis-rubric.md` | At Step 2, before analyzing any operation. Smoke-test thresholds, per-operation signal lists, priority matrix. |
| `rules/operation-analysis.md` | At Step 2, alongside the diagnosis rubric. Per-operation candidate criteria and cross-references to pattern libraries. |
| `rules/encapsulation-patterns.md` | When evaluating an Encapsulate candidate. Catalogue of good patterns (P1-P5) and anti-patterns (A1-A4). |
| `rules/hardening-patterns.md` | When evaluating a Harden candidate. Library of vague→precise rewrite shapes (H1-H10). |
| `rules/description-quality.md` | When applying the Retrigger operation, or any time the user mentions trigger accuracy. |
| `rules/plan-template.md` | At Step 3, before printing the plan. Exact format and confirmation prompt. |
| `rules/write-procedure.md` | At Step 4, before writing any file. Write order, dry-run procedure, anti-patterns. |
| `rules/verification-checklist.md` | At Step 5, after writing. Two-layer verification (script + human) and the done summary format. |

## Scripts

| File | Usage |
|------|-------|
| `scripts/measure_tokens.py` | `python3 scripts/measure_tokens.py <skill_dir>` — line + token counts grouped by load discipline. Supports `--diff <before> <after>`. |
| `scripts/diff_lossless.py` | `python3 scripts/diff_lossless.py <before> <after>` — verify a restructure preserved every line. Exit 0 = verbatim lossless, exit 1 = LOST/REWRITTEN needs classification. |

## Assets

| File | Usage |
|------|-------|
| `assets/rules-template.md` | Skeleton for a new rules file. Copy and fill in placeholders; strip HTML comments before committing. |
| `assets/skill-md-skeleton.md` | Skeleton for a new SKILL.md. Use when restructuring requires a full SKILL.md rewrite. |