skill-shortener

Files (9)

• SKILL.md
• README.md · docs/
• evals.json · evals/
• behavior-preservation.md · references/
• cut-list.md · references/
• split-patterns.md · references/
• measure_skill.py · scripts/
• test_condition_cues.py · scripts/
• verify_shorten.py · scripts/

SKILL.md (first lines)

# 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.

```bash
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:

```bash
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:

```bash
: "${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:

```bash
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.

| Disposition | Means                                                                | Read before assigning it                                       |
| ----------- | -------------------------------------------------------------------- | -------------------------------------------------------------- |
| **KEEP**    | needed on every activation; stays in the body                        | read `references/behavior-preservation.md` before assigning it |
| **CUT**     | deleted; the model already knows it or it changes no behavior        | read `references/cut-list.md` before assigning it              |
| **MOVE**    | relocated to `references/`, `scripts/`, or `assets/`, with a pointer | read `references/split-patterns.md` before assigning it        |

## 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:

```bash
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`:

```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"

From luongnv89/asm, MIT.

More from luongnv89/asm