# What Is the `superpowers:` Prefix in Skill Names? A Deep Dive into the obra/superpowers Namespace

> Discover the purpose of the superpowers: prefix in skill names. Learn how this namespace prevents collisions and ensures unambiguous execution of built-in capabilities from the obra/superpowers repository.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: deep-dive
- Published: 2026-02-16

---

**The `superpowers:` prefix functions as a reserved namespace that forces the skill resolver to load built-in capabilities from the official Superpowers repository rather than personal skill collections, preventing naming collisions and ensuring unambiguous execution.**

In the `obra/superpowers` repository, every built-in skill is prefixed with `superpowers:`. This naming convention is not merely decorative—it forms the backbone of the skill resolution architecture. Understanding how this prefix functions is essential for developers building complex agent workflows or extending the Superpowers framework with custom capabilities.

## Why the `superpowers:` Namespace Exists

The prefix serves four critical architectural purposes defined in the project's resolution logic and release documentation.

### Unambiguous Invocation

When the Skill tool receives a fully-qualified name, the `superpowers:` prefix signals that the runtime should search the official Superpowers repository rather than the user's personal skill directory. This prevents accidental resolution of a personal skill that happens to share the same short name.

### Collision Avoidance

Users can define custom skills—such as a personal `brainstorming` skill—without fear that a future Superpowers update will overwrite their work. The namespace guarantees that `superpowers:brainstorming` and `brainstorming` occupy distinct resolution paths, as documented in [`RELEASE-NOTES.md`](https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md) (lines 450-453).

### Shadowing Rules

The resolver prioritizes personal skills unless the name explicitly forces the Superpowers namespace. This design allows developers to deliberately override a personal implementation with the official skill by adding the prefix, providing fine-grained control over which version executes.

### Consistent Documentation and CLI Syntax

All internal references, command shortcuts, and documentation use the `superpowers:` qualifier (for example, `/superpowers:brainstorm`). This uniformity simplifies parsing and enables reliable auto-completion within Claude Code and Codex environments.

## How the `superpowers:` Prefix Works Under the Hood

The resolution algorithm is implemented in the skill loader logic, specifically detailed in [`docs/plans/2025-11-22-opencode-support-implementation.md`](https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-implementation.md) (lines 194-203). The resolver strips the prefix, sets a forced-Superpowers flag, and adjusts the search order accordingly.

```javascript
function resolveSkillPath(skillName, superpowersDir, personalDir) {
  const forceSuperpowers = skillName.startsWith('superpowers:');
  const actualSkillName = forceSuperpowers
      ? skillName.replace(/^superpowers:/, '')
      : skillName;

  // Personal skills first – unless we were forced to use Superpowers
  if (!forceSuperpowers && personalDir) { /* search personal */ }

  // Then look in the Superpowers directory
  if (superpowersDir) { /* search superpowers */ }
}

```

When `skillName` is `"superpowers:brainstorming"`, `forceSuperpowers` evaluates to `true`, causing the resolver to skip the personal directory and load the official implementation from the Superpowers repository.

## Practical Examples of Using the `superpowers:` Prefix

### CLI Invocation

To execute a built-in skill from the command line, prepend the namespace:

```bash
/plugin install superpowers@superpowers-marketplace

# After installation

/superpowers:brainstorm     # Explicitly runs the built-in skill

```

Without the prefix, the system would check for a personal `brainstorm` skill first, potentially executing different logic.

### Sub-Agent Configuration

When defining complex workflows that require specific capabilities, use the fully-qualified name in YAML specifications:

```yaml

# In a sub-agent spec (e.g., subagent-driven-development plan)

required_sub_skills:
  - superpowers:test-driven-development
  - superpowers:code-reviewer

```

The `resolveSkillPath` helper processes these entries, ensuring the agent loads the official Superpowers implementations rather than any local variants.

## Summary

- The `superpowers:` prefix functions as a **namespace** that isolates built-in skills from personal collections.
- It ensures **unambiguous invocation** by forcing the resolver to search the official repository when present.
- The prefix prevents **naming collisions** between user-defined skills and future Superpowers updates.
- Developers can use it to **override shadowing rules** and explicitly select the official implementation.
- The resolution logic is implemented in [`docs/plans/2025-11-22-opencode-support-implementation.md`](https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-implementation.md) and enforced throughout the CLI and documentation.

## Frequently Asked Questions

### What happens if I omit the `superpowers:` prefix when calling a skill?

If you omit the prefix, the resolver first searches your personal skill directory. If a personal skill with that name exists, it executes that version instead of the built-in Superpowers skill. Only if no personal skill is found does the system fall back to the Superpowers repository.

### Can I create my own skills with the `superpowers:` prefix?

No. The resolver treats the `superpowers:` prefix as a reserved namespace that forces resolution to the official Superpowers directory. Attempting to use this prefix for personal skills would cause the resolver to look in the wrong location, resulting in a "skill not found" error or loading the official version instead of your custom code.

### Does the `superpowers:` prefix affect skill versioning or updates?

The prefix itself does not encode version information, but it ensures that updates to the official Superpowers library do not accidentally overwrite your personal skills. By maintaining separate namespaces, the system can update `superpowers:brainstorming` without touching your local `brainstorming` skill, preventing destructive collisions during upgrades.

### Where is the resolution logic for the `superpowers:` prefix implemented?

The core resolution algorithm is documented in [`docs/plans/2025-11-22-opencode-support-implementation.md`](https://github.com/obra/superpowers/blob/main/docs/plans/2025-11-22-opencode-support-implementation.md) (lines 194-203) and implemented in the skill loading utilities. This logic checks for the prefix, strips it to determine the actual skill name, and adjusts the search path to prioritize either the personal directory or the official Superpowers repository accordingly.