Skip to content
Open
198 changes: 198 additions & 0 deletions .cursor/INSTALL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
# Installing Superpowers for Cursor

Quick setup to enable superpowers skills in Cursor.

> **Important:** Cursor does not discover symlinked rules, skills, agents, or commands.
> This installation uses copy-based setup to ensure proper discovery. After updating
> superpowers, you'll need to re-copy the files (see Updating section).

## Installation

### Option 1: Global Installation (Recommended)

Install superpowers globally for use across all Cursor projects.

1. **Clone superpowers repository**:

```bash
mkdir -p ~/.cursor/superpowers
cd ~/.cursor/superpowers
git clone https://github.com/obra/superpowers.git .
```

2. **Create skills directory**:

```bash
mkdir -p ~/.cursor/skills
```

3. **Copy superpowers skills**:

```bash
rm -rf ~/.cursor/skills/superpowers
cp -r ~/.cursor/superpowers/skills ~/.cursor/skills/superpowers
```

4. **Copy superpowers rules**:

```bash
mkdir -p ~/.cursor/rules
cp ~/.cursor/superpowers/.cursor/rules/superpowers.mdc ~/.cursor/rules/superpowers.mdc
```

5. **Copy superpowers subagents**:

```bash
mkdir -p ~/.cursor/agents
rm -rf ~/.cursor/agents/superpowers
cp -r ~/.cursor/superpowers/agents ~/.cursor/agents/superpowers
```

6. **Copy superpowers commands**:

```bash
mkdir -p ~/.cursor/commands
rm -rf ~/.cursor/commands/superpowers
cp -r ~/.cursor/superpowers/commands ~/.cursor/commands/superpowers
```

### Option 2: Project-Specific Installation

Install superpowers in a specific project (overrides global installation).

1. **Clone superpowers repository**:

```bash
git clone https://github.com/obra/superpowers.git .cursor/superpowers
```

2. **Create skills directory**:

```bash
mkdir -p .cursor/skills
```

3. **Copy superpowers skills**:

```bash
rm -rf .cursor/skills/superpowers
cp -r .cursor/superpowers/skills .cursor/skills/superpowers
```

4. **Copy superpowers rule**:

```bash
mkdir -p .cursor/rules
cp .cursor/superpowers/.cursor/rules/superpowers.mdc .cursor/rules/superpowers.mdc
```

5. **Copy superpowers subagents**:

```bash
mkdir -p .cursor/agents
cp -r .cursor/superpowers/agents/* .cursor/agents/
```

6. **Copy superpowers commands**:

```bash
mkdir -p .cursor/commands
cp -r .cursor/superpowers/commands/* .cursor/commands/
```

## Usage

### Automatic Discovery

Cursor automatically discovers:

- **Skills** from:
- `.cursor/skills/` (project-level)
- `~/.cursor/skills/` (global-level)
- **Subagents** from:
- `.cursor/agents/` (project-level)
- `~/.cursor/agents/` (global-level)
- **Commands** from:
- `.cursor/commands/` (project-level)
- `~/.cursor/commands/` (global-level)

### Manual Invocation

Skills can be manually invoked in chat using `/skill-name` syntax.

Subagents can be manually invoked using `/name` syntax or natural language requests:
- `/name` syntax: `/code-reviewer review this code`
- Natural language: `Use the code-reviewer subagent to review this code`

### Personal Skills

Create your own skills in the appropriate skills directory:

- Global: `~/.cursor/skills/my-skill/SKILL.md`
- Project: `.cursor/skills/my-skill/SKILL.md`

Create `~/.cursor/skills/my-skill/SKILL.md`:

```markdown
---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill content here]
```

## Priority Order

### Skills

Skills are loaded in this priority order (highest to lowest):

1. Project personal skills (`.cursor/skills/`)
2. Project superpowers skills (`.cursor/skills/superpowers/`)
3. Global personal skills (`~/.cursor/skills/`)
4. Global superpowers skills (`~/.cursor/skills/superpowers/`)

### Subagents

Subagents are loaded from:

- Project: `.cursor/agents/` (highest priority)
- Global: `~/.cursor/agents/` (fallback)

### Commands

Commands are loaded from:

- Project: `.cursor/commands/` (highest priority)
- Global: `~/.cursor/commands/` (fallback)

## Updating

```bash
# Global installation
cd ~/.cursor/superpowers
git pull

# After git pull, sync the copies:
# Global installation
rm -rf ~/.cursor/skills/superpowers ~/.cursor/agents/superpowers ~/.cursor/commands/superpowers
cp -r ~/.cursor/superpowers/skills ~/.cursor/skills/superpowers
cp -r ~/.cursor/superpowers/agents ~/.cursor/agents/superpowers
cp -r ~/.cursor/superpowers/commands ~/.cursor/commands/superpowers
cp ~/.cursor/superpowers/.cursor/rules/superpowers.mdc ~/.cursor/rules/superpowers.mdc

# Project installation
cd .cursor/superpowers
git pull

# After git pull, sync the copies:
# Project installation
rm -rf .cursor/skills/superpowers
cp -r .cursor/superpowers/skills .cursor/skills/superpowers
cp .cursor/superpowers/.cursor/rules/superpowers.mdc .cursor/rules/superpowers.mdc
cp -r .cursor/superpowers/agents/* .cursor/agents/
cp -r .cursor/superpowers/commands/* .cursor/commands/
```
28 changes: 28 additions & 0 deletions .cursor/rules/superpowers.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
alwaysApply: true
---

## Superpowers System

<EXTREMELY_IMPORTANT>
You have superpowers. Skills, subagents, and commands are automatically discovered from:
- `.cursor/skills/`, `.cursor/agents/`, `.cursor/commands/` (project-level)
- `~/.cursor/skills/`, `~/.cursor/agents/`, `~/.cursor/commands/` (global-level)

**Invocation:**
- Skills: `/skill-name` in chat
- Subagents: `/name` syntax or natural language requests
- Commands: `/command-name` syntax

**Critical Rules:**
- If a relevant skill/subagent/command applies to your task, you MUST use it
- Skills with checklists require update_plan todos for each item
- NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)
- Use Cursor's native subagent system (/name syntax) when skills reference subagents
- Use available commands for standardized workflows

**Priority (highest to lowest):**
1. Project personal > Project superpowers > Global personal > Global superpowers

Available skills include: brainstorming, systematic-debugging, test-driven-development, code-review, subagent-driven-development, writing-plans, executing-plans, verification-before-completion, and more.
</EXTREMELY_IMPORTANT>
54 changes: 54 additions & 0 deletions .cursor/superpowers-bootstrap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Superpowers Bootstrap for Cursor

<EXTREMELY_IMPORTANT>
You have superpowers.

**Skill System:**

- Skills are automatically discovered from `.cursor/skills/` and `~/.cursor/skills/` directories
- Skills can be manually invoked using `/skill-name` in chat
- Cursor's agent automatically applies relevant skills based on context

**Subagent System:**

- Subagents are automatically discovered from `.cursor/agents/` and `~/.cursor/agents/` directories
- Subagents can be invoked using /name syntax or natural language requests (e.g., /code-reviewer review this code or Use the code-reviewer subagent to review this code)
- Cursor's agent automatically uses subagents when appropriate for context isolation and parallel work
- You can launch multiple subagents concurrently by requesting parallel execution (e.g., "Review the API changes and update the documentation in parallel")

**Command System:**

- Commands are automatically discovered from `.cursor/commands/` and `~/.cursor/commands/` directories
- Commands can be invoked using `/command-name` syntax in chat
- Commands provide reusable workflows and standardized processes

**Critical Rules:**

- Before ANY task, consider if a relevant skill exists
- If a relevant skill applies to your task, you MUST use it
- Skills with checklists require `update_plan` todos for each item
- NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)
- Use Cursor's native subagent system (/name syntax) when skills reference subagents
- Use available commands for standardized workflows

**Skills location:**

- Global superpowers skills: ~/.cursor/skills/superpowers/
- Global personal skills: ~/.cursor/skills/ (override superpowers when names match)
- Project superpowers skills: .cursor/skills/superpowers/
- Project personal skills: .cursor/skills/ (highest priority, override all others)

**Subagents location:**

- Global superpowers subagents: ~/.cursor/agents/superpowers/
- Global personal subagents: ~/.cursor/agents/
- Project subagents: .cursor/agents/ (includes superpowers subagents when installed)

**Commands location:**

- Global superpowers commands: ~/.cursor/commands/superpowers/
- Global personal commands: ~/.cursor/commands/
- Project commands: .cursor/commands/ (includes superpowers commands when installed)

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
</EXTREMELY_IMPORTANT>
12 changes: 11 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Thanks!

## Installation

**Note:** Installation differs by platform. Claude Code has a built-in plugin system. Codex and OpenCode require manual setup.
**Note:** Installation differs by platform. Claude Code has a built-in plugin system. Cursor, Codex and OpenCode require manual setup.

### Claude Code (via Plugin Marketplace)

Expand Down Expand Up @@ -67,6 +67,16 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp

**Detailed docs:** [docs/README.codex.md](docs/README.codex.md)

### Cursor

Tell Cursor:

```
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.cursor/INSTALL.md
```

**Detailed docs:** [docs/README.cursor.md](docs/README.cursor.md)

### OpenCode

Tell OpenCode:
Expand Down
Loading