How to Override Default Superpowers Skills with Your Own Custom Skills

Yes, you can override any default Superpowers skill by creating a personal skill with the same name in your OpenCode configuration directory, and the framework will automatically prefer your version unless you explicitly request the built-in one using the superpowers: prefix.

The Superpowers framework by obra ships with a robust set of built-in skills located in the repository's skills/ directory. When you need customized behavior for specific workflows, you can override default Superpowers skills by creating personal skill definitions that shadow the built-in versions. This shadowing system prioritizes your local configurations while maintaining access to the original framework capabilities.

Understanding the Skill Resolution Hierarchy

The framework maintains two distinct skill repositories that work together to provide flexibility without requiring you to fork the core project.

Built-in Superpowers Skills

The default skills ship with the obra/superpowers repository under the skills/ directory. These provide standard behaviors for common tasks like brainstorming, code review, and project planning. When you invoke a skill without any prefix, the system first checks for a personal override before falling back to these built-in definitions.

Personal Skills Directory

Your custom skills live in the OpenCode configuration directory, typically located at ~/.config/opencode/skills/. According to the design documentation in docs/plans/2025-11-22-opencode-support-implementation.md, personal skills override Superpowers skills when names match, giving you complete control over skill behavior without modifying the core repository.

How Skill Shadowing Works in lib/skills-core.js

The resolution logic that enables you to override default Superpowers skills is implemented in lib/skills-core.js. The resolveSkillPath function implements a priority-based lookup system that checks your personal directory first.

When resolving a skill, the function follows this algorithm:

1. Check if the skill name starts with superpowers: to force built-in usage
2. If not forced, search the personal skills directory for a SKILL.md file
3. If found in personal, return that path with sourceType: 'personal'
4. If not found in personal (or forced), search the built-in skills/ directory
5. Return the built-in path with sourceType: 'superpowers' if found

This implementation ensures that your personal configurations take precedence while preserving access to the original framework skills when needed.

Creating Your First Override Skill

To override a default Superpowers skill, you need to create a personal skill directory with the same name as the built-in skill you want to replace.

First, create the directory structure and skill definition file:

mkdir -p ~/.config/opencode/skills/my-skills/brainstorming
cat > ~/.config/opencode/skills/my-skills/brainstorming/SKILL.md <<'EOF'
---
name: brainstorming
description: Use when you want a custom brainstorming flow.
---

# My Custom Brainstorming Skill

1️⃣ Ask the user clarifying questions before any plan.
2️⃣ Produce a short bullet-point list of ideas.
EOF

This configuration creates a personal brainstorming skill that will override the default Superpowers brainstorming skill. When you request the brainstorming skill, the framework will load your custom SKILL.md instead of the built-in version.

Forcing the Default Superpowers Skill

There are scenarios where you might want to use the original built-in skill even when you have a personal override configured. The framework provides a superpowers: prefix for this exact purpose.

To force the use of the built-in skill, prefix the skill name with superpowers::

Use the superpowers:brainstorming skill to generate ideas for a new CLI tool.

When the engine parses this request, it sets forceSuperpowers = true in the resolveSkillPath function, which bypasses the personal directory lookup and proceeds directly to the built-in skills/ directory. This ensures you can always access the original framework behavior when needed.

Programmatic Skill Resolution

For developers building tools on top of the Superpowers framework, the resolveSkillPath function exported from lib/skills-core.js provides programmatic access to the skill resolution logic.

Here is how you can use it in a Node.js application:

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

const superDir = path.resolve(__dirname, 'skills');               // repo's built-in skills
const personalDir = path.resolve(process.env.HOME, '.config/opencode/skills/my-skills');

const result = resolveSkillPath('brainstorming', superDir, personalDir);
console.log(result);
// → { skillFile: '/home/you/.config/opencode/skills/my-skills/brainstorming/SKILL.md',
//     sourceType: 'personal',
//     skillPath: 'brainstorming' }

This programmatic interface allows you to build custom workflows that respect the personal-override-built-in hierarchy, making it easy to integrate Superpowers skill resolution into your own applications.

Summary

• Personal skills override built-in skills: Place custom skills in ~/.config/opencode/skills/ to shadow default Superpowers skills with the same name.
• Resolution happens in lib/skills-core.js: The resolveSkillPath function checks personal directories first, then falls back to built-in skills/.
• Use the superpowers: prefix to force the framework to use the built-in version even when a personal override exists.
• Skills require a SKILL.md file in their directory to be recognized by the resolution engine.

Frequently Asked Questions

Where do I place my personal Superpowers skills?

Personal skills belong in your OpenCode configuration directory, typically at ~/.config/opencode/skills/. Each skill should have its own subdirectory containing a SKILL.md file that defines the skill's behavior and metadata. The framework automatically detects skills in this location and prioritizes them over built-in versions.

What happens if my personal skill has the same name as a default one?

When you create a personal skill with the same name as a built-in Superpowers skill, the framework automatically uses your version. The resolveSkillPath function in lib/skills-core.js implements a shadowing mechanism that checks your personal directory first, ensuring your local customizations take precedence without requiring any configuration changes.

Can I override multiple default Superpowers skills at once?

Yes, you can override as many default skills as needed by creating personal versions for each one. There is no limit to the number of skills you can shadow. Each override operates independently, so you can customize specific workflows while leaving others unchanged, mixing personal and built-in skills as your project requires.

How do I debug which skill file is being loaded?

To verify which skill is being used, you can check the sourceType property returned by the resolveSkillPath function. It returns 'personal' when loading from your custom directory and 'superpowers' when loading from the built-in repository. Alternatively, use the superpowers: prefix to explicitly test the built-in version against your custom one and compare the outputs.

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