Skill Compact — Development skill for Claude Code

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

Command	Cost targeted	Guarantee
analyze	both	pure measurement, mutates nothing
check / set-desc	always-on	rejects a rewrite that drops any trigger token
body	on-invoke	lossless: strip HTML comments, collapse blank runs, trailing ws
refs	on-invoke	extract long code blocks to references/, leave a pointer

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//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 desc