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

# Plugin System

> How plugins package and distribute Superpowers across platforms

# Plugin System

Plugins are platform-specific packages that integrate Superpowers with different AI coding tools. Each platform has unique requirements for how plugins are structured, distributed, and installed.

## Plugin Manifest Formats

Superpowers includes manifests for four platforms, each with different capabilities and installation methods.

### Claude Code Plugin

**Location**: `.claude-plugin/plugin.json`

```json theme={null}
{
  "name": "superpowers",
  "displayName": "Superpowers",
  "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
  "version": "4.3.1",
  "author": {
    "name": "Jesse Vincent",
    "email": "jesse@fsck.com"
  },
  "homepage": "https://github.com/obra/superpowers",
  "repository": "https://github.com/obra/superpowers",
  "license": "MIT",
  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"],
  "skills": "skills directory path",
  "agents": "agents directory path",
  "commands": "commands directory path",
  "hooks": "hooks configuration path"
}
```

<Accordion title="Field Descriptions">
  * **`name`**: Unique plugin identifier (lowercase, no spaces)
  * **`displayName`**: Human-readable name shown in UI
  * **`description`**: Short description (under 100 chars)
  * **`version`**: Semantic version (MAJOR.MINOR.PATCH)
  * **`author`**: Author name and email
  * **`homepage`**: Plugin website/documentation URL
  * **`repository`**: Source code repository URL
  * **`license`**: SPDX license identifier
  * **`keywords`**: Searchable tags for marketplace
  * **`skills`**: Relative path to skills directory
  * **`agents`**: Relative path to agents directory
  * **`commands`**: Relative path to commands directory
  * **`hooks`**: Relative path to hooks configuration
</Accordion>

<Note>
  Claude Code **automatically registers** all resources (skills, agents, commands, hooks) from the paths specified in `plugin.json`.
</Note>

### Cursor Plugin

**Location**: `.cursor-plugin/plugin.json`

```json theme={null}
{
  "name": "superpowers",
  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
  "version": "4.3.1",
  "author": {
    "name": "Jesse Vincent",
    "email": "jesse@fsck.com"
  },
  "homepage": "https://github.com/obra/superpowers",
  "repository": "https://github.com/obra/superpowers",
  "license": "MIT",
  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
}
```

<Warning>
  Cursor's plugin format is **simpler** than Claude Code's - it doesn't support explicit path declarations for skills/agents/commands/hooks. Cursor uses convention-based discovery.
</Warning>

### OpenCode Plugin

**Location**: `.opencode/plugins/superpowers.js`

OpenCode uses a **JavaScript plugin** with code-based integration:

```javascript theme={null}
import path from 'path';
import fs from 'fs';
import os from 'os';
import { fileURLToPath } from 'url';

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

// Simple frontmatter extraction
const extractAndStripFrontmatter = (content) => {
  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
  if (!match) return { frontmatter: {}, content };
  
  const frontmatterStr = match[1];
  const body = match[2];
  const frontmatter = {};
  
  for (const line of frontmatterStr.split('\n')) {
    const colonIdx = line.indexOf(':');
    if (colonIdx > 0) {
      const key = line.slice(0, colonIdx).trim();
      const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
      frontmatter[key] = value;
    }
  }
  
  return { frontmatter, content: body };
};

export const SuperpowersPlugin = async ({ client, directory }) => {
  const homeDir = os.homedir();
  const superpowersSkillsDir = path.resolve(__dirname, '../../skills');
  const configDir = path.join(homeDir, '.config/opencode');
  
  // Helper to generate bootstrap content
  const getBootstrapContent = () => {
    const skillPath = path.join(superpowersSkillsDir, 'using-superpowers', 'SKILL.md');
    if (!fs.existsSync(skillPath)) return null;
    
    const fullContent = fs.readFileSync(skillPath, 'utf8');
    const { content } = extractAndStripFrontmatter(fullContent);
    
    const toolMapping = `**Tool Mapping for OpenCode:**
When skills reference tools you don't have, substitute OpenCode equivalents:
- \`TodoWrite\` → \`update_plan\`
- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
- \`Skill\` tool → OpenCode's native \`skill\` tool
- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools

**Skills location:**
Superpowers skills are in the config skills superpowers directory
Use OpenCode's native \`skill\` tool to list and load skills.`;
    
    return `<EXTREMELY_IMPORTANT>
You have superpowers.

**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED.**

${content}

${toolMapping}
</EXTREMELY_IMPORTANT>`;
  };
  
  return {
    // Use system prompt transform to inject bootstrap
    'experimental.chat.system.transform': async (_input, output) => {
      const bootstrap = getBootstrapContent();
      if (bootstrap) {
        (output.system ||= []).push(bootstrap);
      }
    }
  };
};
```

<Accordion title="How OpenCode Plugin Works">
  1. **Export named function**: `SuperpowersPlugin` is the entry point
  2. **Receive context**: Gets `{ client, directory }` parameters
  3. **Read skill content**: Loads the using-superpowers SKILL.md file
  4. **Strip frontmatter**: Removes YAML metadata
  5. **Add tool mapping**: Translates tool names for OpenCode
  6. **Return hooks object**: Registers system prompt transform
  7. **Transform executes**: Injects content at session start
</Accordion>

<Note>
  OpenCode plugins use **experimental hooks** (`experimental.chat.system.transform`) because OpenCode doesn't have built-in hooks support.
</Note>

### Codex (No Plugin)

Codex doesn't have a plugin system - it uses **direct symlink discovery**:

**Installation**: `.codex/INSTALL.md`

```markdown theme={null}
# Installing Superpowers for Codex

1. Clone the repository to your codex superpowers directory

2. Create the skills symlink in your agents skills directory

3. Restart Codex to discover the skills.
```

<Warning>
  Codex has **no hooks support** - cannot inject context at session start. Users must manually load the `using-superpowers` skill in each session.
</Warning>

## Distribution Methods

### Marketplace (Claude Code, Cursor)

<Steps>
  <Step title="Create Marketplace Repository">
    Create a Git repository with `marketplace.json`:

    ```json theme={null}
    {
      "name": "superpowers-dev",
      "description": "Development marketplace for Superpowers",
      "owner": {
        "name": "Jesse Vincent",
        "email": "jesse@fsck.com"
      },
      "plugins": [
        {
          "name": "superpowers",
          "description": "Core skills library",
          "version": "4.3.1",
          "source": "current directory",
          "author": {
            "name": "Jesse Vincent",
            "email": "jesse@fsck.com"
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Register Marketplace">
    Users register your marketplace using the plugin marketplace add command with the repository path
  </Step>

  <Step title="Install Plugin">
    Users install from marketplace using the plugin install command
  </Step>

  <Step title="Automatic Updates">
    Platforms automatically check for updates using the plugin update command
  </Step>
</Steps>

### Manual Installation (OpenCode, Codex)

<Steps>
  <Step title="Clone Repository">
    Clone the repository to the appropriate config directory for your platform
  </Step>

  <Step title="Create Symlinks">
    Create symlinks for plugins and skills directories in the platform config location
  </Step>

  <Step title="Restart Platform">
    Restart the AI coding tool to discover new resources.
  </Step>

  <Step title="Manual Updates">
    Navigate to the installation directory and run git pull to update
  </Step>
</Steps>

## Creating a Plugin for a New Platform

### Step 1: Analyze Platform Capabilities

<CardGroup cols={2}>
  <Card title="Plugin System" icon="puzzle-piece">
    Does the platform support plugins? If yes, what format?
  </Card>

  <Card title="Skill Discovery" icon="magnifying-glass">
    How does the platform discover skills? Automatic or manual?
  </Card>

  <Card title="Hooks Support" icon="link">
    Does the platform support lifecycle hooks?
  </Card>

  <Card title="Commands" icon="terminal">
    Can users register custom slash commands?
  </Card>
</CardGroup>

### Step 2: Choose Integration Method

<Accordion title="Full Plugin Support (Claude Code style)">
  If the platform has:

  * Plugin manifest format
  * Automatic resource discovery
  * Hooks support
  * Marketplace distribution

  **Create**: `.platform-name-plugin/plugin.json` with paths:

  ```json theme={null}
  {
    "skills": "skills directory path",
    "agents": "agents directory path",
    "commands": "commands directory path",
    "hooks": "hooks configuration path"
  }
  ```
</Accordion>

<Accordion title="Hybrid Plugin (OpenCode style)">
  If the platform has:

  * Plugin code execution
  * System prompt hooks
  * Manual symlink setup

  **Create**: `.platform-name/plugins/superpowers.js` with:

  * Bootstrap injection via system hooks
  * Tool name mapping for platform
  * Skills symlink instructions
</Accordion>

<Accordion title="Manual Symlink (Codex style)">
  If the platform has:

  * Native skill discovery
  * No plugin system
  * No hooks

  **Create**: `.platform-name/INSTALL.md` with:

  * Git clone instructions
  * Symlink setup to skills directory
  * Manual loading instructions
</Accordion>

### Step 3: Create Platform-Specific Directory

Create a directory with the platform name and plugin suffix

### Step 4: Write Plugin Manifest or Code

**For JSON manifests** (Claude Code, Cursor):

```json theme={null}
{
  "name": "superpowers",
  "displayName": "Superpowers",
  "description": "Core skills library: TDD, debugging, collaboration patterns",
  "version": "4.3.1",
  "author": {
    "name": "Jesse Vincent",
    "email": "jesse@fsck.com"
  },
  "repository": "https://github.com/obra/superpowers",
  "license": "MIT",
  "skills": "skills directory path",
  "agents": "agents directory path",
  "commands": "commands directory path",
  "hooks": "hooks configuration path"
}
```

**For code plugins** (OpenCode):

```javascript theme={null}
export const SuperpowersPlugin = async ({ client, directory }) => {
  // Load using-superpowers skill
  const bootstrap = loadSkillContent('using-superpowers');
  
  // Add platform-specific tool mapping
  const toolMapping = mapToolsForPlatform(client.platform);
  
  // Return hooks
  return {
    'system.prompt.transform': async (_input, output) => {
      output.system.push(bootstrap + toolMapping);
    }
  };
};
```

### Step 5: Write Installation Instructions

**Create** a platform-specific INSTALL.md file with:

```markdown theme={null}
# Installing Superpowers for Platform Name

## Prerequisites
- Platform Name installed
- Git installed

## Installation

1. Clone repository to the platform directory

2. Follow platform-specific setup steps

3. Restart platform

## Verify

Ask: "do you have superpowers?"

## Updating

Navigate to the installation directory and run git pull
```

### Step 6: Test Installation

<Steps>
  <Step title="Test Clean Install">
    On a fresh system, follow your installation instructions exactly.
  </Step>

  <Step title="Test Skill Loading">
    Verify skills are discovered and loadable.
  </Step>

  <Step title="Test Hook Execution">
    If hooks supported, verify SessionStart hook injects context.
  </Step>

  <Step title="Test Updates">
    Modify a skill, run update command, verify changes appear.
  </Step>
</Steps>

### Step 7: Submit Pull Request

Contribute your platform support back to Superpowers:

1. Fork the repository
2. Create branch: `git checkout -b platform/platform-name`
3. Add platform directory and files
4. Update main README.md with installation section
5. Submit PR with:
   * Platform name and link
   * Installation instructions
   * Known limitations
   * Testing notes

## Plugin Packaging Best Practices

**Use Semantic Versioning**: Follow SemVer (MAJOR.MINOR.PATCH) - MAJOR for breaking changes, MINOR for new features (backward compatible), PATCH for bug fixes.

**Keep Manifests Minimal**: Only include necessary fields like name, description, version, author, and repository.

**Use Relative Paths**: Always use relative paths with dot-slash prefix to ensure cross-platform compatibility.

**Test Cross-Platform**: If hooks are supported, test on both Windows and Unix systems to ensure compatibility.

## Platform Comparison Matrix

| Feature             | Claude Code    | Cursor         | OpenCode        | Codex         |
| ------------------- | -------------- | -------------- | --------------- | ------------- |
| **Plugin Manifest** | ✅ JSON         | ✅ JSON         | ✅ JavaScript    | ❌ None        |
| **Marketplace**     | ✅ Yes          | ✅ Yes          | ❌ No            | ❌ No          |
| **Auto-Discovery**  | ✅ Yes          | ✅ Yes          | ⚠️ Partial      | ✅ Skills only |
| **Hooks System**    | ✅ Yes          | ✅ Yes          | ⚠️ Experimental | ❌ No          |
| **Auto-Updates**    | ✅ Yes          | ✅ Yes          | ❌ Manual        | ❌ Manual      |
| **Commands**        | ✅ Yes          | ✅ Yes          | ✅ Yes           | ⚠️ Limited    |
| **Agents**          | ✅ Yes          | ✅ Yes          | ✅ Yes           | ✅ Yes         |
| **Installation**    | 🎯 Marketplace | 🎯 Marketplace | 🔧 Manual       | 🔧 Manual     |

## Troubleshooting Plugin Issues

### Plugin Not Loading

<Accordion title="Check manifest syntax">
  Validate JSON with jq to check for syntax errors like missing commas, trailing commas, or unescaped quotes.
</Accordion>

<Accordion title="Verify file paths">
  Check that all referenced paths exist by listing them with ls -la for skills, agents, commands, and hooks directories.
</Accordion>

<Accordion title="Check platform logs">
  * **Claude Code**: `/debug logs`
  * **Cursor**: Developer Console
  * **OpenCode**: Check terminal output
</Accordion>

### Skills Not Discovered

<Accordion title="Verify symlinks">
  Check that the symlink points to the correct location in your config or agents directory.
</Accordion>

<Accordion title="Check SKILL.md format">
  Each skill needs valid frontmatter:

  ```markdown theme={null}
  ---
  name: skill-name
  description: When to use this skill
  ---

  # Skill Content
  ```
</Accordion>

### Hooks Not Running

<Accordion title="Test hook directly">
  Run the hook script directly and verify it outputs valid JSON.
</Accordion>

<Accordion title="Check hooks.json">
  Validate the hooks JSON file using jq to check syntax and verify matcher pattern and command path.
</Accordion>

<Accordion title="Verify hook permissions">
  Ensure hook scripts have execute permissions using chmod +x on the hook files
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/development/architecture">
    Understand overall system architecture
  </Card>

  <Card title="Hooks System" icon="link" href="/development/hooks-system">
    Learn how hooks work in detail
  </Card>

  <Card title="Creating Skills" icon="wand-magic-sparkles" href="/guides/creating-skills">
    Write skills that plugins distribute
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/contributing">
    Contribute platform support
  </Card>
</CardGroup>