---
name: install-skill
description: Installs a Claude Code skill from a curated source via one of three methods (sparse-clone, plugin marketplace, or npx antigravity filtered). Always asks for confirmation before any install. Creates `.maxv-source.json` in the skill folder for traceability. Used by `orchestrate` after `discover-skill` identifies missing components.
when_to_use: |
  Called by `orchestrate` in step 7 for each component the user approved for install.
  Also invocable directly: "instale shadcn-ui",
  "/maxvision-orchestration:install-skill trailofbits",
  "/maxvision-orchestration:install-skill --method=npx antigravity:webapp-testing".
disable-model-invocation: true
allowed-tools: Read Bash(test *) Bash(jq *) Bash(gh api *) Bash(git clone *) Bash(git -C * sparse-checkout *) Bash(git -C * fetch *) Bash(git -C * rev-parse *) Bash(npx antigravity-awesome-skills *) Bash(date *) Bash(mkdir -p *) Bash(cat *) Bash(test -d *)
---

# Install skill

Argument: $ARGUMENTS — component id (matching an entry in `skill-sources.json`) and optional `--method=<sparse_clone|marketplace|npx_filtered>` override.

> **Hard rule:** this skill writes to disk. It must always confirm with the user before executing any install. Never auto-run.

## Workflow

### 1. Look up the source

Read `${CLAUDE_SKILL_DIR}/../discover-skill/references/skill-sources.json` and find the entry for `$ARGUMENTS` (by `id` or `highlight_skills[*]`).

If not found, abort: `"Component not in catalog. Use 'discover-skill <keyword>' to find candidates, or pass a fully-qualified URL with --custom-source."`

### 2. Choose install method

Pick from the entry's `install_methods[*]` array:
- If user passed `--method=<X>`, validate that the source supports it.
- Otherwise, use the entry where `primary: true`.

If a tier_4 source is selected, **always show the warning text** and require explicit `sim` (not `all`) for that line.

### 3. Show install plan

```
About to install: <component>
  Source:  <repo URL>
  Tier:    <tier_1|tier_2|tier_3|tier_4>
  License: <license>
  Method:  <sparse_clone|marketplace|npx_filtered>
  Target:  <destination path>
  Disk:    ~<estimated size> (sparse-clone reduces this)

[Tier 4 only]
  WARNING: <warning text from catalog>

Proceed? [sim/skip]
```

Wait for user response. If `skip`, exit and log.

### 4. Execute the install

#### Method A — sparse_clone

```bash
TARGET=~/.claude/skills/<skill-name>
mkdir -p "$(dirname "$TARGET")"

# Sparse clone for size efficiency
git clone --depth 1 --filter=blob:none --sparse <clone_url> "$TARGET"
git -C "$TARGET" sparse-checkout set <source_path>

# Capture sha for tracking
COMMIT_SHA=$(git -C "$TARGET" rev-parse HEAD)
```

Then write `.maxv-source.json` (see schema below).

#### Method B — marketplace

`/plugin marketplace add` and `/plugin install` are interactive commands. Echo the commands for the user to run:

```
Run these in your Claude Code session:
  /plugin marketplace add <repo>
  /plugin install <plugin-name>@<marketplace-name>
```

After they confirm completion, update the cache. **Do not** create `.maxv-source.json` for marketplace installs — those are tracked by Claude Code's `installed_plugins.json` natively.

#### Method C — npx_filtered (antigravity)

```bash
npx antigravity-awesome-skills --claude --category <category> --risk safe --tags <skill-tag>
```

Before running, show the user the exact command and which categories/tags will be installed. Wait for `sim`.

After execution, the npx tool installs into `~/.claude/skills/` directly. Walk the directory and create `.maxv-source.json` in each newly-created skill folder.

### 5. Write `.maxv-source.json`

For sparse-clone and npx installs:

```bash
cat > "$TARGET/.maxv-source.json" <<EOF
{
  "\$schema_version": "1.0.0",
  "repo": "<owner/repo>",
  "branch": "<branch>",
  "source_path": "<source_path>",
  "commit_sha": "$COMMIT_SHA",
  "last_check": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "install_method": "<method>",
  "installed_via": "maxvision-orchestration",
  "installed_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "catalog_id": "<id from skill-sources.json>",
  "tier": "<tier from catalog>"
}
EOF
```

### 6. Update cache

Update `~/.claude/cache/maxv-orchestration/version-check.json` with a fresh `up_to_date` entry for the new component.

### 7. Report

```
✓ Installed: <component>
  Source:  <repo>
  Method:  <method>
  Path:    ~/.claude/skills/<name>/
  Sha:     <commit_sha>
  Status:  ready (live-watched, no reload needed for personal skills)
```

For marketplace installs, add: `"Run /reload-plugins now to activate."`

Append to `~/.claude/projects/<workspace>/maxv-orchestration.log`:

```
2026-04-28T14:42:11Z  install  shadcn-ui  sparse_clone  shadcn-ui/ui@main:def5678  ok
```

## Guardrails

- **Single confirmation per component.** Even when `orchestrate` passes a batch approval, each tier_4 install still requires its own explicit `sim`.
- **Never overwrite an existing skill folder.** If `~/.claude/skills/<name>/` already exists, abort with `"Already installed. Use update-component to refresh, or remove the folder manually if you want a clean install."`
- **Never write outside `~/.claude/skills/`, `~/.claude/cache/maxv-orchestration/`, or the user's project `.claude/`.**
- **Never run `/plugin install` programmatically** — it is interactive. Always echo the command for the user to run.
- **Sparse-clone first.** Full clones of large repos (e.g. `awesome-agent-skills`) waste disk; always use `--depth 1 --filter=blob:none --sparse`.
- **License check.** Before install, verify the license in the catalog. If `license: source-available` (e.g. anthropics docx/pdf/pptx/xlsx), surface the restriction to the user explicitly.