# Skill Shortener

Refactor a too-long SKILL.md by progressive disclosure: measure token cost, classify...

- Repository: https://github.com/luongnv89/asm (962 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add luongnv89/asm --skill skill-shortener -g -a claude-code -y`
Codex: `npx skills add luongnv89/asm --skill skill-shortener -g -a codex -y`
Cursor: `npx skills add luongnv89/asm --skill skill-shortener -g -a cursor -y`
Gemini CLI: `npx skills add luongnv89/asm --skill skill-shortener -g -a gemini-cli -y`

## Description

Refactor a too-long SKILL.md by progressive disclosure: measure token cost, classify every section KEEP/CUT/MOVE, shorten the body into references/ and scripts/, verify nothing was lost. Don't use for authoring new skills, eval retrofits, or prose.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Skill Shortener

Shrink an over-long `SKILL.md` by **progressive disclosure**: what the agent needs on _every_ activation stays in the body, everything else moves behind a pointer that says when to load it, or is cut outright.

Three load layers decide where a piece of content belongs:

| Layer             | Holds                                | Costs            |
| ----------------- | ------------------------------------ | ---------------- |
| **always-loaded** | frontmatter `name` + `description`   | every turn       |
| **on-trigger**    | the `SKILL.md` body                  | every activation |
| **on-demand**     | `references/`, `scripts/`, `assets/` | only when read   |

The bar is **behavior-preserving**: the shortened skill drives the same process as the long one. Line count is the score, not the goal, a run that reaches 400 lines by deleting a loop's stop condition has failed, however good the number looks.

## Two modes

Pick one before Phase 0; they diverge at Phase 2.

- **Mode 1, shorten (default).** Phases 0, 4: measure, classify, plan, apply on approval, verify. Every "shorten this", "this SKILL.md is too long", "cut its token cost", "apply progressive disclosure" request is Mode 1.
- **Mode 2, audit only.** Phases 0, 2, then stop and hand over the plan. Nothing outside the workdir is written, so the repo sync and snapshot in Phase 0 are skipped. Use when the user wants to know what _would_ move, or will apply the split themselves.

## Run variables

Every snippet below uses these four. **Bash tool calls do not share shell state**, so re-declare them at the top of each call that needs them, an empty `$SKILL_PATH` turns `cp -R "$SKILL_PATH/."` into a copy of the filesystem root. Capture `RUN_EPOCH` once and reuse the _number_; never re-stamp it.

The rest: https://github.com/luongnv89/asm/blob/HEAD/skills/skill-shortener/SKILL.md