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

{
  "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"
}

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

Claude Code automatically registers all resources (skills, agents, commands, hooks) from the paths specified in plugin.json.

Cursor Plugin

Location: .cursor-plugin/plugin.json

{
  "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"]
}

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.

OpenCode Plugin

Location: .opencode/plugins/superpowers.js OpenCode uses a JavaScript plugin with code-based integration:

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);
      }
    }
  };
};

How OpenCode Plugin Works

Export named function: SuperpowersPlugin is the entry point
Receive context: Gets { client, directory } parameters
Read skill content: Loads the using-superpowers SKILL.md file
Strip frontmatter: Removes YAML metadata
Add tool mapping: Translates tool names for OpenCode
Return hooks object: Registers system prompt transform
Transform executes: Injects content at session start

OpenCode plugins use experimental hooks (experimental.chat.system.transform) because OpenCode doesn’t have built-in hooks support.

Codex (No Plugin)

Codex doesn’t have a plugin system - it uses direct symlink discovery: Installation: .codex/INSTALL.md

# Installing Superpowers for Codex

Clone the repository to your codex superpowers directory

Create the skills symlink in your agents skills directory

Restart Codex to discover the skills.

Codex has no hooks support - cannot inject context at session start. Users must manually load the using-superpowers skill in each session.

Distribution Methods

Marketplace (Claude Code, Cursor)

Create Marketplace Repository

Create a Git repository with marketplace.json:

{
  "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"
      }
    }
  ]
}

Users register your marketplace using the plugin marketplace add command with the repository path

Install Plugin

Users install from marketplace using the plugin install command

Automatic Updates

Platforms automatically check for updates using the plugin update command

Manual Installation (OpenCode, Codex)

Clone Repository

Clone the repository to the appropriate config directory for your platform

Create Symlinks

Create symlinks for plugins and skills directories in the platform config location

Restart Platform

Restart the AI coding tool to discover new resources.

Manual Updates

Navigate to the installation directory and run git pull to update

Creating a Plugin for a New Platform

Step 1: Analyze Platform Capabilities

Plugin System

Does the platform support plugins? If yes, what format?

Skill Discovery

How does the platform discover skills? Automatic or manual?

Hooks Support

Does the platform support lifecycle hooks?

Commands

Can users register custom slash commands?

Step 2: Choose Integration Method

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:

{
  "skills": "skills directory path",
  "agents": "agents directory path",
  "commands": "commands directory path",
  "hooks": "hooks configuration path"
}

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

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

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):

{
  "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):

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:

# 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

Test Clean Install

On a fresh system, follow your installation instructions exactly.

Test Skill Loading

Verify skills are discovered and loadable.

Test Hook Execution

If hooks supported, verify SessionStart hook injects context.

Test Updates

Modify a skill, run update command, verify changes appear.

Step 7: Submit Pull Request

Contribute your platform support back to Superpowers:

Fork the repository
Create branch: git checkout -b platform/platform-name
Add platform directory and files
Update main README.md with installation section
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

Check manifest syntax

Validate JSON with jq to check for syntax errors like missing commas, trailing commas, or unescaped quotes.

Verify file paths

Check that all referenced paths exist by listing them with ls -la for skills, agents, commands, and hooks directories.

Check platform logs

Claude Code: /debug logs
Cursor: Developer Console
OpenCode: Check terminal output

Skills Not Discovered

Verify symlinks

Check that the symlink points to the correct location in your config or agents directory.

Check SKILL.md format

Each skill needs valid frontmatter:

---
name: skill-name
description: When to use this skill
---

# Skill Content

Hooks Not Running

Test hook directly

Run the hook script directly and verify it outputs valid JSON.

Check hooks.json

Validate the hooks JSON file using jq to check syntax and verify matcher pattern and command path.

Verify hook permissions

Ensure hook scripts have execute permissions using chmod +x on the hook files

Next Steps

Architecture

Understand overall system architecture

Hooks System

Learn how hooks work in detail

Creating Skills

Write skills that plugins distribute

Contributing

Contribute platform support

​Plugin System

​Plugin Manifest Formats

​Claude Code Plugin

​Cursor Plugin

​OpenCode Plugin

​Codex (No Plugin)

​Distribution Methods

​Marketplace (Claude Code, Cursor)

​Manual Installation (OpenCode, Codex)

​Creating a Plugin for a New Platform

​Step 1: Analyze Platform Capabilities

Plugin System

Skill Discovery

Hooks Support

Commands

​Step 2: Choose Integration Method

​Step 3: Create Platform-Specific Directory

​Step 4: Write Plugin Manifest or Code

​Step 5: Write Installation Instructions

​Step 6: Test Installation

​Step 7: Submit Pull Request

​Plugin Packaging Best Practices

​Platform Comparison Matrix

​Troubleshooting Plugin Issues

​Plugin Not Loading

​Skills Not Discovered

​Hooks Not Running

​Next Steps

Architecture

Hooks System

Creating Skills

Contributing

Plugin System

Plugin Manifest Formats

Claude Code Plugin

Cursor Plugin

OpenCode Plugin

Codex (No Plugin)

Distribution Methods

Marketplace (Claude Code, Cursor)

Manual Installation (OpenCode, Codex)

Creating a Plugin for a New Platform

Step 1: Analyze Platform Capabilities

Step 2: Choose Integration Method

Step 3: Create Platform-Specific Directory

Step 4: Write Plugin Manifest or Code

Step 5: Write Installation Instructions

Step 6: Test Installation

Step 7: Submit Pull Request

Plugin Packaging Best Practices

Platform Comparison Matrix

Troubleshooting Plugin Issues

Plugin Not Loading

Skills Not Discovered

Hooks Not Running

Next Steps