Superpowers + your own skills
Professional teams rarely need one universal instruction file. The harder—and more useful—job is deciding where each kind of guidance belongs. Superpowers can supply the development process. A local skill can carry domain knowledge. Project instructions keep repository-wide rules in view.
The useful question is not “Which skill is stronger?” It is “Which layer owns this decision?”
The description does more than document#
Codex can activate a skill because you named it or because the task matches its description. The frontmatter is therefore part of the routing mechanism, not administrative decoration. If the description is vague, a relevant skill can be missed without an obvious error.
Use one running request: “Add a tenant-aware invoice export with CSV output and audit logging.” Superpowers sees new-feature work and may route into brainstorming before implementation. Your own tenant-export skill sees invoice export, tenancy, and audit evidence. Both matches can be legitimate because they answer different questions.[1][4]
Extract task verbs, objects, constraints, and any explicitly named skill.
Compare the request with concise trigger boundaries in available skills.
Read the complete SKILL.md only for selected skills.
Use process and domain instructions together inside project constraints.
How to read this: the request can activate more than one relevant skill, but the skills do not have to play the same role. Superpowers shapes the development method; tenant-export supplies the tenant and audit constraints.
Separate process from domain rules#
Superpowers is a development methodology expressed as composable skills. Repeating that methodology in a local skill adds another place for the same rules to drift. Use the local skill for knowledge the generic process cannot have: architecture boundaries, regulated evidence, project commands, and acceptance checks.
Superpowers starts before code. Its documented workflow moves through brainstorming, worktree isolation, planning, implementation, test-driven development, review, and verification. Its value is procedural consistency across repositories—not knowledge of your invoice schema.[4]
For the running request, it should ask what “tenant-aware” means, surface alternative export designs, get approval, create a plan, and verify the result. Those moves remain useful whether the product is billing software, a medical records system, or a CLI.
A custom tenant-export skill can require tenant predicates in every query, forbid cross-tenant joins, point to the canonical audit-event schema, name the fixture generator, and run a leakage test. This is reusable expertise, but only inside environments that share those rules.
Its description should name the trigger boundary directly: “Use when creating or changing tenant-scoped exports, CSV downloads, or audit events in the billing service.” Codex relies on that description for implicit activation, and descriptions may be shortened when many skills compete for the initial context budget.[1]
Use this layer for repository-wide expectations: “Every data query must include the authenticated tenant ID,” “Never log invoice contents,” or “Run the isolation suite before commit.” Codex reads AGENTS.md before work and combines guidance from the repository root down to the current directory; closer files override earlier guidance in that chain.[2]
If a rule must survive a missed skill trigger, it does not belong only inside that skill. AGENTS.md keeps the guidance in the agent’s working context, but it does not enforce the rule. Tenant isolation still needs authorization code, tests, and CI.
Brainstorm, plan, implement, review, verify.
Tenant boundaries, audit schema, local evidence.
Rules that cannot depend on a trigger.
The concrete outcome and current intent.
Conflict is an ownership problem#
Codex documents how skills are found and activated. It does not document a universal “closest skill wins” algorithm for conflicting instructions. If two skills share a name, they are not merged; both may appear. Design the boundary between them instead of assuming precedence.[1]
Collision by accident
Superpowers says to stop and clarify. Your custom skill says to infer defaults and implement immediately.
Both claim process ownership. The conflict is architectural, not lexical. Renaming either skill will not fix it.
Composition by design
In the responsibility model used here, Superpowers owns clarification, planning, TDD, and review. The custom skill contributes export-specific questions, invariants, fixtures, and checks.
That division lets both run without asking either skill to override the other.
How to read this: this is a recommended responsibility model, not a claim about an undocumented Codex arbitration engine. Every lower layer should operate inside constraints established above it.
Direct requests and project instructions define the task envelope. Superpowers itself states that user instructions take precedence over its skills.[5]
Superpowers orders process skills before implementation skills, so brainstorming can shape the approach before domain execution begins.[5]
Your skill supplies the export-specific invariants and verification commands at the relevant steps.
Write a skill when the workflow repeats#
A skill is worth maintaining when the same specialized work keeps returning and you can describe how to recognize, perform, and verify it. A standing repository rule belongs in AGENTS.md. A one-off outcome belongs in the prompt.
Use for temporary scope, acceptance criteria, and choices that are unlikely to repeat.
Use when every task in a directory should receive the instruction, whether or not a skill activates.
Use for reusable process: ideation, planning, TDD, debugging, review, and verification.
Use when trigger words, references, scripts, and evidence checks belong together.
Package skills as a plugin when other people should install them, when multiple skills travel together, or when connectors and tools belong in the same bundle.[3]
Do not write one yet
The workflow has happened once.
You cannot state a precise trigger boundary.
The content is mostly generic coding advice already covered by Superpowers.
There is no verification step—only prose.
Write your own
The same domain task recurs across features or repositories.
The trigger can be named with concrete verbs and objects.
The workflow needs local references, templates, or scripts.
Success can be checked with observable evidence.
Decision check
Choose the right owner
The goal is not to memorize a hierarchy. It is to assign policy, process, and domain knowledge to layers that can compose without surprise.
Primary material#
The article separates documented Codex behavior from recommended workflow architecture. Product behavior comes from official OpenAI documentation; Superpowers behavior comes from its maintained repository.
- Build skills Official OpenAI documentation — activation modes, progressive disclosure, skill scopes, duplicate names, and plugin distribution.
- Custom instructions with AGENTS.md Official OpenAI documentation — discovery, instruction chaining, and project-directory precedence.
- Plugins Official OpenAI documentation — plugins as bundles of skills, connectors, MCP servers, hooks, and other capabilities.
- Superpowers repository Obra / Jesse Vincent — project overview, installation paths, methodology, and the documented development workflow.
- Using Superpowers skill Obra / Superpowers — skill invocation rule, process-before-implementation ordering, and user-instruction priority.
