> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://opencode.ai) installed
* Git installed
* Terminal access (Bash, PowerShell, Command Prompt, or Git Bash)

## Quick Install

The fastest way is to tell OpenCode:

```text theme={null}
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:

<Tabs>
  <Tab title="macOS / Linux">
    <Steps>
      <Step title="Clone Superpowers">
        Install or update Superpowers:

        ```bash theme={null}
        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
        ```
      </Step>

      <Step title="Create Directories">
        Ensure plugin and skill directories exist:

        ```bash theme={null}
        mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
        ```
      </Step>

      <Step title="Create Plugin Symlink">
        Register the Superpowers plugin:

        ```bash theme={null}
        rm -f ~/.config/opencode/plugins/superpowers.js
        ln -s ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js ~/.config/opencode/plugins/superpowers.js
        ```
      </Step>

      <Step title="Create Skills Symlink">
        Make skills discoverable:

        ```bash theme={null}
        rm -rf ~/.config/opencode/skills/superpowers
        ln -s ~/.config/opencode/superpowers/skills ~/.config/opencode/skills/superpowers
        ```
      </Step>

      <Step title="Restart OpenCode">
        Restart OpenCode to load the plugin and discover skills.
      </Step>

      <Step title="Verify Installation">
        Check both symlinks:

        ```bash theme={null}
        ls -l ~/.config/opencode/plugins/superpowers.js
        ls -l ~/.config/opencode/skills/superpowers
        ```

        Both should show symlinks pointing to the superpowers directory.

        Ask OpenCode:

        ```text theme={null}
        Do you have superpowers?
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows (PowerShell)">
    <Steps>
      <Step title="Clone Superpowers">
        Open PowerShell (as Administrator or with Developer Mode enabled):

        ```powershell theme={null}
        git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.config\opencode\superpowers"
        ```

        <Warning>
          Windows symlinks require Developer Mode enabled OR running as Administrator.
        </Warning>
      </Step>

      <Step title="Create Directories">
        ```powershell theme={null}
        New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
        New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"
        ```
      </Step>

      <Step title="Remove Existing Links">
        Safe for reinstalls:

        ```powershell theme={null}
        Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
        Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers" -Force -ErrorAction SilentlyContinue
        ```
      </Step>

      <Step title="Create Plugin Symlink">
        ```powershell theme={null}
        New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\superpowers.js" -Target "$env:USERPROFILE\.config\opencode\superpowers\.opencode\plugins\superpowers.js"
        ```
      </Step>

      <Step title="Create Skills Junction">
        ```powershell theme={null}
        New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\superpowers" -Target "$env:USERPROFILE\.config\opencode\superpowers\skills"
        ```

        <Note>
          Junctions work like symlinks but don't require special permissions.
        </Note>
      </Step>

      <Step title="Restart OpenCode">
        Close and restart OpenCode completely.
      </Step>

      <Step title="Verify Installation">
        ```powershell theme={null}
        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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows (Command Prompt)">
    <Steps>
      <Step title="Clone Superpowers">
        Run Command Prompt as Administrator:

        ```cmd theme={null}
        git clone https://github.com/obra/superpowers.git "%USERPROFILE%\.config\opencode\superpowers"
        ```
      </Step>

      <Step title="Create Directories">
        ```cmd theme={null}
        mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
        mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul
        ```
      </Step>

      <Step title="Remove Existing Links">
        ```cmd theme={null}
        del "%USERPROFILE%\.config\opencode\plugins\superpowers.js" 2>nul
        rmdir "%USERPROFILE%\.config\opencode\skills\superpowers" 2>nul
        ```
      </Step>

      <Step title="Create Plugin Symlink">
        ```cmd theme={null}
        mklink "%USERPROFILE%\.config\opencode\plugins\superpowers.js" "%USERPROFILE%\.config\opencode\superpowers\.opencode\plugins\superpowers.js"
        ```
      </Step>

      <Step title="Create Skills Junction">
        ```cmd theme={null}
        mklink /J "%USERPROFILE%\.config\opencode\skills\superpowers" "%USERPROFILE%\.config\opencode\superpowers\skills"
        ```
      </Step>

      <Step title="Restart OpenCode">
        Close and restart OpenCode.
      </Step>

      <Step title="Verify Installation">
        ```cmd theme={null}
        dir /AL "%USERPROFILE%\.config\opencode\plugins"
        dir /AL "%USERPROFILE%\.config\opencode\skills"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows (Git Bash)">
    <Note>
      Git Bash's `ln` command copies files instead of creating symlinks. Use `cmd //c mklink` instead.
    </Note>

    <Steps>
      <Step title="Clone Superpowers">
        ```bash theme={null}
        git clone https://github.com/obra/superpowers.git ~/.config/opencode/superpowers
        ```
      </Step>

      <Step title="Create Directories">
        ```bash theme={null}
        mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
        ```
      </Step>

      <Step title="Remove Existing Links">
        ```bash theme={null}
        rm -f ~/.config/opencode/plugins/superpowers.js 2>/dev/null
        rm -rf ~/.config/opencode/skills/superpowers 2>/dev/null
        ```
      </Step>

      <Step title="Create Plugin Symlink">
        ```bash theme={null}
        cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/superpowers.js)\" \"$(cygpath -w ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js)\""
        ```
      </Step>

      <Step title="Create Skills Junction">
        ```bash theme={null}
        cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/superpowers)\" \"$(cygpath -w ~/.config/opencode/superpowers/skills)\""
        ```
      </Step>

      <Step title="Restart OpenCode">
        Close and restart OpenCode.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

<Steps>
  <Step title="List Available Skills">
    ```text theme={null}
    use skill tool to list skills
    ```

    This shows all discovered skills including Superpowers.
  </Step>

  <Step title="Load a Specific Skill">
    ```text theme={null}
    use skill tool to load superpowers/brainstorming
    ```

    Explicitly load a skill by its path.
  </Step>

  <Step title="Automatic Activation">
    Skills activate automatically based on context:

    ```text theme={null}
    Help me design a new feature for user authentication
    ```

    The agent should automatically load the brainstorming skill.
  </Step>
</Steps>

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

<Steps>
  <Step title="Create Skill Directory">
    ```bash theme={null}
    mkdir -p ~/.config/opencode/skills/my-skill
    ```
  </Step>

  <Step title="Write Skill File">
    Create `~/.config/opencode/skills/my-skill/SKILL.md`:

    ```markdown theme={null}
    ---
    name: my-skill
    description: Use when [condition] - [what it does]
    ---

    # My Skill

    [Your skill instructions here]
    ```
  </Step>

  <Step title="Restart OpenCode">
    Restart to discover the new skill.
  </Step>
</Steps>

## Creating Project Skills

Add project-specific skills in your repository:

```bash theme={null}
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:

```bash theme={null}
cd ~/.config/opencode/superpowers
git pull
```

Restart OpenCode to load updates.

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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?"
  </Accordion>
</AccordionGroup>

## Testing Your Installation

Verify everything works:

```bash theme={null}
# 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:

```bash theme={null}
rm ~/.config/opencode/plugins/superpowers.js
rm ~/.config/opencode/skills/superpowers
```

**Windows (PowerShell):**

```powershell theme={null}
Remove-Item "$env:USERPROFILE\.config\opencode\plugins\superpowers.js"
Remove-Item "$env:USERPROFILE\.config\opencode\skills\superpowers"
```

Optionally delete the clone:

```bash theme={null}
rm -rf ~/.config/opencode/superpowers
```

**Windows (PowerShell):**

```powershell theme={null}
Remove-Item -Recurse -Force "$env:USERPROFILE\.config\opencode\superpowers"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/getting-started/quick-start">
    Learn the Superpowers workflow
  </Card>

  <Card title="Skills Reference" icon="book" href="/skills/overview">
    Browse all available skills
  </Card>

  <Card title="Writing Skills" icon="pen" href="/customization/writing-skills">
    Create custom skills
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>