skill-compact

Shrink the token footprint of Claude Code SKILL.md files without breaking the skill. It separates the two costs, attacks each honestly, and refuses any change that would drop an activation trigger.

The two footprints

• Description (frontmatter): loads into every session for every installed skill. Always-on tax. Small per skill, large in aggregate.
• Body + references: load only when the skill is invoked. Where the big bytes are.

Measured on one real library of ~600 skills: descriptions cost ~54k tokens every session; 276 skills carry a description over 350 characters.

What it does

The fidelity guard (why it will not break your skills)

check extracts the original description's trigger tokens - quoted phrases, /slash-commands, kebab and CamelCase identifiers, acronyms - and refuses any shorter description that loses one. This is not a heuristic hope; it is a hard gate.

It was validated adversarially. Compacting prose-y descriptions is safe (an OAuth-review skill went 373 to 330 chars, verified no lost triggers). Compacting a trigger-dense skill is not: a bug-bounty skill with a 1,405-char description enumerating dozens of vuln classes and non-English keywords cannot be shortened to 350 chars without dropping triggers, and the tool blocks that rewrite. Use refs and body on those instead.

Install

git clone https://github.com/<you>/skill-compact.git
python3 skill-compact/scripts/analyze.py --top 20

Usage

# 1. find the worst offenders
python3 scripts/analyze.py --top 20

# 2. always-on: propose a shorter description, prove it is safe, then apply
python3 scripts/compact.py check   <skill> --desc "<shorter, keeps every trigger>"
python3 scripts/compact.py set-desc <skill> --desc "<shorter>"

# 3. on-invoke: lossless body minify, and move long code out to references/
python3 scripts/compact.py body <skill> --apply
python3 scripts/compact.py refs <skill> --min-lines 30 --apply

Every --apply writes a timestamped .orig backup and re-reads the file to confirm the change held; refs restores from backup if any block went missing.

Design notes

Two independent designs (a deterministic invariant-checked minimizer and an LLM-semantic description compressor with a deterministic validator) converged on the same split: automate what is provably safe, gate description rewrites behind trigger preservation, and never silently cut content. The model proposes prose; the tool guarantees no trigger is lost.

Tests

pytest -q tests/

License

MIT