⚡ superpower_setup

One-command installer for obra/superpowers — a curated collection of AI coding skills for Google Antigravity.

Superpower_setup downloads and installs 14 battle-tested skills that teach your Antigravity agent proven development workflows: TDD, systematic debugging, parallel agents, code review, and more.

Table of Contents

• Why Superpowers?
• Quick Start
• Installation Modes
• Commands
• Options
• Examples
• Directory Structure
• Included Skills
• How It Works
• Troubleshooting
• License

Why Superpowers?

Out of the box, Antigravity is powerful — but it doesn't know your workflows. Superpowers fills that gap with a structured skill system that:

• 🧠 Teaches patterns, not just prompts — Each skill is a detailed methodology (e.g., RED-GREEN-REFACTOR for TDD) that the agent follows consistently.
• 🔄 Stays up to date — Run update anytime to pull the latest skills from the upstream repo.
• 🌍 Works locally or globally — Install per-project for team consistency, or globally for personal productivity across all repos.
• 📦 Zero dependencies — Pure Node.js, no external packages. Just npx and go.

Quick Start

# Install into your current project
npx superpower_setup init

# Or install globally (available across all projects)
npx superpower_setup init --global

That's it. Your Antigravity agent now has access to 14 professional development skills.

Installation Modes

Local Mode (default)

Installs skills into the current project's .agents/ directory. Best for:

• Team projects where everyone should share the same skills
• Project-specific skill configurations
• Keeping skills version-locked per repo

npx superpower_setup init

Global Mode (--global)

Installs skills into ~/.gemini/antigravity/ so they are available across all projects. Best for:

• Personal productivity — install once, use everywhere
• Trying out superpowers without modifying any project
• Shared skills across multiple solo repos

npx superpower_setup init --global

Note: Global mode does not create gemini-extension.json or modify .gitignore, since the global directory lives outside any git repository.

Local vs Global Comparison

| Aspect | Local | Global | |--------|-------|--------| | Skills location | <project>/.agents/skills/superpowers/ | ~/.gemini/antigravity/skills/superpowers/ | | GEMINI.md | <project>/GEMINI.md | ~/.gemini/GEMINI.md | | gemini-extension.json | ✅ Created | ❌ Not needed | | .gitignore | ✅ Updated | ❌ Not needed | | Scope | Current project only | All projects | | Team sharing | ✅ Commit config to repo | ❌ Per-user only |

Commands

init

Downloads and installs superpowers skills.

npx superpower_setup init [options]

• Creates the .agents/ directory structure (or ~/.gemini/antigravity/ for global)
• Copies all skills, agents, commands, and hooks
• Sets up GEMINI.md with skill references
• Copies gemini-extension.json (local mode only)
• Adds .agents to .gitignore (local mode only)

Will not overwrite existing files unless --force is used.

update

Updates superpowers to the latest version from the upstream repository.

npx superpower_setup update [options]

Functionally identical to init --force — it re-downloads and overwrites all existing skill files to ensure you have the latest version.

Options

| Option | Description | Default | |--------|-------------|---------| | --target <path> | Target directory for installation (local mode only) | Current working directory | | --branch <name> | Git branch of the superpowers repository to install from | main | | --force | Overwrite all existing files without prompting | false | | --global | Install to the global Antigravity directory (~/.gemini/antigravity/) instead of the current project | false | | --help, -h | Show help message | — | | --version, -v | Show version number | — |

Note: If --global and --target are used together, --target is ignored with a warning. The global directory is always ~/.gemini/antigravity/.

Examples

# Basic local install
npx superpower_setup init

# Install globally
npx superpower_setup init --global

# Install into a specific project directory
npx superpower_setup init --target /path/to/my-project

# Force reinstall (overwrite existing files)
npx superpower_setup init --force

# Install from a development branch
npx superpower_setup init --branch develop

# Update local installation
npx superpower_setup update

# Update global installation
npx superpower_setup update --global

# Show help
npx superpower_setup --help

Directory Structure

After Local Install

project-root/
├── .agents/
│   ├── skills/superpowers/         # 14 skill definitions
│   │   ├── brainstorming/
│   │   ├── test-driven-development/
│   │   ├── systematic-debugging/
│   │   ├── writing-plans/
│   │   ├── executing-plans/
│   │   ├── subagent-driven-development/
│   │   ├── using-git-worktrees/
│   │   ├── requesting-code-review/
│   │   ├── receiving-code-review/
│   │   ├── finishing-a-development-branch/
│   │   ├── verification-before-completion/
│   │   ├── dispatching-parallel-agents/
│   │   ├── writing-skills/
│   │   └── using-superpowers/
│   ├── agents/superpowers/         # Agent definitions
│   ├── commands/superpowers/       # Custom slash commands
│   └── hooks/superpowers/          # Session lifecycle hooks
├── GEMINI.md                       # Context file (auto-generated references)
├── gemini-extension.json           # Extension metadata
└── .gitignore                      # .agents entry added automatically

After Global Install

~/.gemini/
├── antigravity/
│   ├── skills/superpowers/         # 14 skill definitions
│   ├── agents/superpowers/         # Agent definitions
│   ├── commands/superpowers/       # Custom slash commands
│   └── hooks/superpowers/          # Session lifecycle hooks
└── GEMINI.md                       # Global context file

Platform-specific global paths:

| OS | Path | |----|------| | Windows | C:\Users\<username>\.gemini\antigravity\ | | macOS | /Users/<username>/.gemini/antigravity/ | | Linux | /home/<username>/.gemini/antigravity/ |

Included Skills

| Skill | Description | Use When | |-------|-------------|----------| | brainstorming | Socratic design refinement | Starting a new feature or exploring solutions | | test-driven-development | RED-GREEN-REFACTOR cycle | Writing new functionality with tests first | | systematic-debugging | 4-phase root cause process | Tracking down bugs methodically | | writing-plans | Detailed implementation plans | Planning complex multi-file changes | | executing-plans | Batch execution with checkpoints | Implementing a pre-written plan step by step | | subagent-driven-development | Fast iteration with two-stage review | Rapid prototyping with quality checks | | using-git-worktrees | Parallel development branches | Working on multiple features simultaneously | | requesting-code-review | Pre-review checklist | Preparing code for peer review | | receiving-code-review | Responding to feedback | Addressing review comments systematically | | finishing-a-development-branch | Merge/PR decision workflow | Wrapping up a feature branch | | verification-before-completion | Final validation checklist | Ensuring changes actually work before marking done | | dispatching-parallel-agents | Concurrent subagent workflows | Splitting large tasks across multiple agents | | writing-skills | Skill authoring guide | Creating your own custom skills | | using-superpowers | Introduction to the skills system | Learning how the superpowers framework works |

How It Works

1. Clone — The tool shallow-clones the obra/superpowers repository into a temporary directory.
2. Copy — Skills, agents, commands, and hooks are copied from the cloned repo to the target directory (.agents/ for local, ~/.gemini/antigravity/ for global).
3. Configure — GEMINI.md is created or updated with @-references pointing to the installed skill files. For local mode, gemini-extension.json and .gitignore are also set up.
4. Cleanup — The temporary clone is deleted.

The GEMINI.md file uses marker comments (<!-- SUPERPOWERS_START --> / <!-- SUPERPOWERS_END -->) to manage its section, so it can safely coexist with your own content in the same file.

Troubleshooting

"Git is not installed"

Superpower_setup requires Git to clone the upstream repository. Install Git from git-scm.com/downloads.

"Failed to clone repo"

• Check your internet connection
• Verify the branch name exists: git ls-remote --heads https://github.com/obra/superpowers.git
• Try with the default branch: npx superpower_setup init (without --branch)

Files already exist

By default, init will not overwrite existing files. Use one of:

# Overwrite everything
npx superpower_setup init --force

# Or use update (which implies --force)
npx superpower_setup update

Skills not being picked up by Antigravity

• Ensure GEMINI.md exists and contains the <!-- SUPERPOWERS_START --> section
• For local installs, verify gemini-extension.json is present at the project root
• For global installs, check that files exist in ~/.gemini/antigravity/skills/superpowers/
• Restart your Antigravity session after installation

Prerequisites

• Node.js >= 18.0.0 (for parseArgs support)
• Git (for cloning the superpowers repository)
• npx (included with Node.js)

License

MIT