This document provides step-by-step installation instructions for Superpowers on Cursor IDE. For installation on other platforms, see Installing on Claude Code, Installing on OpenCode, or Installing on Codex.
Cursor provides a built-in plugin marketplace that simplifies installation. The Superpowers plugin integrates via Cursor's hook system to inject skill context at session start. Unlike platforms requiring manual git clones, Cursor handles plugin distribution automatically through its marketplace.
What this installation does:
SessionStart hook that injects the using-superpowers skill contentSkill toolSources: README.md46-52 .cursor-plugin/plugin.json1-19
Figure: Cursor installation and bootstrap flow from marketplace command to agent context injection
Sources: README.md46-52 .cursor-plugin/plugin.json1-19 hooks/session-start.sh1-52
Execute this command in Cursor's agent chat:
/plugin-add superpowers
Cursor will:
superpowers pluginSessionStart hook for all subsequent sessionsNo additional configuration required. The plugin is immediately active.
Sources: README.md46-52
The installed plugin contains these directories referenced by .cursor-plugin/plugin.json:
| Directory | Purpose | Referenced in plugin.json |
|---|---|---|
skills/ | Skill definitions in markdown format | "skills": "./skills/" |
agents/ | Agent definitions (e.g., code-reviewer) | "agents": "./agents/" |
commands/ | User-invocable slash commands | "commands": "./commands/" |
hooks/ | Lifecycle hooks (session-start) | "hooks": "./hooks/hooks.json" |
Sources: .cursor-plugin/plugin.json14-18
Sources: .cursor-plugin/plugin.json1-19
The plugin registers a SessionStart hook via hooks/hooks.json When Cursor creates a new session, it executes hooks/session-start.sh1-52 before the agent's first response.
Figure: Session initialization sequence showing how session-start.sh injects bootstrap context before agent interaction
Sources: hooks/session-start.sh1-52 RELEASE-NOTES.md25-27
The hooks/session-start.sh35-49 script outputs dual-format JSON for compatibility:
Why dual format? Cursor hooks expect additional_context while Claude Code hooks expect hookSpecificOutput.additionalContext. The script provides both for cross-platform compatibility.
Sources: hooks/session-start.sh38-49
Before JSON embedding, hooks/session-start.sh23-31 applies escape_for_json() using bash parameter substitution:
Performance note: This replaced a character-by-character loop that was O(n²) on Windows Git Bash. The parameter substitution approach is 7x faster on macOS and dramatically faster on Windows.
Sources: hooks/session-start.sh23-31 RELEASE-NOTES.md50-53
Start a new Cursor session and observe the agent's behavior. The agent should not immediately start coding when you describe a task. Instead, it should check for relevant skills.
Test prompt:
I need to build a new feature that handles user authentication
Expected behavior:
Skill tool to search for relevant skillssuperpowers:brainstormingFailure modes:
Sources: README.md74-76 skills/using-superpowers/SKILL.md (referenced in session-start.sh)
Directly request a skill to confirm the skills directory is accessible:
Test command:
Show me the test-driven-development skill
Expected behavior:
Skill tool with parameter superpowers:test-driven-developmentFailure modes:
Sources: .cursor-plugin/plugin.json14
Test that the agent follows the mandatory first response protocol established by using-superpowers:
Test prompt:
Help me debug this failing test
Expected behavior:
superpowers:systematic-debugging or related skillFailure modes:
Sources: README.md94
Symptom: Agent responds to requests without checking for or invoking skills.
Diagnosis:
/plugin-list to confirm superpowers appearsFix:
/plugin-remove superpowers then /plugin-add superpowersSources: hooks/session-start.sh1-52 RELEASE-NOTES.md25-27
Symptom: Agent's first response doesn't reflect skill awareness, but subsequent responses do.
Diagnosis: The SessionStart hook runs asynchronously, completing after the agent's first turn. This was fixed in v4.2.0.
Background: Earlier versions used async: true in hooks.json, allowing the hook to complete after the agent began responding. Version 4.2.0 changed to async: false to ensure synchronous execution.
Verify synchronous execution:
Fix: Ensure you have v4.2.0 or later. Check version via /plugin-list.
Sources: RELEASE-NOTES.md25-27
Symptom: Hook fails with JSON parse errors, particularly on Windows.
Diagnosis: The skill content contains characters that break JSON embedding (backslashes, quotes, newlines).
Fix: Verify hooks/session-start.sh23-31 contains the correct escape_for_json() implementation using parameter substitution, not character-by-character loops.
Related issue: Windows CRLF line endings can break bash scripts. The repository includes .gitattributes to enforce LF endings for .sh files.
Sources: hooks/session-start.sh23-31 RELEASE-NOTES.md45-53
Symptom: Warning message about ~/.config/superpowers/skills appears on session start.
Explanation: Prior to v3.0, Superpowers used an external skills repository cloned to ~/.config/superpowers/skills. Version 3.0+ moved skills into the plugin itself. The warning appears if the old directory still exists.
Warning content from hooks/session-start.sh11-15:
⚠️ **WARNING:** Superpowers now uses Claude Code's skills system.
Custom skills in ~/.config/superpowers/skills will not be read.
Move custom skills to ~/.claude/skills instead.
To make this message go away, remove ~/.config/superpowers/skills
Fix:
Sources: hooks/session-start.sh11-15 RELEASE-NOTES.md1-92
This diagram maps logical components to actual files in the plugin:
Figure: Mapping of logical components to file paths in the Superpowers plugin structure
Sources: .cursor-plugin/plugin.json1-19 hooks/session-start.sh1-52 agents/code-reviewer.md1-49
After successful installation:
superpowers:using-superpowers for a complete introduction to the skills systemThe agent now has Superpowers. It will automatically check for relevant skills before responding to any request, following the mandatory first response protocol established by the bootstrap context.
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.