Superpowers Plugin Configuration: Core Components and Architecture

The Superpowers plugin configuration consists of eight core components—including a front-matter extractor, path normalizer, main factory function, and system-prompt transform hook—that bootstrap the Superpowers skill-set into every OpenCode.ai chat session.

The Superpowers plugin for OpenCode.ai, maintained in the obra/superpowers repository, extends the IDE with specialized software development capabilities through a single JavaScript module. Understanding the Superpowers plugin configuration is essential for customizing skill locations, modifying tool mappings, or debugging how the plugin injects context into chat sessions.

Module Infrastructure and Path Resolution

The plugin begins by establishing its runtime environment through Node.js core modules and directory resolution.

Core Module Imports and __dirname

At lines 8‑13 of .opencode/plugins/superpowers.js, the plugin imports essential Node.js modules and captures __dirname to resolve relative paths:

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

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

This setup enables the plugin to locate skill files and configuration directories regardless of where the module is executed.

Path Normalization Utility

The normalizePath function (lines 36‑47) standardizes user-provided paths by trimming whitespace, expanding the tilde (~) to the user's home directory, and resolving to absolute paths:

const normalizePath = (inputPath) => {
  if (!inputPath) return inputPath;
  let normalized = inputPath.trim();
  if (normalized.startsWith('~')) {
    normalized = path.join(os.homedir(), normalized.slice(1));
  }
  if (!path.isAbsolute(normalized)) {
    normalized = path.resolve(normalized);
  }
  return normalized;
};

This utility is critical for handling the optional OPENCODE_CONFIG_DIR environment variable.

Content Processing Utilities

Before injecting skills into the system prompt, the plugin must parse skill files and extract their metadata.

Front-Matter Extraction

The extractAndStripFrontmatter function (lines 15‑34) removes YAML front-matter delimiters (---) from skill files and returns both the cleaned content and a parsed key-value map:

const extractAndStripFrontmatter = (content) => {
  const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
  const match = content.match(frontmatterRegex);
  
  if (!match) {
    return { content, frontmatter: {} };
  }
  
  const frontmatterText = match[1];
  const frontmatter = {};
  // Parse key: value pairs...
  
  return {
    content: content.replace(frontmatterRegex, ''),
    frontmatter
  };
};

This avoids pulling in the full Superpowers "skills-core" library just for bootstrapping.

The SuperpowersPlugin Factory

The main entry point is the SuperpowersPlugin factory function exported at line 49.

Runtime Directory Computation

When OpenCode loads the plugin, it invokes the factory with { client, directory }. The function computes several runtime directories:

• The user's home directory (os.homedir())
• The Superpowers skills folder (typically ~/.config/opencode/skills/superpowers/)
• The configuration directory (overridden via OPENCODE_CONFIG_DIR)

export const SuperpowersPlugin = async ({ client, directory }) => {
  const homeDir = os.homedir();
  const configDir = normalizePath(process.env.OPENCODE_CONFIG_DIR) || 
                    path.join(homeDir, '.config', 'opencode');
  // ... plugin setup
};

Bootstrap Content Generation

The getBootstrapContent function (lines 56‑84) loads the skills/using-superpowers/SKILL.md file, extracts its body using the front-matter utility, and assembles the bootstrap block injected into every chat session.

System Prompt Integration and Tool Mapping

The plugin ensures Superpowers-specific tools work seamlessly within OpenCode's environment.

Tool Mapping for OpenCode Compatibility

Inside the bootstrap content template (lines 64‑70), the plugin defines explicit mappings between Superpowers tool names and their OpenCode.ai equivalents:

When using tools, map Superpowers names to OpenCode:
- TodoWrite → update_plan
- Skill → skill

This translation layer ensures that skills written for the Superpowers ecosystem function correctly within the OpenCode environment without requiring manual tool name changes.

The System-Prompt Transform Hook

The plugin registers the experimental.chat.system.transform hook (lines 86‑94) to intercept every chat request. This hook injects the generated bootstrap content into the system prompt, guaranteeing that every session starts with the Superpowers context.

client.experimental.chat.system.transform(async (systemPrompt) => {
  const bootstrapContent = await getBootstrapContent();
  return systemPrompt + '\n\n' + bootstrapContent;
});

Customizing the Plugin Environment

You can override the default configuration directory using the OPENCODE_CONFIG_DIR environment variable. When set, the normalizePath utility expands any tilde (~) characters and resolves the path absolutely, allowing you to store Superpowers skills in alternative locations such as shared drives or version-controlled directories.

export OPENCODE_CONFIG_DIR=~/work/shared-opencode-config

When the plugin starts, it looks for Superpowers skills under $OPENCODE_CONFIG_DIR/skills/superpowers/ instead of the default ~/.config/opencode/skills/superpowers/.

Summary

• The Superpowers plugin configuration centers on .opencode/plugins/superpowers.js, which exports a factory function that bootstraps the plugin into OpenCode.ai.
• Utility functions extractAndStripFrontmatter (lines 15‑34) and normalizePath (lines 36‑47) handle skill file parsing and path resolution without external dependencies.
• The SuperpowersPlugin factory (line 49) computes runtime directories and supports the OPENCODE_CONFIG_DIR environment variable for custom configuration paths.
• Bootstrap content generation via getBootstrapContent (lines 56‑84) loads the using-superpowers skill and assembles tool mappings that translate Superpowers-specific tools to OpenCode equivalents.
• The system-prompt transform hook (lines 86‑94) ensures every chat session receives the Superpowers context by injecting the bootstrap block into the system prompt.

Frequently Asked Questions

What file contains the main Superpowers plugin configuration?

The main configuration logic resides in .opencode/plugins/superpowers.js within the obra/superpowers repository. This single JavaScript module exports the SuperpowersPlugin factory function and contains all utility functions, path resolution logic, and the system-prompt transform hook required to bootstrap the plugin into OpenCode.ai.

How does the plugin handle custom configuration directories?

The plugin checks for the OPENCODE_CONFIG_DIR environment variable and passes it through the normalizePath function (lines 36‑47) to resolve tilde expansions and relative paths. If set, the plugin loads Superpowers skills from $OPENCODE_CONFIG_DIR/skills/superpowers/ instead of the default ~/.config/opencode/skills/superpowers/.

What is the purpose of the tool-mapping section in the configuration?

The tool-mapping section (lines 64‑70) defines explicit translations between Superpowers-specific tool names and their OpenCode.ai equivalents, such as mapping TodoWrite to update_plan and Skill to skill. This ensures that skills written for the Superpowers ecosystem function correctly within the OpenCode environment without requiring manual tool name changes.

How is the Superpowers context injected into every chat session?

The plugin registers the experimental.chat.system.transform hook (lines 86‑94), which intercepts every chat request and appends the bootstrap content—generated by getBootstrapContent—to the system prompt. This guarantees that every new chat session initializes with the complete Superpowers skill context and tool mappings loaded.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}