Skill Install Improved

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.