# Superpowers Plugin Configuration: Core Components and Architecture

> Explore the eight core components of Superpowers plugin configuration including front-matter extractor path normalizer and factory function to enhance your OpenCodeai chat sessions.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: architecture
- Published: 2026-02-16

---

**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`](https://github.com/obra/superpowers/blob/main/.opencode/plugins/superpowers.js), the plugin imports essential Node.js modules and captures `__dirname` to resolve relative paths:

```javascript
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:

```javascript
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:

```javascript
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`)

```javascript
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`](https://github.com/obra/superpowers/blob/main/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.

```javascript
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.

```bash
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`](https://github.com/obra/superpowers/blob/main/.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`](https://github.com/obra/superpowers/blob/main/.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.