skill-zipper
Decision rule: an item survives only if the agent cannot derive it from the command itself, the surrounding code, a referenced file, or general knowledge.
Delete
| Target |
Test |
| Abstract or ambiguous wording |
Could two agents act differently on it? → replace with a decidable condition |
| Explanation of general knowledge |
Would a competent agent already know this? |
| Rules not specific to this skill |
Would it apply unchanged to any other skill? |
| Human-facing labels, bold, signposts |
Does any cross-reference point at the name? If not, delete |
| Comments restating what a command does |
Is it derivable from the command or from line order? |
| Standard commands with no second form |
git commit, git tag, firebase deploy, npm run lint — demote to a constraint sentence |
| Duplicated rationale across sections |
Keep one canonical statement, cross-reference the rest |
Keep
- Proper nouns, exact flags that change behavior (
--staged, --yes, --source=. --push), literal argument values ('(default)')
- Anything this skill invented: its own schemas, its own
resources/* scripts and their CLI contract, its output format
- Comments answering when to run, what must hold afterward, what is forbidden
- Cross-reference anchors and normative markers (
hard rule, no override) — these set a rule's override class
- Heading hierarchy and paragraph structure
Form
- Prefer JSON / Schema / yml / tables / example code over prose
- Example code need not be runnable: one key line plus comments showing the rest
- Code block = must be copied literally. Prose = constraint. Never blur the two
- Lead a rule with its trigger condition, not its topic name
Baseline
Establish before any edit. Prefer git — it needs no cleanup and cannot be clobbered by a stray write.
| Target file state |
Baseline |
Rollback |
| tracked, clean |
git show HEAD:./<path> |
git checkout -- <path> |
| tracked, dirty |
ask first, see below |
— |
| untracked, or no repo |
cp SKILL.md SKILL.old.md, never modify it again |
the copy |
Uncommitted changes in the target → ask which, never choose silently:
- commit them now → baseline is that commit
git switch -c zip/<skill-name> and commit there → the working branch stays clean, the diff is reviewable as a branch- leave them → fall back to the
SKILL.old.md copy, and say that the baseline now includes unreviewed work
Procedure
- Enumerate every rule in the baseline as a numbered checklist before editing
- Run 10 passes, one focus each:
| # |
Focus |
| 1 |
ambiguity → decidable conditions |
| 2 |
prose → tables and schemas |
| 3 |
drop what references/* already covers |
| 4 |
restructure rules to lead with their trigger |
| 5 |
replace narrated flows with the skill's own schema/examples |
| 6 |
escalation and branching → decision ladders |
| 7 |
required outputs → fill-in templates |
| 8 |
cross-section deduplication |
| 9 |
sentence compression, imperative voice |
| 10 |
proofread + parity check |
- Parity check: every checklist item from step 1 must still be findable. Missing → restore it
- Measure both sides whitespace-normalized — formatters pad table cells, so raw byte counts lie.
git show needs the path repo-relative, hence the ./:git show HEAD:./skills/x/SKILL.md | tr -s ' ' ' ' | wc -c # baseline
tr -s ' ' ' ' < skills/x/SKILL.md | wc -c # result
- Gate: smaller and at parity. Either one fails → report and stop, original untouched
- Report, then ask the user to confirm. Point them at
git diff rather than pasting the diff into chat. Write the change only on approval; declined → git checkout -- <path>, or restore from the copy
- Confirmed → delete
SKILL.old.md if one was made. A git baseline leaves nothing to clean up
A format-on-save markdown formatter also eats the space before inline code and rewrites tables between edits — re-read the file before edits that depend on surrounding lines.
Report
- Per-pass table: focus → what changed, or "no change"
- Parity: baseline rule count vs found; anything deliberately dropped, and why
- Size: baseline vs result, whitespace-normalized, with the percentage
- Say plainly when passes stop reducing — structural gain ≠ token gain
1---2name: skill-zipper3description: Compresses a SKILL.md or agent instruction file to the minimum an agent needs — strips prose, human-facing labels, restating comments, and demonstrations of standard commands — then proves functional parity before applying. Use when asked to shorten, tighten, simplify, condense, or cut the token cost of a skill.4---56# skill-zipper78Decision rule: an item survives only if the agent cannot derive it from the command itself, the surrounding code, a referenced file, or general knowledge.910## Delete1112| Target | Test |13| --- | --- |14| Abstract or ambiguous wording | Could two agents act differently on it? → replace with a decidable condition |15| Explanation of general knowledge | Would a competent agent already know this? |16| Rules not specific to this skill | Would it apply unchanged to any other skill? |17| Human-facing labels, bold, signposts | Does any cross-reference point at the name? If not, delete |18| Comments restating what a command does | Is it derivable from the command or from line order? |19| Standard commands with no second form | `git commit`, `git tag`, `firebase deploy`, `npm run lint` — demote to a constraint sentence |20| Duplicated rationale across sections | Keep one canonical statement, cross-reference the rest |2122## Keep2324- Proper nouns, exact flags that change behavior (`--staged`, `--yes`, `--source=. --push`), literal argument values (`'(default)'`)25- Anything this skill invented: its own schemas, its own `resources/*` scripts and their CLI contract, its output format26- Comments answering *when to run*, *what must hold afterward*, *what is forbidden*27- Cross-reference anchors and normative markers (`hard rule, no override`) — these set a rule's override class28- Heading hierarchy and paragraph structure2930## Form3132- Prefer JSON / Schema / yml / tables / example code over prose33- Example code need not be runnable: one key line plus comments showing the rest34- Code block = must be copied literally. Prose = constraint. Never blur the two35- Lead a rule with its trigger condition, not its topic name3637## Baseline3839Establish before any edit. Prefer git — it needs no cleanup and cannot be clobbered by a stray write.4041| Target file state | Baseline | Rollback |42| --- | --- | --- |43| tracked, clean | `git show HEAD:./<path>` | `git checkout -- <path>` |44| tracked, dirty | ask first, see below | — |45| untracked, or no repo | `cp SKILL.md SKILL.old.md`, never modify it again | the copy |4647Uncommitted changes in the target → ask which, never choose silently:4849- commit them now → baseline is that commit50- `git switch -c zip/<skill-name>` and commit there → the working branch stays clean, the diff is reviewable as a branch51- leave them → fall back to the `SKILL.old.md` copy, and say that the baseline now includes unreviewed work5253## Procedure54551. Enumerate every rule in the baseline as a numbered checklist before editing562. Run 10 passes, one focus each:5758| # | Focus |59| --- | --- |60| 1 | ambiguity → decidable conditions |61| 2 | prose → tables and schemas |62| 3 | drop what `references/*` already covers |63| 4 | restructure rules to lead with their trigger |64| 5 | replace narrated flows with the skill's own schema/examples |65| 6 | escalation and branching → decision ladders |66| 7 | required outputs → fill-in templates |67| 8 | cross-section deduplication |68| 9 | sentence compression, imperative voice |69| 10 | proofread + parity check |70713. Parity check: every checklist item from step 1 must still be findable. Missing → restore it724. Measure both sides whitespace-normalized — formatters pad table cells, so raw byte counts lie. `git show` needs the path repo-relative, hence the `./`:73 ```bash74 git show HEAD:./skills/x/SKILL.md | tr -s ' ' ' ' | wc -c # baseline75 tr -s ' ' ' ' < skills/x/SKILL.md | wc -c # result76 ```775. Gate: smaller **and** at parity. Either one fails → report and stop, original untouched786. Report, then ask the user to confirm. Point them at `git diff` rather than pasting the diff into chat. Write the change only on approval; declined → `git checkout -- <path>`, or restore from the copy797. Confirmed → delete `SKILL.old.md` if one was made. A git baseline leaves nothing to clean up8081A format-on-save markdown formatter also eats the space before inline code and rewrites tables between edits — re-read the file before edits that depend on surrounding lines.8283## Report8485- Per-pass table: focus → what changed, or "no change"86- Parity: baseline rule count vs found; anything deliberately dropped, and why87- Size: baseline vs result, whitespace-normalized, with the percentage88- Say plainly when passes stop reducing — structural gain ≠ token gain
drgarbage