Skip to content

tobihagemann/turbo / codex/skills/write-skill

write-skill

Verified

Create or update a skill that extends Codex's capabilities. Use when the user asks to "create a skill", "make a new skill", "write a skill for...", or "update this skill".

FileKindSize
SKILL.mdskill md10.0 KB
references/composition.mdmarkdown4.7 KB
references/evaluation.mdmarkdown4.0 KB
references/harness.mdmarkdown4.2 KB
references/principles.mdmarkdown7.4 KB
references/scripts.mdmarkdown4.5 KB
references/skill-reviewer.mdmarkdown5.7 KB
references/structure.mdmarkdown9.5 KB
references/tools.mdmarkdown23.2 KB
references/workflows.mdmarkdown8.4 KB
references/writing.mdmarkdown7.3 KB

references/composition.md

View on GitHub
# Cross-Skill Composition

How skills depend on, invoke, and fan out to other skills.

## Contents

- Cross-Skill Dependencies
- Explicitly Invoke Skills When the Verb Matches a Skill Name
- Keep One Concern's Fan-Out Inside One Skill

## Cross-Skill Dependencies

When a skill depends on another skill, make it an explicit numbered step. Use "Run `$skill-name` Skill" as the heading and "Run the `$skill-name` skill" in the step body. Including "skill" signals that the agent should read and follow the named skill's SKILL.md before continuing.

```markdown
## Step 1: Run `$<rules-skill>` Skill

Run the `$<rules-skill>` skill to load shared rules and conventions.

## Step 2: Do the Work

- The actual steps of this skill
```

**Style-guide dependencies get their own step, placed late:** When a skill depends on a style-guide skill that loads conventions, give the load its own discrete instruction: a numbered step, or a numbered item in an ordered list. Burying it in a paragraph of prose is what makes it skippable.

Place it before the first step the guide governs, with no work-producing step in between. In a short skill that is Step 1, as in the example above. In a longer one it lands later. Loading at Step 1 anyway can put the load ahead of the values it depends on: a guide that inspects an artifact needs the step that fetches that artifact to have run first, or it silently takes a fallback path. Late placement also skips the load entirely on runs that exit before the governed output is produced. When the governed output lives inside a conditional branch, the load is the first line of that branch.

- ✗ **Avoid**: A six-step skill loads the style guide at Step 1, gathers context through Step 5, then drafts at Step 6.
- ✓ **Good**: The same skill gathers context through Step 4, loads the style guide at Step 5, then drafts at Step 6.

Late placement has a floor: the load still precedes any step whose condition the guide defines. A step that tests for the presence, location, or shape of something the guide specifies is governed by that guide even though it produces no output of its own. Run it first and it resolves against a default the guide would have overridden, so the skill exits as a silent no-op on exactly the projects that customized that detail. Moving a cheap check ahead of an expensive load is safe only when the check's subject is fixed independently of what the guide defines.

- ✗ **Avoid**: A skill checks whether the target artifact exists, exits when it does not, and loads the style guide that defines where that artifact lives afterward.
- ✓ **Good**: The same skill loads the style guide first, then applies the existence check to the location the guide resolves.

## Explicitly Invoke Skills When the Verb Matches a Skill Name

When a step body uses an action verb that is also the name of an existing skill, the bare verb reads as inline reasoning and the agent skips the actual skill load. Name the skill explicitly so the invocation is unambiguous.

- ✗ **Avoid**: "If a check fails, halt and `<verb>`."
- ✓ **Good**: "If a check fails, run the `$<verb>` skill."

This complements the explicit numbered-step rule above by covering verb collisions inside step bodies.

## Keep One Concern's Fan-Out Inside One Skill

When a workflow needs N parallel reviewers/dimensions/perspectives (e.g., internal review + peer review, or multiple review types in one pass), put the fan-out inside one skill body rather than splitting it across sibling skills that a parent mentions "in parallel". Splitting one fan-out across siblings leaks their implementation details into the parent step.

The right shape is a single skill that emits N+1 `spawn_agent` calls and joins them with `wait_agent`. Add an opt-out (e.g., "skip peer review") for runs that want only the internal pass.

- ✗ **Avoid**: Parent skill step says "Run `$<review-skill>` and `$<peer-review-skill>` skills concurrently", leaving neither sibling able to cover the concern alone.
- ✓ **Good**: `$<review-skill>` internally spawns both internal reviewer sub-agents and a peer reviewer sub-agent; the parent just runs `$<review-skill>`.

A parent may follow two siblings together when each already fans out on its own and covers a distinct concern. Running a skill only reads its instructions into the current context, so following two lands both bodies in the same agent, which then spawns every sibling's sub-agent before joining any of them. Keep such a parent to the scope it resolves and the ordering it imposes, and leave each sibling's criteria in the sibling.

- ✓ **Good**: `$<combined-skill>` follows `$<code-skill>` and `$<docs-skill>` together, spawns every sub-agent both define before joining any, then applies a single round of fixes.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall