Install on OpenCode

Install Superpowers on OpenCode via plugin and skill symlinks

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

1. 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
   
2. Create Directories

   Ensure plugin and skill directories exist:

   mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
   
3. Create Plugin Symlink

   Register the Superpowers plugin:

   rm -f ~/.config/opencode/plugins/superpowers.js
   ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
   
4. Create Skills Symlink

   Make skills discoverable:

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

   Restart OpenCode to load the plugin and discover skills.

6. 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?
   

Windows (PowerShell)

1. 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.

2. Create Directories

   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"
   
3. 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
   
4. 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"
   
5. 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.

6. Restart OpenCode

   Close and restart OpenCode completely.

7. 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.

Windows (Command Prompt)

1. Clone Superpowers

   Run Command Prompt as Administrator:

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

   mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
   mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul
   
3. Remove Existing Links

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

   mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\superpowers\.opencode\plugins\superpowers.js"
   
5. Create Skills Junction

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

   Close and restart OpenCode.

7. Verify Installation

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

Windows (Git Bash)

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

1. Clone Superpowers

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

   mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
   
3. Remove Existing Links

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

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

   cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""
   
6. 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:

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

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

Using Skills

1. List Available Skills

   use skill tool to list skills
   

   This shows all discovered skills including Superpowers.

2. Load a Specific Skill

   use skill tool to load superpowers/brainstorming
   

   Explicitly load a skill by its path.

3. 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

1. Create Skill Directory

   mkdir -p ~/.config/opencode/skills/my-skill
   
2. 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]
   
3. 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 injected

Solutions:

• 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 skills

Solutions:

• 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” error

Solutions:

• 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 error

Solutions:

• 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 Superpowers

Solutions:

• 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