How Superpowers Handles Skill Shadowing Between Personal and Superpower Skills

Superpowers resolves skill shadowing through a deterministic three-step algorithm that prioritizes personal skills over built-in superpowers unless the superpowers: prefix is explicitly specified.

The Superpowers framework maintains two independent skill libraries to balance customization with stability. Understanding how skill shadowing works between your personal directory and the system superpowers directory is essential for effectively overriding built-in workflows without breaking core functionality.

Understanding the Dual Library Architecture

Superpowers segregates skills into two distinct namespaces to prevent accidental collisions and enable safe customization.

Personal Skills Directory

Personal skills reside in ~/.config/opencode/skills/ and use the personal namespace. These are user-specific overrides that take precedence over built-in functionality. When you create a skill with the same name as a superpower, this directory is where the shadowing version lives.

Superpowers Skills Directory

Built-in skills are stored in ~/.config/opencode/superpowers/skills/ under the superpowers namespace. These represent the upstream, version-controlled workflows distributed with the framework. The system protects these from modification while allowing shadowing through the personal directory mechanism.

The Skill Shadowing Resolution Algorithm

The core resolution logic is implemented in lib/skills-core.js (lines 108-140) through the resolveSkillPath function. The algorithm follows a strict priority order:

1. Force-Superpowers Prefix – If the skill name includes the superpowers: prefix (e.g., superpowers:my-skill), the resolver ignores the personal directory entirely and searches only the Superpowers library. This provides an escape hatch when you need the original implementation despite having a personal override.

2. Personal-First Lookup – For unprefixed names, the resolver first checks the personal directory (personalDir). If a SKILL.md file exists there, that version is returned immediately with sourceType set to "personal".

3. Fallback to Superpowers – If the skill is not found in the personal directory, the resolver searches the Superpowers directory. A match yields sourceType: "superpowers".

If neither location contains the requested skill, the resolver returns null.

Practical Code Examples

Programmatic Resolution

You can interact with the shadowing system directly using the core library:

import { resolveSkillPath } from '../lib/skills-core.js';
import path from 'path';
import os from 'os';

const home = os.homedir();
const superpowersDir = path.join(home, '.config/opencode/superpowers/skills');
const personalDir = path.join(home, '.config/opencode/skills');

// Personal skill shadows Superpowers
console.log(resolveSkillPath('shared-skill', superpowersDir, personalDir));
// → { skillFile: '/home/you/.config/opencode/skills/shared-skill/SKILL.md',
//     sourceType: 'personal', skillPath: 'shared-skill' }

// Force Superpowers version
console.log(resolveSkillPath('superpowers:shared-skill', superpowersDir, personalDir));
// → { skillFile: '/home/you/.config/opencode/superpowers/skills/shared-skill/SKILL.md',
//     sourceType: 'superpowers', skillPath: 'shared-skill' }

CLI Usage

The use_skill tool exposed by the OpenCode plugin automatically applies the same shadowing rules defined in .opencode/plugin/superpowers.js (lines 22-30):

# Load a personal-overridden skill

opencode run use_skill --skill_name shared-skill

# Force the original Superpowers implementation

opencode run use_skill --skill_name superpowers:shared-skill

Why Skill Shadowing Matters

The dual-library approach with deterministic shadowing provides three critical benefits:

• Customization – Users can locally override any built-in Superpowers workflow without forking or modifying the upstream repository. Place a skill with the same name in your personal directory, and it automatically takes precedence.

• Predictability – The explicit superpowers: prefix gives power users a reliable escape hatch to bypass local overrides when they need the original implementation, ensuring consistent behavior across environments.

• Isolation – Personal skills are sandboxed to a user-specific directory, preventing accidental changes to the shared Superpowers skill set while maintaining clear separation between user customizations and system defaults.

Summary

• Superpowers implements skill shadowing through two isolated libraries: personal (~/.config/opencode/skills/) and superpowers (~/.config/opencode/superpowers/skills/).
• The resolution algorithm in lib/skills-core.js prioritizes personal skills unless the superpowers: prefix is explicitly used.
• Users can override built-in skills by placing identically named skills in their personal directory, while the prefix syntax provides access to original implementations.
• The test suite in tests/opencode/test-skills-core.sh validates that personal skills correctly shadow superpowers when names collide.

Frequently Asked Questions

How do I override a built-in Superpowers skill with my own version?

Create a skill directory with the same name in your personal skills folder at ~/.config/opencode/skills/. When you reference the skill without a prefix, the resolver in lib/skills-core.js will automatically select your personal version over the built-in one. Your custom skill should include a SKILL.md file just like the original.

What happens if I use the superpowers: prefix on a skill that only exists in my personal directory?

The resolver will return null because the superpowers: prefix restricts the search to the Superpowers library only. If the skill does not exist in ~/.config/opencode/superpowers/skills/, the lookup fails even if you have a personal version available. Remove the prefix to access your personal skill.

Can I completely disable skill shadowing and only use built-in Superpowers?

There is no global configuration flag to disable shadowing entirely. However, you can achieve the same effect by ensuring your personal skills directory (~/.config/opencode/skills/) remains empty, or by always using the superpowers: prefix when invoking skills. The deterministic resolution algorithm ensures consistent behavior based on directory contents and naming conventions.

Where is the skill shadowing logic tested?

The shadowing behavior is verified in tests/opencode/test-skills-core.sh (lines 336-380). These tests create identical skill names in both the personal and Superpowers directories, then validate that the personal version takes precedence during unprefixed lookups, while the superpowers: prefix correctly forces resolution to the built-in library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}