Complete guide for using Superpowers with OpenCode.ai.
Tell OpenCode:
Clone https://github.com/obra/superpowers to my OpenCode config directory under superpowers/, then create a plugins/ directory there, then symlink superpowers/.opencode/plugins/superpowers.js to plugins/superpowers.js, then symlink superpowers/skills to skills/superpowers, then restart opencode.
Custom config directory: If you've set
OPENCODE_CONFIG_DIR, the commands below will use it automatically. Otherwise they default to~/.config/opencode(macOS/Linux) or%USERPROFILE%\.config\opencode(Windows).
OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
# 1. Install Superpowers (or update existing)
if [ -d "$OPENCODE_CONFIG_DIR/superpowers" ]; then
cd "$OPENCODE_CONFIG_DIR/superpowers" && git pull
else
git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
fi
# 2. Create directories
mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
# 3. Remove old symlinks/directories if they exist
rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
# 4. Create symlinks
ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
# 5. Restart OpenCode
OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
Both should show symlinks pointing to the superpowers directory.
Prerequisites:
Pick your shell below: Command Prompt | PowerShell | Git Bash
Run as Administrator, or with Developer Mode enabled:
if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
:: 1. Install Superpowers
git clone https://github.com/obra/superpowers.git "%OPENCODE_CONFIG_DIR%\superpowers"
:: 2. Create directories
mkdir "%OPENCODE_CONFIG_DIR%\plugins" 2>nul
mkdir "%OPENCODE_CONFIG_DIR%\skills" 2>nul
:: 3. Remove existing links (safe for reinstalls)
del "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" 2>nul
rmdir "%OPENCODE_CONFIG_DIR%\skills\superpowers" 2>nul
:: 4. Create plugin symlink (requires Developer Mode or Admin)
mklink "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" "%OPENCODE_CONFIG_DIR%\superpowers\.opencode\plugins\superpowers.js"
:: 5. Create skills junction (works without special privileges)
mklink /J "%OPENCODE_CONFIG_DIR%\skills\superpowers" "%OPENCODE_CONFIG_DIR%\superpowers\skills"
:: 6. Restart OpenCode
Run as Administrator, or with Developer Mode enabled:
if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
# 1. Install Superpowers
git clone https://github.com/obra/superpowers.git "$env:OPENCODE_CONFIG_DIR\superpowers"
# 2. Create directories
New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\plugins"
New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\skills"
# 3. Remove existing links (safe for reinstalls)
Remove-Item "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -Force -ErrorAction SilentlyContinue
# 4. Create plugin symlink (requires Developer Mode or Admin)
New-Item -ItemType SymbolicLink -Path "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\.opencode\plugins\superpowers.js"
# 5. Create skills junction (works without special privileges)
New-Item -ItemType Junction -Path "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\skills"
# 6. Restart OpenCode
Note: Git Bash's native ln command copies files instead of creating symlinks. Use cmd //c mklink instead (the //c is Git Bash syntax for /c).
OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
# 1. Install Superpowers
git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
# 2. Create directories
mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
# 3. Remove existing links (safe for reinstalls)
rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js" 2>/dev/null
rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers" 2>/dev/null
# 4. Create plugin symlink (requires Developer Mode or Admin)
cmd //c "mklink \"$(cygpath -w "$OPENCODE_CONFIG_DIR/plugins/superpowers.js")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js")\""
# 5. Create skills junction (works without special privileges)
cmd //c "mklink /J \"$(cygpath -w "$OPENCODE_CONFIG_DIR/skills/superpowers")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/skills")\""
# 6. Restart OpenCode
If running OpenCode inside WSL, use the macOS / Linux instructions instead.
Command Prompt:
if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
dir /AL "%OPENCODE_CONFIG_DIR%\plugins"
dir /AL "%OPENCODE_CONFIG_DIR%\skills"
PowerShell:
if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
Get-ChildItem "$env:OPENCODE_CONFIG_DIR\plugins" | Where-Object { $_.LinkType }
Get-ChildItem "$env:OPENCODE_CONFIG_DIR\skills" | Where-Object { $_.LinkType }
Look for <SYMLINK> or <JUNCTION> in the output.
"You do not have sufficient privilege" error:
"Cannot create a file when that file already exists":
Symlinks not working after git clone:
git config --global core.symlinks true and re-cloneUse OpenCode's native skill tool to list all available skills:
use skill tool to list skills
Use OpenCode's native skill tool to load a specific skill:
use skill tool to load superpowers/brainstorming
Create your own skills in your OpenCode skills directory:
OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
Create a SKILL.md in that directory:
---
name: my-skill
description: Use when [condition] - [what it does]
---
# My Skill
[Your skill content here]
Create project-specific skills in your OpenCode project:
# In your OpenCode project
mkdir -p .opencode/skills/my-project-skill
Create .opencode/skills/my-project-skill/SKILL.md:
---
name: my-project-skill
description: Use when [condition] - [what it does]
---
# My Project Skill
[Your skill content here]
OpenCode discovers skills from these locations:
.opencode/skills/) - Highest priority~/.config/opencode/skills/)~/.config/opencode/skills/superpowers/) - via symlinkThe plugin automatically injects superpowers context via the experimental.chat.system.transform hook. This adds the "using-superpowers" skill content to the system prompt on every request.
Superpowers uses OpenCode's native skill tool for skill discovery and loading. Skills are symlinked into the skills directory so they appear alongside your personal and project skills.
Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:
TodoWrite → todowriteTask with subagents → OpenCode's @mention systemSkill tool → OpenCode's native skill toolLocation: $OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js
Components:
experimental.chat.system.transform hook for bootstrap injectionLocation: $OPENCODE_CONFIG_DIR/skills/superpowers/ (symlink to $OPENCODE_CONFIG_DIR/superpowers/skills/)
Skills are discovered by OpenCode's native skill system. Each skill has a SKILL.md file with YAML frontmatter.
OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
cd "$OPENCODE_CONFIG_DIR/superpowers"
git pull
Restart OpenCode to load the updates.
ls $OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.jsls -l $OPENCODE_CONFIG_DIR/plugins/ (macOS/Linux) or dir /AL "%OPENCODE_CONFIG_DIR%\plugins" (Windows)opencode run "test" --print-logs --log-level DEBUGls -l $OPENCODE_CONFIG_DIR/skills/superpowers (should point to superpowers/skills/)skill tool to list available skillsSKILL.md file with valid frontmatterIf you see Cannot find module errors on Windows:
ln -sf copies files instead of creating symlinksmklink /J directory junctions instead (see Windows installation steps)ls $OPENCODE_CONFIG_DIR/superpowers/skills/using-superpowers/SKILL.mdexperimental.chat.system.transform hookVerify your installation:
# Check plugin loads
opencode run --print-logs "hello" 2>&1 | grep -i superpowers
# Check skills are discoverable
opencode run "use skill tool to list all skills" 2>&1 | grep -i superpowers
# Check bootstrap injection
opencode run "what superpowers do you have?"
The agent should mention having superpowers and be able to list skills from superpowers/.