Superpowers + your own skills
A professional agent does not need one universal instruction file. It needs a clean division of labor: Superpowers for development process, your skills for domain-specific work, and project instructions for rules that must never become optional.
The useful question is not “Which skill is stronger?” It is “Which layer owns this decision?”
A description opens the door#
Codex can activate a skill because you named it or because the task matches its description. That means the frontmatter is not administrative metadata. It is routing logic—and vague routing creates silent misses.
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. The useful composition is sequential: one skill controls the development method; the other supplies tenant and audit constraints.
Give each layer one job#
Superpowers is a development methodology expressed as composable skills. Your own skill should not restate that methodology. It should carry knowledge the generic process layer cannot know: architecture boundaries, regulated evidence, local 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]
Put non-optional repository law here: “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. Skills are selected workflows. AGENTS.md is ambient project instruction.
Brainstorm, plan, implement, review, verify.
Tenant boundaries, audit schema, local evidence.
Rules that cannot depend on a trigger.
The concrete outcome and current intent.
There is no magic tournament#
Codex documents how skills are found and activated, but it does not publish a universal “closest skill wins” algorithm for conflicting skill instructions. If two skills share a name, they are not merged; both may appear. Engineer composition 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
Superpowers decides when clarification, planning, TDD, and review occur. Your custom skill contributes export-specific questions, invariants, fixtures, and checks.
Each owns a different dimension, so the combined workflow becomes stricter without becoming contradictory.
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 memory becomes machinery#
A skill earns its maintenance cost when the same specialized workflow must be recognized, executed, and verified repeatedly. If the requirement is merely a standing rule, use AGENTS.md. If it is a one-off outcome, use the prompt.
Use for temporary scope, acceptance criteria, and choices that are unlikely to repeat.
Use when every task in a directory must obey 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.
