Superpowers

Overview

Imagine having a personal AI-powered engineering teammate who doesn’t just write code — they understand your project, automate repetitive tasks, enforce best practices, and grow smarter with every interaction. That’s the promise of Superpowers, an innovative agentic skills framework and methodology designed specifically for modern software developers.

Built as a universal skill system, Superpowers transforms how AI assistants engage with codebases by introducing structured, reusable automation workflows across languages like Shell, JavaScript, and beyond. Instead of treating each AI request as isolated, Superpowers enables persistent, context-aware behaviors — turning one-off prompts into long-term developer superpowers.

This isn't just another script library or CLI tool. Superpowers is a paradigm shift: it empowers AI agents (like those in Cursor, Claude Code, or custom LLM environments) to act autonomously, safely, and effectively within your development ecosystem. Whether you're scaffolding new features, debugging production issues, or automating CI/CD pipelines, Superpowers gives your AI the tools to operate like a seasoned engineer.

In a world where AI-assisted coding is becoming standard, Superpowers helps you move from reactive assistance to proactive collaboration — making your AI not just helpful, but truly capable.

Key Benefits

1. Reusable Automation Across Projects

With Superpowers, common development patterns (e.g., setting up linting, generating boilerplate, running tests) are codified once and reused infinitely. No more copying scripts between repos — your AI knows exactly what to do because the instructions live in a shared, executable format.

✅ Scenario: Start a new Node.js microservice? Your AI runs setup-node-service via Superpowers — installing dependencies, configuring ESLint/Prettier, creating Dockerfile, and initializing Git hooks — all without manual input.

2. Language-Agnostic Task Execution

Whether you're working in Bash, JavaScript, Python, or even YAML configuration files, Superpowers provides consistent interfaces for automation. It abstracts complexity while preserving control.

✅ Scenario: Need to parse logs, modify environment variables, and restart services on a remote server? Chain Shell-based Superpowers skills together — securely and idempotently.

3. Agentic Workflows with Memory & Context

Unlike traditional scripts, Superpowers supports stateful operations. Skills can remember past actions, adapt based on feedback, and coordinate multi-step tasks across files and systems.

✅ Scenario: Debugging a failing test suite? The AI uses Superpowers to isolate flaky tests, generate hypotheses, run targeted retries, and suggest fixes — learning from each attempt.

4. Enhanced Collaboration Between Humans & AI

By defining clear, auditable skill boundaries, Superpowers makes AI behavior transparent and trustworthy. You always know what the AI plans to do before it acts — enabling safe delegation.

✅ Scenario: A junior dev asks the AI to “optimize database queries.” With Superpowers, the AI explains its plan using registered optimization skills, gets approval, then executes step-by-step.

5. Future-Proof Your AI Tooling

As new models and platforms emerge, Superpowers’ modular design ensures compatibility. Write skills once, use them everywhere — from local IDEs to cloud-based coding agents.

✅ Scenario: Migrating from Cursor to a custom VS Code + LLM setup? Your Superpowers skills transfer seamlessly thanks to their platform-agnostic architecture.

Core Features

Feature	Description	Supported Platforms
Modular Skill Architecture	Define discrete, composable functions (skills) in JSON or JS modules that encapsulate specific dev tasks (e.g., create-component, run-security-scan)	Universal (GitHub, CLI, IDEs)
Cross-Language Support	Execute logic in Shell, JavaScript, Python, and more through unified skill invocation syntax	Any environment with Node.js or shell access
Skill Registry & Discovery	Browse, search, and invoke existing skills programmatically — ideal for team knowledge sharing	Local .superpowers/ dir or remote registry
Safe Execution Sandbox	Optional sandboxing for dangerous operations (e.g., file deletion, network calls), with dry-run previews	Configurable per skill
Contextual Awareness	Skills can inspect project structure, git status, config files, and runtime environment to make intelligent decisions	All supported platforms
Extensible Plugin Model	Add new language runtimes, integrate with CI/CD tools, or connect to observability platforms via plugins	Custom integrations supported

How to Get & Install

Superpowers is a universal AI skill, meaning it works across multiple development environments and AI coding platforms. Since it's open-source and hosted on GitHub, installation is straightforward — whether you’re using Cursor, VS Code with an LLM plugin, or building your own agent system.

Here’s how to get started:

Step 1: Clone the Repository

Start by cloning the official Superpowers GitHub repository:

git clone https://github.com/obra/superpowers.git
cd superpowers

This gives you access to:

• Example skills (examples/)
• Core framework code (src/)
• Configuration templates
• Documentation and contribution guidelines

Step 2: Install Dependencies

Ensure you have Node.js (v18+) installed, then run:

npm install

Some skills may require additional tools like bash, jq, or curl. Make sure these are available in your PATH if you plan to use Shell-based automation.

Step 3: Initialize Superpowers in Your Project

To enable Superpowers in your own project, copy the .superpowers directory (from the repo) into your project root:

cp -r superpowers/.superpowers /your/project/root/

Alternatively, create a minimal config:

// .superpowers/config.json
{
  "skills": "./.superpowers/skills",
  "enableSandbox": true,
  "trustedOrigins": ["https://github.com/obra"]
}

Then set up a basic skill:

// .superpowers/skills/hello-world.js
module.exports = {
  name: "hello-world",
  description: "Prints a friendly greeting",
  async execute(input, context) {
    console.log("👋 Hello from Superpowers!");
    return { message: "Success", output: "Hello World" };
  }
};

Step 4: Use with Your AI Coding Assistant

For Cursor Users:

1. Open your project in Cursor.
2. Place the .superpowers folder at the root of your workspace.
3. In any chat prompt, type:

   /plugin install https://github.com/obra/superpowers
   

   Or manually link the local version via settings.

Now you can ask things like:

"Use the hello-world skill"
"Run all setup tasks for a new Express API"

Cursor will detect available skills and execute them securely.

For Claude Code (via Anthropic Artifacts or Browser Extension):

While Claude doesn’t natively support plugins yet, you can still leverage Superpowers by:

• Pasting relevant skill definitions into context
• Asking Claude to simulate or generate calls to Superpowers functions
• Using the framework locally and invoking it via shell commands

Example prompt:

"I’ve installed the Superpowers framework in my project. Please use the create-react-component skill to generate a Button component with TypeScript and Tailwind."

For Universal Use (Custom Agents or Editors):

Integrate Superpowers as a module in your agent pipeline:

const superpowers = require('./superpowers');

await superpowers.loadSkills('.superpowers/skills');
const result = await superpowers.run('create-dockerfile', {
  language: 'node',
  port: 3000
});

You can also wrap Superpowers in a REST API or CLI for broader integration.

💡 Pro Tip: Host your team’s private skill library by forking the repo and publishing internal skills under .superpowers/skills/team/.

Step 5: Explore & Extend

Browse the included example skills:

• git-commit-suggester.js: Analyzes changes and drafts commit messages
• shell/exec.js: Safely runs shell commands with confirmation
• js/refactor-variable.js: Renames variables across files

Then start writing your own! Each skill should follow this pattern:

module.exports = {
  name: "my-skill",
  description: "What this does",
  parameters: { /* JSON Schema */ },
  async execute(params, context) {
    // Your logic here
  }
};

See the README for full authoring guidelines.

Use Cases

Superpowers shines in scenarios where consistency, speed, and autonomy matter. Here are five ideal applications:

1. Onboarding New Developers

Automate the entire setup process: clone repos, install deps, configure editors, run first build. Just say:

“Run the onboarding workflow”
and let Superpowers guide the new hire step-by-step.

2. Automated Pull Request Preparation

Before pushing code, trigger a skill that:

• Formats all files
• Runs linters and type checks
• Generates changelog snippets
• Suggests a PR title and description

All in one command.

3. Incident Response Playbooks

When alerts fire, activate a troubleshoot-api-error skill that:

• Checks logs
• Validates recent deploys
• Queries metrics
• Proposes root causes

Turn reactive firefighting into proactive diagnosis.

4. Frontend Component Generation

Generate fully-typed React components with stories, tests, and styling pre-configured:

“Create a DashboardCard component using Superpowers”

No more copy-pasting from old files.

5. Legacy Migration Assistance

Break down large refactors into manageable steps. Use skills like:

• migrate-jest-to-vite
• convert-class-to-function
• add-types-to-js-file

Each step is repeatable, reviewable, and safe.

Tips

🔹 Start Small: Begin with simple skills like create-file or print-env-info. Master the execution model before tackling complex workflows.

🔹 Version Control Your Skills: Treat .superpowers/skills/ like source code — track it in Git, review changes, and test updates.

🔹 Use Dry Runs First: Enable sandbox mode and preview changes before applying them to critical systems.

🔹 Document Public Skills: Add clear descriptions and parameter schemas so both humans and AIs understand what each skill does.

🔹 Share Across Teams: Create a central repository of approved skills for frontend, backend, DevOps, etc., ensuring consistency across projects.

Disclaimer

Superpowers is an experimental open-source project developed by obra and maintained on GitHub. While designed with safety in mind (including sandboxing and execution previews), always review AI-generated or automated changes before deploying to production.

The authors and contributors are not liable for data loss, security breaches, or operational downtime caused by misuse or bugs in automation scripts.

Use Superpowers responsibly. Grant permissions cautiously. And remember: great power requires great responsibility. 🦸‍♂️💻

---

Ready to unlock your AI’s full potential? Head over to https://github.com/obra/superpowers/ and give your coding assistant the Superpowers it deserves.