Superpowers

A comprehensive skills library of proven techniques, patterns, and workflows for AI coding assistants.

This is a fork and extension of Jesse Vincent's incredible Superpowers for Claude Code. Jesse's groundbreaking work and his amazing blog post introduced the concept of systematic, reusable skills for AI agents. This fork extends that vision to support agent-agnostic workflows across GitHub Copilot, Cursor, Gemini, and other AI coding assistants.

What's New

v8.0.0 (March 13, 2026):

Skills-only delivery — All per-platform prompt/command files (.opencode/command/, .cursor/commands/, .gemini/commands/, .github/prompts/, .codex/prompts/, commands/) have been removed.
Bootstrap cleanup — Bootstrap now runs a removeLegacyPrompts step that deletes any prompt/command files previously installed by older versions.
setup-skills is now a skill — Project initialization is delivered as skills/setup-skills/SKILL.md. The superpowers-agent setup-skills CLI command remains.
Cursor integration is symlink-only — Cursor hooks (hooks/cursor/) have been removed. Cursor now discovers skills through its native skill tool via symlinks.
Removed skills: writing-skills, testing-skills-with-subagents, gardening-skills-wiki deleted from skills/meta/ mostly in favor of Claude's Skills 2.0 skill-creator skill.
Removed CLI commands: install-copilot-prompts, install-cursor-commands, install-codex-prompts, install-gemini-commands, install-claude-commands, install-opencode-commands.

v7.0.5 (February 9, 2026):

Agent Auto-Installation - add and pull commands now automatically detect and install agents from repositories with an agents.json manifest, supporting GitHub Copilot and OpenCode platforms with extensible platform support
Agent Tracking - Installed agents are tracked in ~/.agents/config.json with source repository, version, and install timestamps
Persistent Repo Storage - Git-sourced agent repositories are persisted at ~/.agents/repos/ to maintain valid symlinks

v7.0.0 (February 7, 2026):

🔧 Bun Build System - Migrated CLI build toolchain from Node.js/npm to Bun for faster builds and simpler dependency management
📋 Smart Copilot Instructions - bootstrap and update now process ~/.github/copilot-instructions.md as a template, injecting the using-superpowers skill content and supporting marker-based idempotent updates with automatic backups
📊 Mermaid Flowcharts - Replaced DOT-format flowcharts with Mermaid syntax across 8 skills for better rendering in GitHub, VS Code, and agent contexts

v6.5.0 (January 24, 2026):

🔄 Upstream Sync - Ported advanced features from Jesse Vincent's obra/superpowers v4.1.1:
- OpenCode Plugin (.opencode/plugins/superpowers-agent.js) - Session bootstrap injection via system prompt transform
- using-superpowers Skill - Behavioral enforcement with Red Flags rationalization table (12 anti-patterns)
- Two-Stage Code Review - Spec compliance review + code quality review workflow
- Test Infrastructure (tests/) - Agent-agnostic test scripts for skill triggering
🔌 OpenCode Plugin - Native plugin for OpenCode that injects superpowers context at every session start using experimental.chat.system.transform hook
📋 Two-Stage Review Process - Updated subagent-driven-development skill with spec reviewer and code quality reviewer prompts for comprehensive code review

v6.4.x (January 23-24, 2026):

📐 Context Optimization - Reduced AGENTS.md context size by ~60-70% with separate SUPERPOWERS.md reference file
🔗 Project-Level Symlinks - setup-skills now creates symlinks from agent directories to .agents/skills

Previous Releases:

v6.3.x - Codex platform support, native skill tools, extended symlinks for OpenCode/Cursor/Gemini
v6.0.0 - Complete codebase modernization with 90% bundle reduction
v5.4.0 - Dynamic tool mappings, automated platform detection

Key Features:

🎯 Smart Skill Matching - Just type superpowers execute brainstorming instead of full paths
🚀 One-Line Installer - curl -fsSL https://raw.githubusercontent.com/complexthings/superpowers/main/install.sh | bash
📦 Skill Installation - add and add-repository commands for Git/local skill installation
🔍 Helper Discovery - get-helpers finds scripts within skills using substring matching
📝 Setup Skills - setup-skills skill initializes projects with agent instruction files and skill symlinks

What You Get

Testing Skills - TDD, async testing, anti-patterns
Debugging Skills - Systematic debugging, root cause tracing, verification
Collaboration Skills - Brainstorming, planning, code review, parallel agents
Development Skills - Git worktrees, finishing branches, subagent workflows
Meta Skills - Creating, testing, and sharing skills
Utility Commands - find-skills to discover available skills, execute to load them

Plus:

Universal Prompts - Work across Claude, GitHub Copilot, Cursor, Gemini, and other AI assistants
Automatic Integration - Skills activate automatically when relevant
Consistent Workflows - Systematic approaches to common engineering tasks

Installation

Quick Install (Recommended)

Install Superpowers globally with one command:

curl -fsSL https://raw.githubusercontent.com/complexthings/superpowers/main/install.sh | bash

Security Note: Always review scripts before running:

curl -fsSL https://raw.githubusercontent.com/complexthings/superpowers/main/install.sh -o install.sh
cat install.sh
bash install.sh

The installer will:

Install to ~/.agents/superpowers (global, works everywhere)
Set up universal aliases: superpowers and superpowers-agent
Sync skill symlinks for all detected agents
Optionally update project files (AGENTS.md)

After installation, you can use Superpowers from anywhere:

superpowers --help
superpowers find-skills
superpowers execute systematic-debugging

Manual Installation

If you prefer manual installation or need project-specific setup, see .agents/INSTALL.md.

Learn more: Superpowers for Claude Code by Jesse Vincent

Quick Start

Discovering Skills

List all available skills:

superpowers find-skills

Search for specific skills:

superpowers find-skills | grep -i <topic>

Using Skills

Smart skill matching - Just type the skill name or any suffix:

superpowers execute brainstorming              # Finds superpowers:collaboration/brainstorming
superpowers execute test-driven-development    # Finds superpowers:testing/test-driven-development
superpowers execute collaboration/brainstorming # More specific suffix also works

Full paths still work:

superpowers execute superpowers:collaboration/brainstorming

Priority order: Project skills → Home skills → Global Superpowers skills

Automatic Skill Activation

Skills activate automatically when relevant. For example:

test-driven-development activates when implementing features
systematic-debugging activates when debugging issues
verification-before-completion activates before claiming work is done

Configuration

Superpowers supports project-level and global configuration via .agents/config.json.

Directory Configuration

Default locations:

Prompts: .agents/prompts/
Plans: .agents/plans/
Skills: .agents/skills/

Override globally:

// ~/.agents/config.json
{
  "prompts_dir": "custom/prompts",
  "plans_dir": "custom/plans",
  "installLocation": "global"
}

Override per-project:

// .agents/config.json (in project root)
{
  "prompts_dir": ".my-prompts",
  "plans_dir": ".my-plans",
  "installLocation": "project"
}

Priority: Project config > Global config > Defaults

Read config from CLI:

superpowers-agent get-config prompts_dir
superpowers-agent get-config plans_dir

Repository Aliases

Superpowers allows you to create shortcuts for frequently used skill repositories using repository aliases.

Add a repository alias:

# Automatic alias detection from skill.json
superpowers-agent add-repository https://github.com/example/skills.git

# Custom alias
superpowers-agent add-repository https://github.com/example/skills.git --as=@myskills

# Add to project config
superpowers-agent add-repository https://github.com/example/skills.git --project

Use repository aliases to install skills:

# Install all skills from repository
superpowers-agent add @myskills

# Install specific skill path
superpowers-agent add @myskills path/to/skill

# Install to project
superpowers-agent add @myskills path/to/skill --project

Configuration format:

// ~/.agents/config.json or .agents/config.json
{
  "installLocation": "global",
  "repositories": {
    "@myskills": "https://github.com/example/skills.git",
    "@internal": "https://github.com/myorg/internal-skills.git"
  }
}

Repository aliases make it easy to:

Install skills from multiple sources
Share skill repositories across teams
Quickly access frequently used skill collections
Support both Git URLs and local paths

Agent Auto-Installation

Repositories can include an agents.json manifest to automatically install AI agents alongside skills. When you run superpowers-agent add or superpowers-agent pull on a repository containing agents.json, agents are automatically symlinked to the appropriate platform directories.

agents.json format:

{
    "version": "1.0.0",
    "repository": "@my-agents",
    "agents": {
        "github": ["agent-name-1", "agent-name-2"],
        "opencode": ["agent-name-1", "agent-name-2"]
    }
}

Supported platforms and paths:

Platform	Source Directory	Destination
`github`	`.github/agents/<name>.agent.md`	VS Code `prompts/` directory
`opencode`	`.opencode/agents/<name>.md`	`~/.config/opencode/agents/`

How it works:

After skills are installed, the system checks for agents.json at the repository root
For each platform listed, agents are symlinked from the repository to the platform destination
For git-sourced repositories, a persistent copy is stored at ~/.agents/repos/ so symlinks remain valid
Installed agents are tracked in ~/.agents/config.json under installedAgents

Examples:

# Install skills and agents from a repository
superpowers-agent add https://github.com/example/agents-repo.git

# Update agents from a repository alias
superpowers-agent pull @my-agents

Skill Symlinks for IDE Integration

Superpowers automatically creates symlinks to make skills available to all major AI coding assistants in their native skill directories.

How it works:

When you run superpowers-agent bootstrap or superpowers-agent setup-skills:

Global symlinks (via bootstrap) sync skills to user-level directories:
- ~/.claude/skills/superpowers -> ~/.agents/superpowers/skills/
- ~/.copilot/skills/superpowers -> ~/.agents/superpowers/skills/
- ~/.config/opencode/skill/superpowers -> ~/.agents/superpowers/skills/
- ~/.cursor/skills/superpowers -> ~/.agents/superpowers/skills/
- ~/.gemini/skills/superpowers -> ~/.agents/superpowers/skills/
- ~/.codex/skills/superpowers -> ~/.agents/superpowers/skills/
Project symlinks (via setup-skills) sync project skills to agent directories:
- .claude/skills -> .agents/skills
- .github/skills -> .agents/skills
- .opencode/skill -> .agents/skills
- .cursor/skills -> .agents/skills
- .gemini/skills -> .agents/skills
- .codex/skills -> .agents/skills
Personal skills (installed via superpowers-agent add) are symlinked individually to all platforms.

Behavior:

Symlinks are only created if the parent directory exists
Use --force flag to create parent directories: superpowers-agent bootstrap --force
Use --force-<agent> flags to re-install only specific agent integrations (e.g. --force-copilot, --force-cursor, --force-claude)
Symlinks are tracked in ~/.agents/config.json for management

Windows Notes:

On Windows, symlinks require either:

Developer Mode enabled (Settings > Update & Security > For developers)
Running as administrator

If symlink creation fails on Windows, you'll see a warning with instructions.

Configuration:

// ~/.agents/config.json
{
  "symlinks": {
    "claude": {
      "superpowers": "~/.claude/skills/superpowers",
      "skills": ["~/.claude/skills/my-skill"]
    },
    "copilot": {
      "superpowers": "~/.copilot/skills/superpowers",
      "skills": []
    },
    "opencode": {
      "superpowers": "~/.config/opencode/skill/superpowers",
      "skills": []
    },
    "cursor": {
      "superpowers": "~/.cursor/skills/superpowers",
      "skills": []
    },
    "gemini": {
      "superpowers": "~/.gemini/skills/superpowers",
      "skills": []
    },
    "codex": {
      "superpowers": "~/.codex/skills/superpowers",
      "skills": []
    }
  }
}

Slash Commands & Skill Priority

Superpowers delivers skills as symlinks into each agent's native skill directory. Each agent discovers and loads skills using its native skill tool — no separate prompt/command files are installed.

Skill priority pipeline (first match wins):

./skills/ or .agents/skills/ inside the workspace (project-specific overrides)
.claude/skills/ inside the repo if present (repo-wide Claude overrides)
Personal skills in ~/.agents/skills/ (user-level customizations)
Bundled Superpowers skills in ~/.agents/superpowers/skills/ (system defaults)

When any agent invokes a skill — no matter which tool it originates from — the CLI enforces the ordering above. Add a brainstorming skill under ./skills/ and every tool immediately picks it up without modifying any prompt files.

OpenCode

Skills are available via OpenCode's native skill tool. The .opencode/plugins/superpowers-agent.js plugin injects bootstrap context at session start. Docs: OpenCode Plugins