mirror of
https://github.com/obra/superpowers.git
synced 2026-04-28 12:39:07 +08:00
158 lines
4.1 KiB
Markdown
158 lines
4.1 KiB
Markdown
# Superpowers for OpenCode
|
|
|
|
Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
|
|
|
|
## Installation
|
|
|
|
Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
|
|
|
|
```json
|
|
{
|
|
"plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
|
|
}
|
|
```
|
|
|
|
Restart OpenCode. The plugin installs through OpenCode's plugin manager and
|
|
registers all skills.
|
|
|
|
Verify by asking: "Tell me about your superpowers"
|
|
|
|
OpenCode uses its own plugin install. If you also use Claude Code, Codex, or
|
|
another harness, install Superpowers separately for each one.
|
|
|
|
### Migrating from the old symlink-based install
|
|
|
|
If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
|
|
|
|
```bash
|
|
# Remove old symlinks
|
|
rm -f ~/.config/opencode/plugins/superpowers.js
|
|
rm -rf ~/.config/opencode/skills/superpowers
|
|
|
|
# Optionally remove the cloned repo
|
|
rm -rf ~/.config/opencode/superpowers
|
|
|
|
# Remove skills.paths from opencode.json if you added one for superpowers
|
|
```
|
|
|
|
Then follow the installation steps above.
|
|
|
|
## Usage
|
|
|
|
### Finding Skills
|
|
|
|
Use OpenCode's native `skill` tool to list all available skills:
|
|
|
|
```
|
|
use skill tool to list skills
|
|
```
|
|
|
|
### Loading a Skill
|
|
|
|
```
|
|
use skill tool to load superpowers/brainstorming
|
|
```
|
|
|
|
### Personal Skills
|
|
|
|
Create your own skills in `~/.config/opencode/skills/`:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/opencode/skills/my-skill
|
|
```
|
|
|
|
Create `~/.config/opencode/skills/my-skill/SKILL.md`:
|
|
|
|
```markdown
|
|
---
|
|
name: my-skill
|
|
description: Use when [condition] - [what it does]
|
|
---
|
|
|
|
# My Skill
|
|
|
|
[Your skill content here]
|
|
```
|
|
|
|
### Project Skills
|
|
|
|
Create project-specific skills in `.opencode/skills/` within your project.
|
|
|
|
**Skill Priority:** Project skills > Personal skills > Superpowers skills
|
|
|
|
## Updating
|
|
|
|
OpenCode installs Superpowers through a git-backed package spec. Some OpenCode
|
|
and Bun versions pin that resolved git dependency in a lockfile or cache, so a
|
|
restart may not pick up the newest Superpowers commit. If updates do not appear,
|
|
clear OpenCode's package cache or reinstall the plugin.
|
|
|
|
To pin a specific version, use a branch or tag:
|
|
|
|
```json
|
|
{
|
|
"plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
|
|
}
|
|
```
|
|
|
|
## How It Works
|
|
|
|
The plugin does two things:
|
|
|
|
1. **Injects bootstrap context** via the `experimental.chat.system.transform` hook, adding superpowers awareness to every conversation.
|
|
2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.
|
|
|
|
### Tool Mapping
|
|
|
|
Skills written for Claude Code are automatically adapted for OpenCode:
|
|
|
|
- `TodoWrite` → `todowrite`
|
|
- `Task` with subagents → OpenCode's `@mention` system
|
|
- `Skill` tool → OpenCode's native `skill` tool
|
|
- File operations → Native OpenCode tools
|
|
|
|
## Troubleshooting
|
|
|
|
### Plugin not loading
|
|
|
|
1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
|
|
2. Verify the plugin line in your `opencode.json` is correct
|
|
3. Make sure you're running a recent version of OpenCode
|
|
|
|
### Windows install issues
|
|
|
|
Some Windows OpenCode builds have upstream installer issues with git-backed
|
|
plugin specs, including cache paths for `git+https` URLs and Bun not finding
|
|
`git.exe` even when it works in a normal terminal. If OpenCode cannot install
|
|
the plugin, try installing with system npm and pointing OpenCode at the local
|
|
package:
|
|
|
|
```powershell
|
|
npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
|
|
```
|
|
|
|
Then use the installed package path in `opencode.json`:
|
|
|
|
```json
|
|
{
|
|
"plugin": ["~/.config/opencode/node_modules/superpowers"]
|
|
}
|
|
```
|
|
|
|
### Skills not found
|
|
|
|
1. Use OpenCode's `skill` tool to list available skills
|
|
2. Check that the plugin is loading (see above)
|
|
3. Each skill needs a `SKILL.md` file with valid YAML frontmatter
|
|
|
|
### Bootstrap not appearing
|
|
|
|
1. Check OpenCode version supports `experimental.chat.system.transform` hook
|
|
2. Restart OpenCode after config changes
|
|
|
|
## Getting Help
|
|
|
|
- Report issues: https://github.com/obra/superpowers/issues
|
|
- Main documentation: https://github.com/obra/superpowers
|
|
- OpenCode docs: https://opencode.ai/docs/
|