ai-coding-skills/docs/INSTALLER.md

# Skill Manager Installer

Use the skill manager wizard to install, update/reinstall, or remove skills from this repository for supported local coding clients.

## Quick Start

```bash
./scripts/manage-skills.sh
# or
node scripts/manage-skills.mjs
```

Preview without changing files:

```bash
node scripts/manage-skills.mjs --dry-run
```

Drive the planner non-interactively:

```bash
node scripts/manage-skills.mjs --plan-only --answers answers.json
```

## Supported Clients

The wizard detects these clients by CLI and known skill directories:

| Client | CLI check | Default skill root |
|---|---|---|
| Codex | `codex --version` | `~/.codex/skills` |
| Claude Code | `claude --version` | `~/.claude/skills` |
| Cursor | `cursor-agent --version` then `cursor agent --version` | `.cursor/skills` or `~/.cursor/skills` |
| OpenCode | `opencode --version` | `~/.config/opencode/skills` |
| Pi | `pi --version` | package mode or `.pi/skills` / `~/.pi/agent/skills` |

## Actions

For each selected client/scope, the wizard lists repository skills and offers actions based on installed state:

- missing skill: `install` or `skip`
- installed/stale/unknown skill: `update`, `reinstall`, `remove`, or `skip`
- unsupported variant: reported as `unsupported` and skipped

The current skill matrix is:

| Skill | Codex | Claude Code | Cursor | OpenCode | Pi |
|---|---:|---:|---:|---:|---:|
| `atlassian` | yes | yes | yes | yes | yes |
| `create-plan` | yes | yes | yes | yes | yes |
| `do-task` | yes | yes | yes | yes | yes |
| `implement-plan` | yes | yes | yes | yes | yes |
| `web-automation` | yes | yes | yes | yes | yes |

## Superpowers Handling

Workflow skills require Obra Superpowers:

- `create-plan`: `brainstorming`, `writing-plans`
- `implement-plan`: `executing-plans`, `using-git-worktrees`, `verification-before-completion`, `finishing-a-development-branch`
- `do-task`: `brainstorming`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch` plus conditional `using-git-worktrees`

When a selected install/update needs Superpowers and none are detected for the target client/scope, the wizard asks whether to install them. It asks for an absolute path to an Obra Superpowers `skills` directory and lets you choose symlink or copy:

- symlink is recommended because updates to the source checkout are immediately visible
- copy is more self-contained but must be updated manually

The wizard recognizes client-native and plugin-managed Superpowers installs before asking to add another copy:

- Codex: `~/.agents/skills/superpowers` or `~/.codex/superpowers/skills`
- Claude Code: `~/.claude/skills/superpowers` or the enabled `superpowers@claude-plugins-official` plugin cache
- Cursor: `.cursor/skills/superpowers/skills`, `~/.cursor/skills/superpowers/skills`, or the Cursor public Superpowers plugin cache
- OpenCode: `~/.agents/skills/superpowers` or `~/.config/opencode/skills/superpowers`
- Pi: `~/.agents/skills/superpowers`, `~/.pi/agent/skills/superpowers`, or `.pi/skills/superpowers`

When Cursor has no plugin/cache install, the wizard installs Superpowers at `<scope>/superpowers/skills` because Cursor variants expect `superpowers/skills/<skill>/SKILL.md`. Symlinking is still preferred when the source tree is managed locally. Codex and OpenCode can commonly reuse the shared `~/.agents/skills/superpowers` convention documented in [CODEX.md](./CODEX.md) and [OPENCODE.md](./OPENCODE.md).

When removing the last repository workflow skill from a client/scope, the wizard asks whether to remove Superpowers for that variant too.

## Reviewer Runtime Helpers

Workflow skills install/update the reviewer-runtime helper bundle automatically when needed:

- non-Pi clients receive `run-review.sh` and `notify-telegram.sh` from `skills/reviewer-runtime/`
- Pi receives `run-review.sh` and `notify-telegram.sh` from `skills/reviewer-runtime/pi/`
- diagnostics tests and nested Pi helper directories are not copied into non-Pi installs

## Pi Package Mode

Pi can be managed as a package install or by manual skill copy. Package mode always manages the full Pi bundle; per-skill prompts and `--skill` narrowing are ignored for `packageGlobal` and `packageLocal`.

Package-mode actions:

- `install`: register the package if needed, list bundled skills, and skip already-bootstrapped runtimes.
- `update`: sync the Pi package mirror, reinstall the package registration, and rerun runtime dependency bootstrapping.
- `reinstall`: same behavior as `update`, kept for action parity with manual skill scopes.
- `remove`: unregister the package with `pi remove`; this does not delete repo files or `node_modules`.

Examples:

```bash
node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --action install --yes
node scripts/manage-skills.mjs --client pi --scope packageLocal --pi-package --action install --yes
node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --action update --yes
node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --action remove --yes
```

The compatibility script remains available:

```bash
./scripts/install-pi-package.sh --global
./scripts/install-pi-package.sh --local
```

## Answers JSON

`--plan-only --answers` accepts this shape:

```json
{
  "selections": [
    {
      "clientId": "codex",
      "scope": "global",
      "actions": {
        "create-plan": "install",
        "web-automation": "skip"
      }
    }
  ]
}
```

The output is JSON containing planned operations, dependency prompts, and final-report rows. No filesystem changes are made.

## Final Report

The final report uses these columns:

| Column | Meaning |
|---|---|
| client | client id |
| scope | selected target scope |
| skill/helper | skill name or helper bundle |
| action | install, update, reinstall, remove, sync, bootstrap, etc. |
| status | `ok`, `skipped`, `failed`, or `warning` |
| details | target path or error detail |

Exit code is non-zero if any selected operation fails.

Dangling symlink warnings are surfaced as `warning` rows. For example, if a previously symlinked Superpowers source has moved or been deleted, the final report keeps the operation non-destructive and shows the dangling symlink target in `details` so you can repair or remove it deliberately.

See [PI.md](./PI.md) for Pi package layout details and mirror maintenance.