[OpenCode] `skill` tool returns "Available skills: none" — `config` hook silently ignored by OpenCode plugin API

[NicoGenti]

• I searched existing issues and this is not a duplicate

Environment

Field	Value
Superpowers version	5.0.6
Harness (Claude Code, Cursor, etc.)	OpenCode
Harness version	1.4.0 (@opencode-ai/plugin), internal build 21
Model	claude-sonnet-4.6 (via github-copilot provider)
OS + shell	Windows 11, PowerShell

Is this a Superpowers issue or a platform issue?

• I confirmed this issue does not occur without Superpowers installed

Note: This is a platform-level incompatibility — the config hook returned by the superpowers plugin is not a registered hook in the current OpenCode plugin API, so it is silently ignored. The issue manifests through superpowers but the fix likely requires either updating the plugin or documenting the manual workaround. Related to #1068 (different root cause, same symptom on Windows).

What happened?

After installing superpowers via the recommended method in opencode.json:

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}
Running use skill tool to list skills returns:
Skill "list" not found. Available skills: none
The bootstrap system prompt (injected via experimental.chat.system.transform) works correctly — the agent is aware of superpowers. Only skill discovery is broken.
Steps to reproduce
1. Add superpowers to global ~/.config/opencode/opencode.json via the plugin array (official method)
2. Restart OpenCode
3. Run: use skill tool to list skills
4. Observe: Available skills: none
Expected behavior
OpenCode's skill tool lists all 14 superpowers skills (tdd, systematic-debugging, writing-plans, etc.), as documented in README.opencode.md and INSTALL.md.
Actual behavior
The skill tool returns Available skills: none. The plugin loads (bootstrap works), but the skills/ directory is never registered.
Debug log or conversation transcript
Root cause identified via source inspection of OpenCode's plugin loader (packages/opencode/src/plugin/index.ts):
The plugin returns a config hook to register the skills path:
return {
  config: async (config) => {
    config.skills = config.skills || {};
    config.skills.paths = config.skills.paths || [];
    config.skills.paths.push(superpowersSkillsDir);
  },
  'experimental.chat.system.transform': async (_input, output) => { ... }
};
config is not a registered hook name in OpenCode's plugin API. The runtime iterates known hooks and silently skips unknown keys — no error, no warning. superpowersSkillsDir is never added to the live config.
Workaround (confirmed working): add skills.paths manually to opencode.json:
{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"],
  "skills": {
    "paths": ["C:\\Users\\<user>\\.cache\\opencode\\node_modules\\superpowers\\skills"]
  }
}
After restarting OpenCode, use skill tool to list skills correctly returns all 14 skills.

[DhanushS-11]

Root Cause Analysis

The issue has two layers, both now fully understood:

Layer 1 — The config hook doesn't exist in OpenCode's plugin API.

The plugin returns a config key in its hooks object, attempting to mutate a live config object to inject skills.paths. But OpenCode's plugin loader (packages/opencode/src/plugin/index.ts) only recognizes specific hook names (experimental.chat.system.transform, tool, event, auth, etc.). Unknown keys are silently skipped. So superpowersSkillsDir is never registered.

Layer 2 — OpenCode doesn't need skills.paths at all.

As the [OpenCode skills docs](https://opencode.ai/docs/skills/) show, skill discovery is entirely filesystem-based — it scans a fixed set of hardcoded paths:

• ~/.config/opencode/skills/*/SKILL.md (global)
• .opencode/skills/*/SKILL.md (project-local, walked up to git root)
• ~/.claude/skills/*/SKILL.md, ~/.agents/skills/*/SKILL.md, etc.

There is no skills.paths config key in OpenCode at all. The workaround in the issue accidentally works because OpenCode reads that field... wait — actually, re-reading the docs, it doesn't read a skills.paths config. The workaround works for a different reason: when OpenCode installs the npm package to ~/.cache/opencode/node_modules/superpowers/, and the user adds that path, OpenCode's skill tool scans it only if it happens to fall under one of its discovery roots — which it won't by default. The workaround "works" only because the user is coincidentally symlinking into a scanned path.

The real fix: The plugin should use the experimental.chat.system.transform hook (which already works) to also inject skill content, and/or create a symlink into ~/.config/opencode/skills/ at install/first-run time — which is exactly what the older installation approach did manually. The cleanest solution is to create the symlink programmatically from within the plugin at startup using the event hook or the plugin's initialization phase.

---

The Fix

The plugin already has access to the filesystem via Node/Bun APIs. On first load, it should symlink (or copy on Windows, since Windows symlinks require elevated permissions) the skills/ directory into ~/.config/opencode/skills/superpowers — the global discovery path OpenCode always scans.

Here's the proposed patch for .opencode/plugins/superpowers.js:

// At plugin initialization (top-level async, before returning hooks):

import path from 'path';
import fs from 'fs';
import os from 'os';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Resolve the superpowers skills directory (two levels up from .opencode/plugins/)
const superpowersSkillsDir = path.resolve(__dirname, '../../skills');

// Resolve OpenCode's global skills discovery root
const configDir = process.env.OPENCODE_CONFIG_DIR 
  ?? path.join(os.homedir(), '.config', 'opencode');
const globalSkillsDir = path.join(configDir, 'skills');
const skillsLinkTarget = path.join(globalSkillsDir, 'superpowers');

function ensureSkillsRegistered() {
  try {
    fs.mkdirSync(globalSkillsDir, { recursive: true });

    // Check if already linked/copied and still valid
    let existing = null;
    try { existing = fs.lstatSync(skillsLinkTarget); } catch {}

    if (existing) {
      if (existing.isSymbolicLink()) {
        const resolved = fs.readlinkSync(skillsLinkTarget);
        if (resolved === superpowersSkillsDir) return; // already correct
        fs.unlinkSync(skillsLinkTarget); // stale link, re-create
      } else if (existing.isDirectory()) {
        return; // user-managed directory, don't touch it
      }
    }

    try {
      // Prefer symlink (works on macOS/Linux and Windows with Developer Mode)
      fs.symlinkSync(superpowersSkillsDir, skillsLinkTarget, 'junction');
    } catch (symlinkErr) {
      // Fallback for Windows without Developer Mode: shallow directory copy
      fs.mkdirSync(skillsLinkTarget, { recursive: true });
      for (const entry of fs.readdirSync(superpowersSkillsDir)) {
        const src = path.join(superpowersSkillsDir, entry);
        const dst = path.join(skillsLinkTarget, entry);
        if (fs.statSync(src).isDirectory()) {
          fs.cpSync(src, dst, { recursive: true });
        }
      }
    }
  } catch (err) {
    // Non-fatal: bootstrap still works, skills just won't appear in native tool
    console.warn('[superpowers] Could not register skills directory:', err.message);
  }
}

// Call at plugin load time (synchronous, fast)
ensureSkillsRegistered();

// ... rest of plugin (return hooks object with experimental.chat.system.transform)

Why junction for the symlink type?

On Windows, junction works for directories without requiring administrator privileges or Developer Mode — unlike 'dir' symlinks. On macOS/Linux, junction is ignored and a regular symlink is created.

Why not rely on the config hook?

Because it doesn't exist in the OpenCode plugin API and there's no indication it will be added. The filesystem approach is more reliable, works across all OpenCode versions, and matches what the old manual installation did.

[bakathefish]

Proposed Fix

The config hook in .opencode/plugins/superpowers.js (lines 89-95) is silently ignored by OpenCode because it doesn't recognize config as a valid hook key. Skills never register, users see "Available skills: none."

Fix: Add filesystem-based fallback

Insert this block at line 83 (before return {):

  // Filesystem fallback: ensure skills are discoverable via OpenCode's
  // default skills path, since the `config` hook may be silently ignored
  // by some OpenCode versions (see #1087).
  const ocSkillsTarget = path.join(configDir, 'skills', 'superpowers');
  if (!fs.existsSync(ocSkillsTarget)) {
    fs.mkdirSync(path.dirname(ocSkillsTarget), { recursive: true });
    try {
      // 'junction' works on Windows NTFS without admin privileges
      fs.symlinkSync(superpowersSkillsDir, ocSkillsTarget, 'junction');
    } catch {
      // Fallback: copy directory if symlink/junction fails
      fs.cpSync(superpowersSkillsDir, ocSkillsTarget, { recursive: true });
    }
  }

Why this works:

• On first plugin load, symlinks the skills directory to ~/.config/opencode/skills/superpowers/ — OpenCode's hardcoded discovery path
• Uses 'junction' type which works on Windows NTFS without admin privileges (relevant since the original reporter is on Windows 11)
• Falls back to fs.cpSync if symlink fails (e.g., on some network drives)
• The config hook is preserved as the primary path for versions of OpenCode that support it
• Idempotent — skips if the target already exists

Also update the file header comment (line 5) from "Auto-registers skills directory via config hook (no symlinks needed)." to "Auto-registers skills directory via config hook, with filesystem symlink fallback."

[moonlighf]

When will this issue be fixed?