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

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

Preview without changing files:

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

Drive the planner non-interactively:

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

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:

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

Answers JSON

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

{
  "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 for Pi package layout details and mirror maintenance.