Files
superpowers/docs
Drew Ritter 98263ce179 docs: address PR #1121 review — respect user preference, drop y/n
- Consent prompt: drop "(y/n)" and add escape valve for users who
  have already declared their worktree preference in global or
  project agent instruction files.
- Directory selection: reorder to put declared user preference
  ahead of observed filesystem state, and reframe the default as
  "if no other guidance available".
- Sandbox fallback: require explicitly informing the user that
  the sandbox blocked creation, not just "report accordingly".
- writing-plans: fully qualify the superpowers:using-git-worktrees
  reference.
- Plan doc: mirror the consent-prompt change.

Step 1a native-tool framing and the helper-scripts suggestion are
still outstanding — the first needs a benchmark re-run before softer
phrasing can be adopted without regressing compliance; the second is
exploratory and will get a thread reply.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 09:53:08 -07:00
..

Superpowers for OpenCode

Complete guide for using Superpowers with OpenCode.ai.

Installation

Add superpowers to the plugin array in your opencode.json (global or project-level):

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

Restart OpenCode. The plugin auto-installs via Bun and registers all skills automatically.

Verify by asking: "Tell me about your superpowers"

If you previously installed superpowers using git clone and symlinks, remove the old setup:

# 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/:

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

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

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

Superpowers updates automatically when you restart OpenCode. The plugin is re-installed from the git repository on each launch.

To pin a specific version, use a branch or tag:

{
  "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:

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

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