This page documents the static configuration files that define how the superpowers plugin integrates with each supported AI coding platform. It covers manifest files, marketplace registration, hook wiring, and repository-level ignore rules.
For the runtime hook execution logic triggered by these configurations, see Hooks System. For the directory layout that these files live in, see Directory Structure. For per-platform installation steps, see Installing on Claude Code, Installing on Cursor, and related pages.
Configuration files by role:
Configuration file relationship to platforms:
Sources: .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 .claude-plugin/marketplace.json1-20 .gitignore1-4
.claude-plugin/plugin.jsonThis is the primary manifest that Claude Code reads when the plugin is installed from a marketplace. It identifies the plugin and provides metadata but does not declare hooks, skills paths, or commands directly — those are discovered by Claude Code from the repository structure at install time.
.claude-plugin/plugin.json1-13
| Field | Value | Purpose |
|---|---|---|
name | "superpowers" | Plugin identifier used in /plugin install and namespace prefixes |
description | "Core skills library..." | Shown in marketplace listings |
version | "4.3.1" | Semver version for update tracking |
author.name | "Jesse Vincent" | Publisher identity |
author.email | "[email protected]" | Publisher contact |
homepage | "https://github.com/obra/superpowers" | Informational link |
repository | "https://github.com/obra/superpowers" | Source repository |
license | "MIT" | License identifier |
keywords | ["skills","tdd","debugging",...] | Marketplace search terms |
The name field determines the namespace prefix for all skills and commands exposed by this plugin. For example, the brainstorming skill becomes accessible as superpowers:brainstorming.
Sources: .claude-plugin/plugin.json1-13
.cursor-plugin/plugin.jsonThe Cursor manifest serves a different purpose from its Claude Code counterpart: it explicitly declares the paths to all resource directories so Cursor's plugin system can locate them.
.cursor-plugin/plugin.json1-18
| Field | Value | Purpose |
|---|---|---|
name | "superpowers" | Plugin identifier |
displayName | "Superpowers" | Human-readable label in Cursor UI |
description | "Core skills library..." | Shown in plugin listings |
version | "4.3.1" | Semver version |
skills | "./skills/" | Path to skills directory |
agents | "./agents/" | Path to agent definitions |
commands | "./commands/" | Path to slash command definitions |
hooks | "./hooks/hooks.json" | Path to hooks configuration |
The critical difference from the Claude Code manifest is the explicit resource path declarations (skills, agents, commands, hooks). Claude Code discovers these by convention; Cursor requires them to be stated.
Manifest field comparison:
Sources: .cursor-plugin/plugin.json1-18 .claude-plugin/plugin.json1-13
.claude-plugin/marketplace.jsonThis file is used for local development testing only. It lets developers register a local directory as a marketplace source so they can install the in-development plugin without publishing to a remote marketplace.
.claude-plugin/marketplace.json1-20
| Field | Purpose |
|---|---|
name | Marketplace identifier ("superpowers-dev") |
description | Description of this marketplace |
owner | Developer contact |
plugins[].name | Must match the plugin's name field in plugin.json |
plugins[].version | Version string for this marketplace entry |
plugins[].source | "./" — points to the repo root as the plugin source |
The plugins[].source field set to "./" is the key production-versus-dev distinction. In the public marketplace (obra/superpowers-marketplace), this would point to a remote URL or published artifact. In this local file, it points to the current directory so the in-progress version can be installed directly.
Sources: .claude-plugin/marketplace.json1-20
hooks/hooks.jsonThis file configures the SessionStart hook that injects superpowers context at the beginning of every session. It is referenced by the Cursor manifest at "hooks": "./hooks/hooks.json" and discovered by Claude Code by convention.
The hook configuration has evolved across versions. Key properties:
| Property | Current value | Notes |
|---|---|---|
event | SessionStart | Fires once when a session begins |
async | false | Changed from true in v4.3.0; ensures context loads before the first agent turn |
command | Points to run-hook.cmd or session-start | Polyglot wrapper or direct script depending on platform |
The async: false setting is critical: when set to true (as it was in earlier versions), the hook could fail to complete before the model's first response, meaning the using-superpowers instructions were absent from the initial context window.
The hook command resolves differently per OS:
session-start directly (extensionless, bash shebang)run-hook.cmd polyglot wrapper which locates bash in standard Git for Windows pathsFor full details on the hook execution mechanics, see Hooks System.
Sources: RELEASE-NOTES.md47-49 RELEASE-NOTES.md13-23 .cursor-plugin/plugin.json17
.claude/settings.local.jsonThis file is not committed to the repository — the entire .claude/ directory is excluded by .gitignore. It is generated locally when Claude Code registers the plugin's hooks into the user's Claude Code configuration.
The file wires the hooks.json SessionStart hook into Claude Code's runtime. It is created automatically during plugin installation (/plugin install superpowers@superpowers-marketplace) and should not be edited by hand.
Because it lives outside version control, its exact schema is determined by Claude Code's plugin system, not by superpowers itself.
Sources: .gitignore3
.gitignore| Pattern | What it excludes | Reason |
|---|---|---|
.worktrees/ | Git worktree checkouts created by using-git-worktrees skill | Worktrees are ephemeral per-developer workspaces; committing them would pollute the repo |
.private-journal/ | Personal notes directory | User-specific content outside the shared plugin |
.claude/ | Claude Code local configuration, including settings.local.json | Contains machine-specific hook registration; not portable |
.DS_Store | macOS Finder metadata | Standard macOS artifact exclusion |
The exclusion of .worktrees/ is particularly significant to the workflow: the using-git-worktrees skill creates worktrees at .worktrees/<branch-name> inside the project. By ignoring this directory, the .gitignore ensures that working branches never appear as untracked changes in the main worktree.
Sources: .gitignore1-4
The following diagram maps each configuration file to the code entities it interacts with:
Sources: .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 .claude-plugin/marketplace.json1-20 .gitignore1-4 RELEASE-NOTES.md7-23
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.