Auto-register skills from plugin, simplify OpenCode install to one line

The plugin's new `config` hook injects the skills directory into
OpenCode's live config singleton, so skills are discovered automatically
without symlinks or manual config edits.

Installation is now just adding one line to opencode.json:
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]

Rewrote docs/README.opencode.md and .opencode/INSTALL.md to reflect
the new approach, removing ~200 lines of platform-specific symlink
instructions. Added migration notes for existing users.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.opencode/INSTALL.md

@@ -3,119 +3,71 @@
 ## Prerequisites
 
 - [OpenCode.ai](https://opencode.ai) installed
-- Git installed
 
-## Installation Steps
+## Installation
 
-> **Custom config directory:** If you've set `OPENCODE_CONFIG_DIR`, the commands below will use it automatically. Otherwise they default to `~/.config/opencode`.
+Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
 
-### 1. Clone Superpowers
+```json
-
+{
-```bash
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+}
-git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
 ```
 
-### 2. Register the Plugin
+Restart OpenCode. That's it — the plugin auto-installs and registers all skills.
 
-Create a symlink so OpenCode discovers the plugin:
+Verify by asking: "Tell me about your superpowers"
+
+## Migrating from the old symlink-based install
+
+If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+# Remove old symlinks
-mkdir -p "$OPENCODE_CONFIG_DIR/plugins"
+rm -f ~/.config/opencode/plugins/superpowers.js
-rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+rm -rf ~/.config/opencode/skills/superpowers
-ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+
+# Optionally remove the cloned repo
+rm -rf ~/.config/opencode/superpowers
+
+# Remove skills.paths from opencode.json if you added one for superpowers
 ```
 
-### 3. Symlink Skills
+Then follow the installation steps above.
-
-Create a symlink so OpenCode's native skill tool discovers superpowers skills:
-
-```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
-mkdir -p "$OPENCODE_CONFIG_DIR/skills"
-rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
-ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
-```
-
-### 4. Restart OpenCode
-
-Restart OpenCode. The plugin will automatically inject superpowers context.
-
-Verify by asking: "do you have superpowers?"
 
 ## Usage
 
-### Finding Skills
+Use OpenCode's native `skill` tool:
-
-Use OpenCode's native `skill` tool to list available skills:
 
 ```
 use skill tool to list skills
-```
-
-### Loading a Skill
-
-Use OpenCode's native `skill` tool to load a specific skill:
-
-```
 use skill tool to load superpowers/brainstorming
 ```
 
-### Personal Skills
-
-Create your own skills in your OpenCode skills directory:
-
-```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
-mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
-```
-
-Create a `SKILL.md` in that directory:
-
-```markdown
----
-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
 
-```bash
+Superpowers updates automatically when you restart OpenCode.
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+
-cd "$OPENCODE_CONFIG_DIR/superpowers"
+To pin a specific version:
-git pull
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+}
 ```
 
 ## Troubleshooting
 
 ### Plugin not loading
 
-```bash
+1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+2. Verify the plugin line in your `opencode.json`
-ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+3. Make sure you're running a recent version of OpenCode
-ls "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js"
-```
 
 ### Skills not found
 
-```bash
+1. Use `skill` tool to list what's discovered
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+2. Check that the plugin is loading (see above)
-ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
-```
-
-Verify the symlink points to `$OPENCODE_CONFIG_DIR/superpowers/skills`. Use `skill` tool to list what's discovered.
 
 ### Tool mapping
 

.opencode/plugins/superpowers.js

@@ -2,7 +2,7 @@
  * Superpowers plugin for OpenCode.ai
  *
  * Injects superpowers bootstrap context via system prompt transform.
- * Skills are discovered via OpenCode's native skill tool from symlinked directory.
+ * Auto-registers skills directory via config hook (no symlinks needed).
  */
 
 import path from 'path';
@@ -84,6 +84,18 @@ ${toolMapping}
   };
 
   return {
+    // Inject skills path into live config so OpenCode discovers superpowers skills
+    // without requiring manual symlinks or config file edits.
+    // This works because Config.get() returns a cached singleton — modifications
+    // here are visible when skills are lazily discovered later.
+    config: async (config) => {
+      config.skills = config.skills || {};
+      config.skills.paths = config.skills.paths || [];
+      if (!config.skills.paths.includes(superpowersSkillsDir)) {
+        config.skills.paths.push(superpowersSkillsDir);
+      }
+    },
+
     // Use system prompt transform to inject bootstrap (fixes #226 agent reset bug)
     'experimental.chat.system.transform': async (_input, output) => {
       const bootstrap = getBootstrapContent();

docs/README.opencode.md

@@ -2,182 +2,36 @@
 
 Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
 
-## Quick Install
+## Installation
 
-Tell OpenCode:
+Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
 
-```
+```json
-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.
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
 ```
 
-## Manual Installation
+Restart OpenCode. The plugin auto-installs via Bun and registers all skills automatically.
 
-### Prerequisites
+Verify by asking: "Tell me about your superpowers"
 
-- [OpenCode.ai](https://opencode.ai) installed
+### Migrating from the old symlink-based install
-- Git installed
 
-> **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).
+If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
-
-### macOS / Linux
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+# Remove old symlinks
+rm -f ~/.config/opencode/plugins/superpowers.js
+rm -rf ~/.config/opencode/skills/superpowers
 
-# 1. Install Superpowers (or update existing)
+# Optionally remove the cloned repo
-if [ -d "$OPENCODE_CONFIG_DIR/superpowers" ]; then
+rm -rf ~/.config/opencode/superpowers
-  cd "$OPENCODE_CONFIG_DIR/superpowers" && git pull
-else
-  git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
-fi
 
-# 2. Create directories
+# Remove skills.paths from opencode.json if you added one for superpowers
-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
 ```
 
-#### Verify Installation
+Then follow the installation steps above.
-
-```bash
-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.
-
-### Windows
-
-**Prerequisites:**
-- Git installed
-- Either **Developer Mode** enabled OR **Administrator privileges**
-  - Windows 10: Settings → Update & Security → For developers
-  - Windows 11: Settings → System → For developers
-
-Pick your shell below: [Command Prompt](#command-prompt) | [PowerShell](#powershell) | [Git Bash](#git-bash)
-
-#### Command Prompt
-
-Run as Administrator, or with Developer Mode enabled:
-
-```cmd
-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
-```
-
-#### PowerShell
-
-Run as Administrator, or with Developer Mode enabled:
-
-```powershell
-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
-```
-
-#### Git Bash
-
-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`).
-
-```bash
-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
-```
-
-#### WSL Users
-
-If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructions instead.
-
-#### Verify Installation
-
-**Command Prompt:**
-```cmd
-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:**
-```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.
-
-#### Troubleshooting Windows
-
-**"You do not have sufficient privilege" error:**
-- Enable Developer Mode in Windows Settings, OR
-- Right-click your terminal → "Run as Administrator"
-
-**"Cannot create a file when that file already exists":**
-- Run the removal commands (step 3) first, then retry
-
-**Symlinks not working after git clone:**
-- Run `git config --global core.symlinks true` and re-clone
 
 ## Usage
 
@@ -191,22 +45,19 @@ use skill tool to list skills
 
 ### Loading a Skill
 
-Use OpenCode's native `skill` tool to load a specific skill:
-
 ```
 use skill tool to load superpowers/brainstorming
 ```
 
 ### Personal Skills
 
-Create your own skills in your OpenCode skills directory:
+Create your own skills in `~/.config/opencode/skills/`:
 
 ```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p ~/.config/opencode/skills/my-skill
-mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create a `SKILL.md` in that directory:
+Create `~/.config/opencode/skills/my-skill/SKILL.md`:
 
 ```markdown
 ---
@@ -221,125 +72,59 @@ description: Use when [condition] - [what it does]
 
 ### Project Skills
 
-Create project-specific skills in your OpenCode project:
+Create project-specific skills in `.opencode/skills/` within your project.
 
-```bash
+**Skill Priority:** Project skills > Personal skills > Superpowers skills
-# In your OpenCode project
+
-mkdir -p .opencode/skills/my-project-skill
+## 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:
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+}
 ```
 
-Create `.opencode/skills/my-project-skill/SKILL.md`:
+## How It Works
 
-```markdown
+The plugin does two things:
----
-name: my-project-skill
-description: Use when [condition] - [what it does]
----
 
-# My Project Skill
+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.
-[Your skill content here]
-```
-
-## Skill Locations
-
-OpenCode discovers skills from these locations:
-
-1. **Project skills** (`.opencode/skills/`) - Highest priority
-2. **Personal skills** (`~/.config/opencode/skills/`)
-3. **Superpowers skills** (`~/.config/opencode/skills/superpowers/`) - via symlink
-
-## Features
-
-### Automatic Context Injection
-
-The 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.
-
-### Native Skills Integration
-
-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.
 
 ### Tool Mapping
 
-Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:
+Skills written for Claude Code are automatically adapted for OpenCode:
 
 - `TodoWrite` → `todowrite`
 - `Task` with subagents → OpenCode's `@mention` system
 - `Skill` tool → OpenCode's native `skill` tool
 - File operations → Native OpenCode tools
 
-## Architecture
-
-### Plugin Structure
-
-**Location:** `$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
-
-**Components:**
-- `experimental.chat.system.transform` hook for bootstrap injection
-- Reads and injects the "using-superpowers" skill content
-
-### Skills
-
-**Location:** `$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.
-
-## Updating
-
-```bash
-OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
-cd "$OPENCODE_CONFIG_DIR/superpowers"
-git pull
-```
-
-Restart OpenCode to load the updates.
-
 ## Troubleshooting
 
 ### Plugin not loading
 
-1. Check plugin exists: `ls $OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
+1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
-2. Check symlink/junction: `ls -l $OPENCODE_CONFIG_DIR/plugins/` (macOS/Linux) or `dir /AL "%OPENCODE_CONFIG_DIR%\plugins"` (Windows)
+2. Verify the plugin line in your `opencode.json` is correct
-3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`
+3. Make sure you're running a recent version of OpenCode
-4. Look for plugin loading message in logs
 
 ### Skills not found
 
-1. Verify skills symlink: `ls -l $OPENCODE_CONFIG_DIR/skills/superpowers` (should point to superpowers/skills/)
+1. Use OpenCode's `skill` tool to list available skills
-2. Use OpenCode's `skill` tool to list available skills
+2. Check that the plugin is loading (see above)
-3. Check skill structure: each skill needs a `SKILL.md` file with valid frontmatter
+3. Each skill needs a `SKILL.md` file with valid YAML frontmatter
-
-### Windows: Module not found error
-
-If you see `Cannot find module` errors on Windows:
-- **Cause:** Git Bash `ln -sf` copies files instead of creating symlinks
-- **Fix:** Use `mklink /J` directory junctions instead (see Windows installation steps)
 
 ### Bootstrap not appearing
 
-1. Verify using-superpowers skill exists: `ls $OPENCODE_CONFIG_DIR/superpowers/skills/using-superpowers/SKILL.md`
+1. Check OpenCode version supports `experimental.chat.system.transform` hook
-2. Check OpenCode version supports `experimental.chat.system.transform` hook
+2. Restart OpenCode after config changes
-3. Restart OpenCode after plugin changes
 
 ## Getting Help
 
 - Report issues: https://github.com/obra/superpowers/issues
 - Main documentation: https://github.com/obra/superpowers
 - OpenCode docs: https://opencode.ai/docs/
-
-## Testing
-
-Verify your installation:
-
-```bash
-# 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/`.

package.json

@@ -0,0 +1,6 @@
+{
+  "name": "superpowers",
+  "version": "5.0.3",
+  "type": "module",
+  "main": ".opencode/plugins/superpowers.js"
+}