Stefano Fiorini
168 lines
6.3 KiB
Markdown
168 lines
6.3 KiB
Markdown
# 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.
|