skill-install-improved

Files (6)

• LICENSE.txt
• SKILL.md
• README.md · docs/
• evals.json · evals/
• install-and-report.md · references/
• target-resolution.md · references/

SKILL.md (first lines)

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

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

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

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

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

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

From luongnv89/asm, MIT.

More from luongnv89/asm