Install on OpenCode

Install Superpowers on OpenCode using the plugin system and native skill discovery. OpenCode loads plugins at startup and discovers skills from ~/.config/opencode/skills/.

Prerequisites

OpenCode.ai installed
Git installed
Terminal access (Bash, PowerShell, Command Prompt, or Git Bash)

Quick Install

The fastest way is to tell OpenCode:

Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart opencode.

OpenCode will execute these steps automatically.

Manual Installation

For manual control, follow these platform-specific instructions:

macOS / Linux
Windows (PowerShell)
Windows (Command Prompt)
Windows (Git Bash)

Clone Superpowers

Install or update Superpowers:

if [ -d ~/.config/opencode/superpowers ]; then
  cd ~/.config/opencode/superpowers && git pull
else
  git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
fi

Create Directories

Ensure plugin and skill directories exist:

mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

Create Plugin Symlink

rm -f ~/.config/opencode/plugins/superpowers.js
ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js

Create Skills Symlink

Make skills discoverable:

rm -rf ~/.config/opencode/skills/superpowers
ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers

Restart OpenCode

Restart OpenCode to load the plugin and discover skills.

Verify Installation

Check both symlinks:

ls -l ~/.config/opencode/plugins/superpowers.js
ls -l ~/.config/opencode/skills/superpowers

Both should show symlinks pointing to the superpowers directory.Ask OpenCode:

Do you have superpowers?

Clone Superpowers

Open PowerShell (as Administrator or with Developer Mode enabled):

git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"

Windows symlinks require Developer Mode enabled OR running as Administrator.

Create Directories

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"

Remove Existing Links

Safe for reinstalls:

Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers" -Force -ErrorAction SilentlyContinue

Create Plugin Symlink

New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js"

Create Skills Junction

New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"

Junctions work like symlinks but don’t require special permissions.

Restart OpenCode

Close and restart OpenCode completely.

Verify Installation

Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }
Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }

Look for <SYMLINK> or <JUNCTION> in the output.

Clone Superpowers

Run Command Prompt as Administrator:

git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers"

Create Directories

mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul

Remove Existing Links

del "%USERPROFILE%\.config\opencode\plugins\superpowers.js" 2>nul
rmdir "%USERPROFILE%\.config\opencode\skills\superpowers" 2>nul

Create Plugin Symlink

mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\superpowers\.opencode\plugins\superpowers.js"

Create Skills Junction

mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.config\opencode\superpowers\skills"

Restart OpenCode

Close and restart OpenCode.

Verify Installation

dir /AL "%USERPROFILE%\.config\opencode\plugins"
dir /AL "%USERPROFILE%\.config\opencode\skills"

Git Bash’s ln command copies files instead of creating symlinks. Use cmd //c mklink instead.

Clone Superpowers

git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers

Create Directories

mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

Remove Existing Links

rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null
rm -rf ~/.config/opencode/skills/superpowers 2>/dev/null

Create Plugin Symlink

cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\""

Create Skills Junction

cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""

Restart OpenCode

Close and restart OpenCode.

How It Works

Superpowers integrates with OpenCode through two mechanisms:

Plugin System

The plugin (~/.config/opencode/plugins/superpowers.js) uses OpenCode’s experimental.chat.system.transform hook to inject the “using-superpowers” skill content into every chat request. This ensures Superpowers workflows are always active.

Native Skill Discovery

OpenCode discovers skills from:

Project skills (.opencode/skills/) - Highest priority
Personal skills (~/.config/opencode/skills/)
Superpowers skills (~/.config/opencode/skills/superpowers/) - via symlink

Use OpenCode’s native skill tool to list and load skills.

Using Skills

List Available Skills

use skill tool to list skills

This shows all discovered skills including Superpowers.

Load a Specific Skill

use skill tool to load superpowers/brainstorming

Explicitly load a skill by its path.

Automatic Activation

Skills activate automatically based on context:

Help me design a new feature for user authentication

The agent should automatically load the brainstorming skill.

Tool Mapping

Superpowers skills written for Claude Code are automatically adapted for OpenCode:

TodoWrite → update_plan (OpenCode’s planning tool)
Task with subagents → @mention system (OpenCode’s agent mentions)
Skill tool → OpenCode’s native skill tool
File operations → Native OpenCode tools

The plugin bootstrap provides these mapping instructions automatically.

Creating Personal Skills

Create Skill Directory

mkdir -p ~/.config/opencode/skills/my-skill

Write Skill File

Create ~/.config/opencode/skills/my-skill/SKILL.md:

---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill instructions here]

Restart OpenCode

Restart to discover the new skill.

Creating Project Skills

Add project-specific skills in your repository:

mkdir -p .opencode/skills/my-project-skill

Create .opencode/skills/my-project-skill/SKILL.md with the same structure as personal skills. Skill Priority: Project skills override personal skills, which override Superpowers skills.

Updating

Update to the latest version:

cd ~/.config/opencode/superpowers
git pull

Restart OpenCode to load updates.

Troubleshooting

Plugin not loading

Symptom: Superpowers context not injectedSolutions:

Check plugin exists: ls ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js
Verify symlink: ls -l ~/.config/opencode/plugins/superpowers.js
Check logs: opencode run "test" --print-logs --log-level DEBUG
Look for “superpowers” in log output
Ensure OpenCode version supports experimental.chat.system.transform hook

Skills not found

Symptom: Cannot load Superpowers skillsSolutions:

Verify skills symlink: ls -l ~/.config/opencode/skills/superpowers
Should point to ~/.config/opencode/superpowers/skills/
Use skill tool to list available skills
Check SKILL.md files have valid YAML frontmatter
Restart OpenCode after creating symlinks

Windows: Cannot create symlink

Symptom: “You do not have sufficient privilege” errorSolutions:

Enable Developer Mode: Settings → System → For developers
OR run PowerShell/Command Prompt as Administrator
For skills, use Junction (/J) instead of symlink (works without privileges)

Windows: Module not found error

Symptom: Plugin fails to load with module errorSolutions:

Git Bash ln -sf copies files instead of creating symlinks
Use mklink with cmd //c instead (see Git Bash instructions)
Run git config --global core.symlinks true and re-clone

Windows: File already exists error

Symptom: “Cannot create a file when that file already exists”Solutions:

Remove existing symlinks first (step 3 in installation)
Manually delete: del %USERPROFILE%\.config\opencode\plugins\superpowers.js
Then retry symlink creation

Bootstrap not appearing

Symptom: Agent doesn’t mention SuperpowersSolutions:

Verify using-superpowers skill exists: ls ~/.config/opencode/superpowers/skills/using-superpowers/SKILL.md
Check plugin loaded in OpenCode logs
Restart OpenCode after plugin installation
Test: ask “what superpowers do you have?”

Testing Your Installation

Verify everything works:

# 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 list skills from the superpowers/ namespace.

Uninstalling

Remove the symlinks:

rm ~/.config/opencode/plugins/superpowers.js
rm ~/.config/opencode/skills/superpowers

Windows (PowerShell):

Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js"
Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers"

Optionally delete the clone:

rm -rf ~/.config/opencode/superpowers

Windows (PowerShell):

Remove-Item -Recurse -Force "$env:USERPROFILE\.config\opencode\superpowers"

Next Steps

Quick Start

Learn the Superpowers workflow

Skills Reference

Browse all available skills

Writing Skills

Create custom skills

Troubleshooting

Common issues and solutions

Get Started

Installation

Core Concepts

Skills Library

Prerequisites

Quick Install

Manual Installation

How It Works

Plugin System

Native Skill Discovery

Using Skills

Tool Mapping

Creating Personal Skills

Creating Project Skills

Updating

Troubleshooting

Testing Your Installation

Uninstalling

Next Steps

Quick Start

Skills Reference

Writing Skills

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Installation

Core Concepts

Skills Library

​Prerequisites

​Quick Install

​Manual Installation

​How It Works

​Plugin System

​Native Skill Discovery

​Using Skills

​Tool Mapping

​Creating Personal Skills

​Creating Project Skills

​Updating

​Troubleshooting

​Testing Your Installation

​Uninstalling

​Next Steps

Quick Start

Skills Reference

Writing Skills

Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Quick Install

Manual Installation

How It Works

Plugin System

Native Skill Discovery

Using Skills

Tool Mapping

Creating Personal Skills

Creating Project Skills

Updating

Troubleshooting

Testing Your Installation

Uninstalling

Next Steps