Skill Shortener

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:

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.

SS="$HOME/.claude/skills/skill-shortener"                            # this skill
SKILL_PATH="$HOME/.claude/skills/<target>"                           # the target: the dir holding SKILL.md
QV="$HOME/.claude/skills/skill-creator/scripts/quick_validate.py"    # the Phase 4 gate
# RUN_EPOCH: reuse the number the preflight printed, e.g. RUN_EPOCH=1787948450

Dependency Preflight (mandatory)

This skill invokes skill-creator: it runs that skill's quick_validate.py as the Phase 4 frontmatter gate. Resolve it before the snapshot below, the first step that changes anything:

RUN_EPOCH="$(date +%s)"; echo "run_started_epoch=$RUN_EPOCH" >&2   # anchors Run stats
QV="$HOME/.claude/skills/skill-creator/scripts/quick_validate.py"
test -f "$QV" || {
  echo "Missing required skill: skill-creator" >&2
  echo "Install it:      asm install skill-creator -p claude --yes" >&2
  echo "No asm yet:      npm install -g agent-skill-manager" >&2
  echo "Verify:          asm list -p claude --json | grep 'skill-creator'" >&2
  exit 1
}

-p claude is not decoration: asm install refuses to guess a provider non-interactively and --yes does not cover that choice, so an install command without it errors instead of installing. On a miss, stop before the first mutation and print those three commands — never continue with a partial run.

Snapshot and Repo Sync Before Edits (mandatory)

Always snapshot first. The most common target — ~/.claude/skills/<name>/ — is not a git repository, so git is not a guaranteed undo path, and this skill rewrites a whole directory rather than one file:

: "${SKILL_PATH:?set SKILL_PATH to the target skill directory}"
: "${RUN_EPOCH:?reuse the epoch captured in the preflight}"
case "$PWD/" in "$SKILL_PATH"/*) echo "cwd is inside $SKILL_PATH — run from outside it, or the workdir is copied into itself" >&2; exit 1;; esac
SNAP=".skill-shortener/snapshot-$RUN_EPOCH"
mkdir -p "$SNAP" && cp -R "$SKILL_PATH/." "$SNAP/"

Then sync only if the target directory itself is a git work tree root — rev-parse --git-dir succeeds for any nested path inside a larger repo, and must not trigger fetch/pull of that tree:

toplevel="$(git -C "$SKILL_PATH" rev-parse --show-toplevel 2>/dev/null || true)"
if [ -n "$toplevel" ] && [ "$(cd "$SKILL_PATH" && pwd -P)" = "$toplevel" ]; then
  branch="$(git -C "$SKILL_PATH" rev-parse --abbrev-ref HEAD)"
  git -C "$SKILL_PATH" fetch origin && git -C "$SKILL_PATH" pull --rebase origin "$branch"
else
  echo "note: $SKILL_PATH is not a git work tree root — $SNAP is the only undo path; skip fetch/pull"
fi

If the tree is dirty, git stash, sync, git stash pop. If origin is missing or the pull conflicts, stop and ask the user — never skip or force the sync. In a git repo, suggest adding .skill-shortener/ to .gitignore.

The three dispositions

Every section of the body gets exactly one, and each has one reference behind it. Read the reference for the disposition you are about to assign — not all three up front.

Workflow

Phase 0 — Baseline

Mode 2 — skip snapshot and git sync. Audit-only must not reach fetch / pull --rebase. Run the preflight and the two measure_skill.py commands below, then continue to Phase 1. Do not create $SNAP and do not run the repo-sync block.

Mode 1. Run the preflight, take the snapshot, sync only when $SKILL_PATH is itself the git work tree root (see above), then measure:

python3 "$SS/scripts/measure_skill.py" "$SKILL_PATH" --json --out .skill-shortener/baseline.json
python3 "$SS/scripts/measure_skill.py" "$SKILL_PATH"   # the human-readable section table

The section table, largest first, is where the fat is — read it before reading the body.

Early exit. If the verdict is WITHIN_CAP, stop: print the current footprint and say no shortening is warranted — splitting a body that already fits costs a pointer hop for no saving. The one exception is an existing references/ tree that is chained or orphaned; see Edge cases. The user can override.

Done when: .skill-shortener/baseline.json exists with a non-empty sections array, and the verdict is recorded.

Phase 1 — Classify every section (the manifest)

Read the body, then assign every heading from baseline.json exactly one disposition. Write .skill-shortener/manifest.json:

{
  "target": "<skill-path>",
  "sections": [
    { "heading": "Overview", "disposition": "KEEP" },
    {
      "heading": "API error codes",
      "disposition": "MOVE",
      "destination": "references/<topic>.md",
      "load_condition": "when the API returns a non-200"
    },
    {
      "heading": "History",
      "disposition": "CUT",
      "reason": "changelog and attribution; changes no behavior"
    }
  ]
}

destination may be a string or a list. load_condition is the clause that goes into the pointer, so write it as the agent will read it: "when X", "before Y", "if Z".

The manifest is the loss-prevention record. Nothing is verified as preserved except through it, so an unclassified section is an unaudited deletion waiting to happen.

Done when: every heading in baseline.json appears in the manifest exactly once; every CUT carries a reason; every MOVE carries a destination and a load_condition. scripts/verify_shorten.py checks all four in Phase 4 — do not defer them.

Phase 2 — Plan and approve

Present the plan as a table — heading, disposition, destination, lines saved — plus the projected body size against both caps and the always-loaded/on-demand split. Name the biggest three savings first.

Expected output — the plan, before any file is touched:

Plan for skill-x — 812 lines / 5,140 words → projected 190 lines / 1,480 words

  heading                  disposition  destination                   lines
  -----------------------  -----------  ----------------------------  -----
  Azure deployment         MOVE         references/<branch>.md         -180
  Error code reference     MOVE         references/<codes>.txt         -140
  Release history          CUT          changelog; changes no behavior  -46
  Workflow                 KEEP         -                                 0

  always-loaded 64 tokens (unchanged) · on-trigger 12,900 → 3,700 · on-demand +9,100

Mode 2 ends here. In Mode 1, stop and wait for an explicit go-ahead. A split is a judgment call and the user is the one who has to live with the result.

Done when: the user has approved the plan, or asked for changes that are folded back into the manifest.