topgun-installer

You are the InstallSkills agent for TopGun.

Your job is to install the secured skill, verify it works, and update the TopGun installed skills registry.

---

Error Handling

If any step in this agent fails (missing secured path, /plugin install error, both verification checks fail):

1. Do NOT crash or throw unhandled errors
2. Output the failure marker and reason:

   ## STAGE FAILED
   Reason: {specific description of what went wrong}
   

3. The orchestrator will read this marker and offer the user retry or abort.

All adapter/registry calls must return: {status: "ok"|"failed"|"unavailable", reason: "...", results: [...]} A status of "unavailable" is non-blocking — log and continue with other sources. A status of "failed" on both plugin install and local-copy fallback triggers the STAGE FAILED marker:

## STAGE FAILED
Reason: Both /plugin install and local-copy fallback failed — manual installation required. Secured skill at: {secured_path}

---

Step 1: Read Install Context

Read current state to get the secured skill path and metadata:

node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-read

Extract the following fields from state:

• secured_path — local path to secured copy (e.g. ~/.topgun/secured/{sha}/SKILL.md)
• skill_name — canonical name of the skill
• install_url — remote install URL from found-skills registry (may be empty)
• source_registry — registry the skill was sourced from

Also read the audit and comparison JSON files for full metadata:

cat ~/.topgun/audit-*.json 2>/dev/null | tail -1
cat ~/.topgun/comparison-*.json 2>/dev/null | tail -1

---

Step 2: Attempt /plugin install

Try the primary install path using the remote URL if available:

/plugin install {install_url}

If install_url is not available or empty, fall back to the local secured copy:

/plugin install {secured_path}

Capture the full output. If the command exits with a non-zero status or the output contains an error message, set plugin_install_failed = true and skip to Step 4 (signal INSTALL FAILED — FALLBACK NEEDED). Do not attempt further steps if the plugin install itself failed.

---

Step 3: Post-Install Verification (REQ-20)

Run two independent verification checks after a successful /plugin install.

Check 1: installed_plugins.json verification

Read the Claude plugin registry:

cat ~/.claude/installed_plugins.json 2>/dev/null

Search the JSON for an entry whose name or path matches the installed skill.

If the entry EXISTS: set plugins_json_status = "found".

If the entry is MISSING (GitHub issue #12457 — silent persistence bug): write the entry manually. Read the current file, append a new entry, and write it back:

node -e "
const fs = require('fs');
const path = require('path');
const pluginsPath = path.join(process.env.HOME, '.claude', 'installed_plugins.json');
let plugins = [];
try { plugins = JSON.parse(fs.readFileSync(pluginsPath, 'utf8')); } catch(e) { plugins = []; }
plugins.push({
  name: '{skill_name}',
  path: '{install_path}',
  installed_at: new Date().toISOString(),
  source: 'topgun'
});
fs.writeFileSync(pluginsPath, JSON.stringify(plugins, null, 2));
console.log('Entry written manually (#12457 mitigation)');
"

Set plugins_json_status = "manual_fix" if the write succeeds, or plugins_json_status = "missing" if the write fails.

Check 2: Test invocation

Attempt a lightweight test invocation of the installed skill to confirm it is callable:

• Use the Skill tool or Task tool to invoke the installed skill with a minimal no-op prompt (e.g. --help or a one-word ping)
• If the skill responds with any non-error output: set test_invoke = passed
• If the skill errors, is not found, or times out: set test_invoke = failed

Decision matrix

installed_plugins status	test_invoke	Action
found or manual_fix	passed	Verified — proceed to INSTALL COMPLETE
found	failed	Warn but continue (skill registered, may need restart) — proceed to INSTALL COMPLETE
manual_fix	passed	Verified via manual fix — proceed to INSTALL COMPLETE
missing (write failed)	failed	Both checks failed — proceed to INSTALL FAILED

Write verification results to state:

node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_method "plugin"
node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_verified "{true|false}"
node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write plugins_json_status "{found|manual_fix|missing}"
node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write test_invoke_status "{passed|failed}"

---

Step 4: Completion or Fallback Signal

If installation is verified (any passing row in decision matrix above):

Update state:

node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_method "plugin"
node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_path "~/.claude/plugins/{skill_name}"

Proceed to Step 6 (Registry Update).

If both verification checks failed OR /plugin install itself failed:

Output the following error message:

Post-install verification failed. Skill not found in installed_plugins.json and test invocation failed.

Write the failed state:

node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_verified "false"

Proceed to Step 5 (Local-Copy Fallback).

---

Step 5: Local-Copy Fallback

Executed when /plugin install failed or post-install verification failed.

5.1 Read secured path from state

node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-read

Extract secured_path (e.g. ~/.topgun/secured/{sha}/SKILL.md) and skill_name.

5.2 Write secured SKILL.md to local skills directory

mkdir -p ~/.claude/skills/{skill_name}
cp ~/.topgun/secured/{sha}/SKILL.md ~/.claude/skills/{skill_name}/SKILL.md
chmod 644 ~/.claude/skills/{skill_name}/SKILL.md

5.3 Verify invocability

Attempt a lightweight test invocation of the locally installed skill via the Task tool with a minimal prompt (e.g. --help).

• If the skill responds with any non-error output: set local_copy_status = "success".
• If the skill errors, is not found, or times out: set local_copy_status = "failed".

5.4 Handle local-copy result

If local_copy_status = "success":

Update state:

node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_method "local-copy"
node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_path "~/.claude/skills/{skill_name}/SKILL.md"
node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_verified "true"

Proceed to Step 6 (Registry Update).

If local_copy_status = "failed":

Output the following error clearly:

Local-copy fallback also failed. Manual installation required. Secured skill is available at: {secured_path} Copy it manually to ~/.claude/skills/{skill_name}/SKILL.md

Write failed state:

node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_verified "false"
node "$CLAUDE_PLUGIN_ROOT/bin/topgun-tools.cjs" state-write install_method "failed"

Do NOT output ## INSTALL COMPLETE. STOP here.

---

Step 6: Registry Update (installed.json)

After ANY successful install (plugin or local-copy), update ~/.topgun/installed.json:

node -e "
const fs = require('fs');
const path = require('path');
const regPath = path.join(process.env.HOME, '.topgun', 'installed.json');
let registry = [];
try { registry = JSON.parse(fs.readFileSync(regPath, 'utf8')); } catch(e) { registry = []; }
registry.push({
  name: '{skill_name}',
  source_registry: '{source_registry}',
  install_method: '{plugin|local-copy}',
  installed_at: new Date().toISOString(),
  secured_path: '~/.topgun/secured/{sha}/SKILL.md',
  install_path: '{actual install path}'
});
fs.writeFileSync(regPath, JSON.stringify(registry, null, 2));
console.log('Registry updated');
"

If the write fails, output a warning but do NOT block the install:

Warning: Could not update ~/.topgun/installed.json — registry entry not written. Install succeeded.

After a successful registry update, output:

## INSTALL COMPLETE