Skill Install Improved

You install an improved variant of one skill instead of the skill as published: resolve the target to a local directory → run skill-creator's Subpath B1 retrofit loop on it → install the improved result → report what was improved and from what. The improvement is a step inside the install, not a separate errand. One skill per run.

When to Use

• The user says "install <skill> but improve it first" or "install an improved version of <skill>"
• The user points at a catalog skill below the 85/8 floor and wants the better version on their machine
• The user has a local or cloned skill directory and wants the improved variant installed, not the raw one

Do not trigger for: improving without installing (skill-creator), contributing upstream (skill-upstream-pr), authoring from scratch (skill-creator), plain installs (asm install <source>), or bulk-improving many skills at once.

Prerequisites

Verify each before resolving anything. If one fails, stop and tell the user which one.

• asm and git on PATH, and Python 3 (skill-creator's validator needs it)
• Network access to GitHub, for the repo and name forms
• Write access to the install target for the chosen tool and scope (see asm list --json for existing install paths)

The user's own files are never modified (design decision)

Every input form is improved on a throwaway copy under $(mktemp -d) — local paths included. An install that rewrites the user's working copy is a side effect they did not ask for, and the retrofit loop's git pull --rebase would rebase their branch.

Repo sync is skipped for every form. A local-path copy has no origin. A repo or name clone does have origin, but it is a throwaway --depth 1 checkout that may sit on a detached --ref, and a pull could move it off the requested ref. The retrofit loop allows this skip for a caller's throwaway copy. Say so when you skip it.

Trade-off: the improvement lands only in the installed copy. To persist it, point the user at skill-creator (their own path) or skill-upstream-pr (the source repo).

Dependency Preflight (mandatory)

This skill invokes skill-creator, declared in frontmatter dependencies. Before Phase 0, verify asm is available:

command -v asm >/dev/null || {
  echo "Missing installer: npm install -g agent-skill-manager" >&2
  exit 1
}
asm deps discover skill-install-improved --json

When execution reaches Phase 1, the main agent runs:

asm deps acquire skill-creator --session <caller-session-id> --json

<caller-session-id> is a unique id the main agent picks once per run, e.g. skill-install-improved-<epoch-seconds>; reuse it for the release.

Set SKILL_CREATOR_DIR to the directory holding the returned skillMdPath, and use it immediately; do not wait for a provider catalog rescan. The retrofit loop is $SKILL_CREATOR_DIR/references/retrofit-loop.md; its validator is $SKILL_CREATOR_DIR/scripts/quick_validate.py. If the acquire fails, stop before Phase 1 and report the error — this skill cannot improve anything without it.

The main agent releases the lease from its own finally/shutdown handling — after Phase 4, or at any earlier stop:

asm deps release --session <caller-session-id> --json

If Phase 0 stops before Phase 1, do not acquire.

Inputs

The user identifies one target skill, in any of four forms — a local path (skills/foo), a local SKILL.md file path, a repo (https://github.com/owner/repo, owner/repo), or a skill name (code-review). Phase 0 normalizes all of them to one local directory, $SKILL_PATH.

Also needed before Phase 3: the install scope (global or project) and the target tool (-p/--tool — claude, codex, agents, …). If the user did not state one, ask; never guess. asm install hard-fails without --tool in a non-interactive run, and -y does not cover it.

Optional: a --name <alt> intent.

Before Phase 0, record the directory the user invoked you from as CALLER_DIR (pwd). Project-scope paths resolve from the current directory, so Phase 3 must run there, not inside $WORK.

Workflow

Execute phases in order. Do not skip or reorder.

Phase 0 — Resolve the target to one local directory

Full contract in references/target-resolution.md. In short, with WORK="$(mktemp -d)":

• Local path — cp -R into $WORK. A SKILL.md file path folds to its parent first; the retrofit loop takes a directory, not a file.
• Repo — plain git clone into $WORK. Never gh repo fork — this skill performs no public GitHub action.
• Skill name — asm search "<term>" --available --json, then copy the string after asm install from the chosen result's installCommand verbatim. Never hand-construct github:owner/repo:path. Clone what it names.

Set $SKILL_PATH to the directory holding the chosen SKILL.md. If the checkout holds several and no subpath was given, list them (find "$WORK" -maxdepth 5 -name SKILL.md -type f) and ask which one. Never guess.

Record for the report: the supplied identifier, the resolved install or clone URL, and the upstream commit SHA.

Phase 1 — Delegate to skill-creator's retrofit loop

This skill does not reimplement the improvement loop, and it reads that loop only now, so the loop's references stay out of the context budget until Phase 1. Acquire skill-creator (Dependency Preflight), then follow $SKILL_CREATOR_DIR/references/retrofit-loop.md (Subpath B1) with $SKILL_PATH as the target, through its Phase 7 report.

Two adaptations, because the target is a throwaway copy:

• Skip its "Repo Sync Before Edits" step. Log — repo sync skipped (throwaway copy) and continue.
• .asm-improver/ is written relative to the current working directory. Run the loop with cwd inside $SKILL_PATH, or Phase 2 has nothing to harvest.
• If the loop asks how to handle a target with no frontmatter, answer "abort" (see Edge Cases). If it offers a Subpath B3 delegation conversion, decline: this run installs, it does not restructure.

If the baseline already clears both gates, the retrofit loop stops without editing — a valid outcome, see Edge Cases.

Phase 2 — Harvest artifacts, then clean up

Harvest before any cleanup. Read the files under $SKILL_PATH/.asm-improver/ that references/install-and-report.md lists, and extract its fields. An early-exit baseline writes no iter-N.json; then the baseline is also the final state.

Then confirm $SKILL_PATH is still inside $WORK, and remove the two artifacts that must not ship (asm install copies the source recursively):

rm -f "$SKILL_PATH/SKILL.md.bak"
rm -rf "$SKILL_PATH/.asm-improver" "$SKILL_PATH/.git"

Never point either command at a user-supplied path.

Phase 3 — Install the improved directory

The retrofit loop never renames, so the improved variant keeps the original frontmatter name. asm install never refuses on a collision: with -y it deletes and replaces the target directory without a prompt. So probe before invoking it:

Run this phase from CALLER_DIR:

cd "$CALLER_DIR"
asm list --json    # is this skill's name or directory already installed for $TOOL / $SCOPE?

Read references/install-and-report.md → Collision policy and take the path it gives for the probe result. The rule that never changes: if the probe shows any match — frontmatter name or directory name — name the target path and what occupies it, and get explicit confirmation before running asm install. Use --name <alt> only when the user asks for it, after the duplicate-trigger warning.

Only after the probe is read and any collision is confirmed:

asm install "$SKILL_PATH" -p "$TOOL" --scope "$SCOPE" --json -y

Install $SKILL_PATH, never the original source. Take the installed path from the command's --json output (.path); never assume ~/.claude/skills/.

Phase 4 — Report, then clean up

Fill in the report template in references/install-and-report.md. It covers the four items the user needs: the result, the evidence, what stays untested, and the next decision.

Remove $WORK only after the report is printed, then release the dependency lease.

Step Completion Reports (mandatory)

After each phase, print a compact status block: √ pass, × fail, — context.

◆ Phase N — [phase name] ([N of 5])
··································································
  [check 1]:         √ pass
  [check 2]:         × fail — [reason]
  Result:            PASS | FAIL | PARTIAL

Checks per phase:

• Phase 0 — Form identified, Copied to temp, SKILL_PATH unambiguous, Provenance recorded
• Phase 1 — skill-creator acquired, Baseline captured, Repo sync skipped, Gates cleared or stop reason known
• Phase 2 — Metrics harvested, .bak removed, .asm-improver removed, Deletions confined to temp
• Phase 3 — Collision probed before install, Overwrite confirmed (if any), Tool and scope supplied, Install succeeded
• Phase 4 — Report printed, Temp dir removed, Lease released

Acceptance Criteria

The expected output of a successful run, each item checkable:

• Exactly one target resolved; $SKILL_PATH is a directory with a SKILL.md, under $WORK; the user's files are unmodified
• Name resolution copied installCommand verbatim; repo resolution used plain git clone — no fork, no push
• The retrofit loop ran from the acquired skill-creator; baseline.json, iter-N.json, and report.md were read before cleanup
• The installed skill contains no .asm-improver/ and no SKILL.md.bak
• asm install targeted $SKILL_PATH with both -p/--tool and --scope, after a collision probe; any overwrite was confirmed first
• The report states the installed path, provenance, and before → after numbers
• $WORK was removed after the report, and the dependency lease was released

When reviewing a run's output (by eval or by a human), also check that a reader can:

• Find the main result — the first line says an improved variant was installed, the original was installed unchanged, or the run stopped.
• Separate facts from assumptions — measured scores are distinct from the untested runtime behavior of the improved skill.
• Trace claims — before → after numbers map to baseline.json and the last iter-N.json; the install path maps to install --json .path.
• See the next decision — the report names any action left (restart the agent, persist the change upstream) or states that none is needed.

An agent's own review cannot confirm human understanding. A reviewer who received no human feedback records understanding as unconfirmed.

Edge Cases

• Baseline already passes both gates — the retrofit loop stops without editing, but it has already written .asm-improver/. Still run Phase 2's cleanup and Phase 3's probe. Install the original, unchanged, and report that no improvement was needed, naming the baseline score. Never imply a delta that did not happen.
• Retrofit loop ends in BLOCKER — show the blocker list and ask whether to install the partial result or abort. Never install one silently.
• skill-creator cannot be acquired — stop before Phase 1, remove $WORK, and report the asm deps acquire error.
• Several SKILL.md files in a clone — list them and ask. Never batch, never guess.
• asm search returns nothing, or several equally-plausible matches — show the candidates and ask; never install the first hit.
• Target has no frontmatter — asm eval --fix cannot add it, and this skill does not scaffold one. Answer "abort" to the retrofit loop, report, and stop; do not install an unimprovable skill as if it were improved.
• Collision with a same-named skill from another source — the install would replace someone else's skill with no prompt. Name the target directory and what the probe shows there (name, dirName, provider, scope), confirm, and offer --name <alt> — all before asm install runs.
• Clone or disk failure mid-resolve — stop, remove $WORK, report. Never install a partial checkout.

References

• references/target-resolution.md — the input forms normalized to one local $SKILL_PATH
• references/install-and-report.md — harvested fields, install flags, collision policy, report template
• $SKILL_CREATOR_DIR/references/retrofit-loop.md — the improvement loop this skill delegates to (acquired at run time)
• asm install --help and asm search --help — flag references