From 494e29f7979678c89b66bb4c5031021720e8cf32 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Thu, 23 Apr 2026 21:27:52 -0500 Subject: [PATCH] docs: add skill manager documentation --- README.md | 18 +++++- docs/CLAUDE-CODE.md | 57 +++++++++++++++++++ docs/CODEX.md | 61 ++++++++++++++++++++ docs/CURSOR.md | 84 +++++++++++++++++++++++++++ docs/INSTALLER.md | 134 ++++++++++++++++++++++++++++++++++++++++++++ docs/OPENCODE.md | 65 +++++++++++++++++++++ docs/README.md | 5 ++ 7 files changed, 423 insertions(+), 1 deletion(-) create mode 100644 docs/CLAUDE-CODE.md create mode 100644 docs/CODEX.md create mode 100644 docs/CURSOR.md create mode 100644 docs/INSTALLER.md create mode 100644 docs/OPENCODE.md diff --git a/README.md b/README.md index 36548e1..f1d822d 100644 --- a/README.md +++ b/README.md @@ -122,15 +122,31 @@ Use the repository skill manager to install, update/reinstall, or remove skills node scripts/manage-skills.mjs ``` -Useful non-interactive modes: +Useful non-interactive modes and examples: ```bash +# Preview detected clients and planned changes without writing files node scripts/manage-skills.mjs --dry-run + +# Emit a machine-readable operation plan from an answers file node scripts/manage-skills.mjs --plan-only --answers answers.json + +# Install/update a skill for a specific client +node scripts/manage-skills.mjs --client codex --scope global --skill create-plan --action install --yes +node scripts/manage-skills.mjs --client codex --scope global --skill create-plan --action update --yes + +# Remove a skill from a specific client +node scripts/manage-skills.mjs --client claude-code --scope global --skill do-task --action remove --yes + +# Install the Pi package globally or project-locally through the manager +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 ``` The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks Superpowers dependencies for workflow skills, and prints a final operation report. +`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill manager does not install, sync, or publish `ai_plan/` contents. + ## Pi Package The repo root now includes a pi package manifest that ships only the pi-specific surface: diff --git a/docs/CLAUDE-CODE.md b/docs/CLAUDE-CODE.md new file mode 100644 index 0000000..820cbb9 --- /dev/null +++ b/docs/CLAUDE-CODE.md @@ -0,0 +1,57 @@ +# Claude Code Manual Install + +## Skill Root + +Claude Code's Skill tool auto-discovers skills installed under: + +```bash +~/.claude/skills// +``` + +Manual install example: + +```bash +mkdir -p ~/.claude/skills/do-task +cp -R skills/do-task/claude-code/* ~/.claude/skills/do-task/ +``` + +Use `skills//claude-code/*` for each supported skill. + +## Reviewer Runtime + +```bash +mkdir -p ~/.claude/skills/reviewer-runtime +cp skills/reviewer-runtime/run-review.sh ~/.claude/skills/reviewer-runtime/ +cp skills/reviewer-runtime/notify-telegram.sh ~/.claude/skills/reviewer-runtime/ +chmod +x ~/.claude/skills/reviewer-runtime/*.sh +``` + +## Superpowers + +Workflow skills invoke Superpowers through Claude Code's skill system. Install or link the Obra Superpowers skills under: + +```bash +~/.claude/skills/superpowers/ +``` + +Example: + +```bash +ln -s /absolute/path/to/obra/superpowers/skills ~/.claude/skills/superpowers +``` + +Verify: + +```bash +test -f ~/.claude/skills/superpowers/brainstorming/SKILL.md +test -f ~/.claude/skills/superpowers/test-driven-development/SKILL.md +test -f ~/.claude/skills/superpowers/verification-before-completion/SKILL.md +``` + +## Verify + +```bash +claude --version +test -f ~/.claude/skills/do-task/SKILL.md +test -x ~/.claude/skills/reviewer-runtime/run-review.sh +``` diff --git a/docs/CODEX.md b/docs/CODEX.md new file mode 100644 index 0000000..306b761 --- /dev/null +++ b/docs/CODEX.md @@ -0,0 +1,61 @@ +# Codex Manual Install + +## Skill Root + +Codex skills are installed under: + +```bash +~/.codex/skills// +``` + +Manual install example: + +```bash +mkdir -p ~/.codex/skills/create-plan +cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/ +``` + +Repeat with `skills//codex/*` for `atlassian`, `create-plan`, `do-task`, `implement-plan`, and `web-automation`. + +## Reviewer Runtime + +Workflow skills need the shared runtime helpers: + +```bash +mkdir -p ~/.codex/skills/reviewer-runtime +cp skills/reviewer-runtime/run-review.sh ~/.codex/skills/reviewer-runtime/ +cp skills/reviewer-runtime/notify-telegram.sh ~/.codex/skills/reviewer-runtime/ +chmod +x ~/.codex/skills/reviewer-runtime/*.sh +``` + +## Superpowers + +Workflow skills require Obra Superpowers. Codex variants expect the shared root: + +```bash +mkdir -p ~/.agents/skills +ln -s /absolute/path/to/obra/superpowers/skills ~/.agents/skills/superpowers +``` + +Verify planning skills: + +```bash +test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md +test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md +``` + +Verify execution skills: + +```bash +test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md +test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md +test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md +``` + +## Verify + +```bash +test -f ~/.codex/skills/create-plan/SKILL.md +test -x ~/.codex/skills/reviewer-runtime/run-review.sh +codex --version +``` diff --git a/docs/CURSOR.md b/docs/CURSOR.md new file mode 100644 index 0000000..802b3c6 --- /dev/null +++ b/docs/CURSOR.md @@ -0,0 +1,84 @@ +# Cursor Manual Install + +## Skill Roots + +Cursor supports repo-local and global skills: + +```bash +.cursor/skills// +~/.cursor/skills// +``` + +Manual repo-local install example: + +```bash +mkdir -p .cursor/skills/create-plan +cp -R skills/create-plan/cursor/* .cursor/skills/create-plan/ +``` + +Global install example: + +```bash +mkdir -p ~/.cursor/skills/create-plan +cp -R skills/create-plan/cursor/* ~/.cursor/skills/create-plan/ +``` + +Cursor variants exist for `atlassian`, `create-plan`, `do-task`, and `implement-plan`. `web-automation` currently has no Cursor variant. + +## Reviewer Runtime + +Repo-local: + +```bash +mkdir -p .cursor/skills/reviewer-runtime +cp skills/reviewer-runtime/run-review.sh .cursor/skills/reviewer-runtime/ +cp skills/reviewer-runtime/notify-telegram.sh .cursor/skills/reviewer-runtime/ +chmod +x .cursor/skills/reviewer-runtime/*.sh +``` + +Global uses `~/.cursor/skills/reviewer-runtime/` instead. + +## Superpowers + +Cursor variants expect the nested Superpowers layout: + +```bash +.cursor/skills/superpowers/skills//SKILL.md +~/.cursor/skills/superpowers/skills//SKILL.md +``` + +Recommended symlink: + +```bash +mkdir -p .cursor/skills/superpowers +ln -s /absolute/path/to/obra/superpowers/skills .cursor/skills/superpowers/skills +``` + +## Cursor Reviewer Notes + +Cursor reviewer calls use JSON output and require `jq` where the skill variant parses reviewer responses: + +```bash +cursor-agent --version +jq --version +``` + +Reviewer calls must use `--mode=ask --trust --output-format json`, never write-capable modes. + +## Verify + +Repo-local scope: + +```bash +cursor-agent --version +test -f .cursor/skills/create-plan/SKILL.md +test -f .cursor/skills/superpowers/skills/brainstorming/SKILL.md +``` + +Global scope: + +```bash +cursor-agent --version +test -f ~/.cursor/skills/create-plan/SKILL.md +test -f ~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md +``` diff --git a/docs/INSTALLER.md b/docs/INSTALLER.md new file mode 100644 index 0000000..06d72f2 --- /dev/null +++ b/docs/INSTALLER.md @@ -0,0 +1,134 @@ +# 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 `/superpowers/skills` because Cursor variants expect `superpowers/skills//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 installs the full Pi bundle and bootstraps packaged runtimes: + +```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 +``` + +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. diff --git a/docs/OPENCODE.md b/docs/OPENCODE.md new file mode 100644 index 0000000..0f94eda --- /dev/null +++ b/docs/OPENCODE.md @@ -0,0 +1,65 @@ +# OpenCode Manual Install + +## Skill Root + +OpenCode skills are installed under: + +```bash +~/.config/opencode/skills// +``` + +Manual install example: + +```bash +mkdir -p ~/.config/opencode/skills/implement-plan +cp -R skills/implement-plan/opencode/* ~/.config/opencode/skills/implement-plan/ +``` + +Use `skills//opencode/*` for each supported skill. + +## Reviewer Runtime + +```bash +mkdir -p ~/.config/opencode/skills/reviewer-runtime +cp skills/reviewer-runtime/run-review.sh ~/.config/opencode/skills/reviewer-runtime/ +cp skills/reviewer-runtime/notify-telegram.sh ~/.config/opencode/skills/reviewer-runtime/ +chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh +``` + +## Superpowers + +OpenCode variants expect Superpowers at: + +```bash +~/.config/opencode/skills/superpowers +``` + +Example: + +```bash +ln -s /absolute/path/to/obra/superpowers/skills ~/.config/opencode/skills/superpowers +``` + +Verify: + +```bash +ls -l ~/.config/opencode/skills/superpowers +test -f ~/.config/opencode/skills/superpowers/brainstorming/SKILL.md +test -f ~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md +``` + +## OpenCode Reviewer Notes + +OpenCode reviewer calls use the built-in read-oriented plan agent: + +```bash +opencode run -m / --agent plan --format json "review prompt" +``` + +## Verify + +```bash +opencode --version +test -f ~/.config/opencode/skills/implement-plan/SKILL.md +test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh +``` diff --git a/docs/README.md b/docs/README.md index ded2472..843228e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,11 @@ This directory contains user-facing docs for each skill. ## Index +- [INSTALLER.md](./INSTALLER.md) — Skill manager wizard for installing, updating/reinstalling, and removing repo skills across supported clients. +- [CODEX.md](./CODEX.md) — Manual install instructions for Codex variants. +- [CLAUDE-CODE.md](./CLAUDE-CODE.md) — Manual install instructions for Claude Code variants. +- [CURSOR.md](./CURSOR.md) — Manual install instructions for Cursor variants. +- [OPENCODE.md](./OPENCODE.md) — Manual install instructions for OpenCode variants. - [ATLASSIAN.md](./ATLASSIAN.md) — Includes requirements, generated bundle sync, install, auth, safety rules, and usage examples for the Atlassian skill. - [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan. - [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit. Sibling of create-plan/implement-plan scoped to ad-hoc tasks.