Stefano Fiorini
146 lines
5.5 KiB
Markdown
146 lines
5.5 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 | no | 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
|
|
|
|
For Cursor, the wizard installs Superpowers at `<scope>/superpowers/skills` because Cursor variants expect `superpowers/skills/<skill>/SKILL.md`. Codex commonly reuses the shared `~/.agents/skills/superpowers` convention documented in [CODEX.md](./CODEX.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.
|