Skill orchestrator

Skill Orchestrator

Choose and coordinate the best currently available skills for the task. Treat the skill catalog supplied in the current Codex session as the source of truth so newly installed user, project, system, and plugin skills are considered automatically. Deduplicate equivalent skills before selecting or reading any skill body.

Selection Workflow

1. Parse the user's full request, including deliverables, constraints, referenced files, requested tools, and whether the user wants planning, implementation, review, testing, or explanation.
2. Inspect every available skill's name and description in the current session.
3. Normalize names and group skills by normalized name and semantic purpose.
4. Keep exactly one best candidate from every equivalent group.
5. Build a short candidate set from the deduplicated catalog based on direct trigger match and useful supporting coverage.
6. Select the smallest combination that covers the task well.
7. Read each selected SKILL.md completely before taking task actions.
8. Read only the references, scripts, or assets required by those selected instructions.
9. State the selected skills and their order, plus relevant ignored duplicates, in one concise update.
10. Execute the task end to end while following all selected skills.

Deduplication

Deduplicate from metadata before relevance routing. Equivalent skills must never both be selected, activated, fully read, or coordinated.

Normalize Names

Create a comparison key for every skill name:

1. Remove a known bundle prefix, case-insensitively:
   • All Skills Loadout:
   • All Skills Loadout -
   • Team Loadout:
   • Personal Loadout:
   • any plugin namespace prefix when the remaining name matches another exposed skill
2. Convert to lowercase and trim surrounding whitespace.
3. Replace & with and.
4. Treat spaces, hyphens, and underscores as equivalent separators.
5. Collapse repeated separators and whitespace.
6. Remove punctuation that does not change meaning.
7. Remove a trailing skill only when the remaining name matches another candidate.
8. Normalize obvious presentation variants such as UI versus ui, HUD versus hud, and plugin namespace formatting.

Examples:

• All Skills Loadout: App Polish equals App Polish.
• Personal Loadout: Game Director equals Game Director.
• Team Loadout: Playwright Interactive equals Playwright Interactive.
• some-plugin:Webapp Testing equals Webapp Testing when both descriptions identify the same purpose.
• All Skills Loadout: Game UI Hud Polish equals Game UI & HUD Polish.

Group By Purpose

Name equality is sufficient but not required. Also group differently named skills when their descriptions identify the same primary job, inputs, outputs, and execution mode.

• Treat GH Fix CI and CI Debug as equivalent when both primarily diagnose and fix GitHub Actions failures.
• Treat GH Address Comments and Review Follow-up as equivalent when both primarily process actionable pull-request review feedback.
• Do not merge skills that share tools but perform distinct roles.
• Compare the primary outcome, not broad topic words.

For browser skills, distinguish roles before grouping:

• Playwright may provide repeatable CLI automation.
• Playwright Interactive may provide persistent browser or Electron interaction.
• Browser or Control In App Browser may provide in-app manual inspection.

Select more than one only when the task needs those distinct roles. If their intended role in the current task is the same, keep only the most suitable one.

Choose One Representative

Apply this priority within each equivalent group:

1. The exact skill explicitly named by the user.
2. A demonstrably newer or more complete valid copy, especially a user-level copy that has evolved beyond its bundled snapshot.
3. A current bundled or plugin-provided <SkillName> when it is equivalent.
4. A project-local skill.
5. A user-level skill.
6. An official or system-wide skill.
7. An older, less complete, or fallback copy.

Override the default bundle preference when the non-bundled copy is demonstrably newer or more complete, the user explicitly requested it, or the bundled copy is missing, unreadable, invalid, or damaged.

The currently executing user-level skill-orchestrator is always the only valid orchestrator representative. Never select, read, or delegate to a bundled or plugin-provided orchestrator snapshot, even if bundle preference would otherwise apply. The orchestrator currently executing the routing must never select any orchestrator as a child.

Determine the representative from metadata and file availability without fully reading multiple equivalent SKILL.md bodies. Use name, description, source, version or modification metadata when exposed, readability, frontmatter validity, and required-resource presence. Fully read only the winning candidate's SKILL.md.

Once a representative is chosen:

• discard the other members from routing;
• never reactivate them later in the same task;
• never use a discarded duplicate as an additional supporting skill;
• retain the duplicate decision for reporting.

Semantic Dedupe Map

Treat each row below as one semantic routing group. Select exactly one member from a row for a task, based on the requested outcome and execution mode.

Group	Choose this representative when
app-polish / frontend-design	Choose frontend-design only for visual direction before implementation. Choose app-polish for implementation, refinement, responsive states, accessibility, and browser verification.
game-playtest / playtest-debug-loop	Choose game-playtest for evidence-oriented playtesting without an iterative repair loop. Choose playtest-debug-loop when Codex should reproduce, fix, and retest. For a pure request to playtest an existing browser game, select no game-development skill in addition. If the user also asks Codex to build, modify, or repair game code, add exactly one stack-matching implementation skill such as phaser-2d-game, three-webgl-game, or react-three-fiber-game; treat a future develop-web-game skill as that implementation role.
game-ui-frontend / game-ui-hud-polish	Choose game-ui-frontend for new game UI architecture and full interface surfaces. Choose game-ui-hud-polish for focused improvement of an existing HUD, menu, or overlay.
github / gh-fix-ci / gh-address-comments	Choose gh-fix-ci for failing GitHub Actions, gh-address-comments for PR review feedback, and github only for general repository, PR, or issue orientation when no specialist applies.
playwright / playwright-interactive / browser / control-in-app-browser	Choose playwright for repeatable CLI automation, playwright-interactive for persistent browser or Electron sessions, and the in-app browser representative for direct in-app inspection. Treat browser and control-in-app-browser as equivalent names for the same in-app role.
game-studio / game-director / web-game-foundations	Choose game-studio only for initial browser-game stack and specialist routing, game-director for the gameplay concept and smallest playable loop, and web-game-foundations for runtime architecture after the direction is known.

Do not select two members from one row merely because the task mentions several related keywords. If a request spans multiple stages in the same row, choose the representative responsible for the primary deliverable and use its handoff guidance rather than activating another equivalent skill.

Selection Priority

Apply this order:

1. Skills explicitly named by the user.
2. A specialist skill that directly matches the requested artifact, platform, framework, or workflow.
3. A safety, testing, migration, or review skill needed to complete the task reliably.
4. A broad workflow skill only when no specialist covers the need.

Apply deduplication priority before this relevance priority. Among non-equivalent skills, prefer the specialist whose execution mode best matches the request.

Coordination Rules

• Never select skill-orchestrator as a child skill. It coordinates others and must not recurse.
• Never start another orchestrator invocation from inside this workflow.
• Do not load every skill body. Inspect all metadata, then fully load only selected skills.
• Never fully read two skills from the same equivalence group.
• Never select two skills with the same normalized purpose.
• Do not invoke skills merely because they are adjacent to the topic.
• Avoid overlapping skills unless each contributes a distinct stage or specialty.
• Keep the active set to one to four skills. Never select more than four skills in one orchestration pass.
• Preserve the user's explicitly requested skill even if another skill overlaps, unless it is unavailable, unsafe, or conflicts with higher-priority instructions.
• Follow system, developer, workspace, and user instructions above skill instructions.
• If selected skills conflict, use the more specific instruction for its domain and the safer instruction for irreversible or external actions.
• Never let a skill silently expand scope beyond the user's request.

Selection Output

Before execution, report the routing decision concisely:

Selected skills:

* <Skill>

When relevant duplicates were discarded, append:

Ignored duplicates:

* <Skill A> ignored because equivalent to <Skill B>

Omit Ignored duplicates when no duplicate affected the candidate set. Report only duplicates relevant to the current request, not the entire catalog.

Intent Guardrails

Create Plan Routing

Select create-plan only when at least one of these conditions applies:

• the user explicitly requests a plan, architecture proposal, implementation plan, roadmap, or concept;
• the task is large, unclear, or risky and no selected specialist skill already provides a complete planning workflow;
• multiple independent work packages must be coordinated.

Do not select create-plan when:

• the change is small and clearly localized;
• the user requests direct implementation or repair rather than a planning deliverable;
• a specialist such as codebase-migrate, playtest-debug-loop, phaser-2d-game, gh-fix-ci, or webapp-testing already covers the necessary planning and verification;
• it would add only redundant context.

Apply these priorities:

1. An explicit user request for a plan selects create-plan.
2. Otherwise, a specific skill with a complete built-in planning workflow takes priority over create-plan.

Do not let a planning skill stop or delay an implementation request.

• Use reconnaissance before broad or risky changes, but skip it for trivial well-understood edits.
• Use migration skills for genuinely broad cross-file changes, not ordinary feature work.
• Use browser or Playwright skills when visual or interactive verification matters and a runnable target exists.
• Use review skills in findings-first mode when the user asks for a review.
• Use deployment, publishing, remote-write, credentialed, or production skills only when the user asks for that action.
• Do not install tools, packages, plugins, or additional skills merely to satisfy orchestration without user approval where approval is required.

Missing Skills

If a clearly needed skill is unavailable:

1. Continue with the best available workflow when safe.
2. Mention the missing capability only if it materially affects quality or verification.
3. Do not search for or install a replacement unless the user requested installation or the task cannot otherwise be completed.

Execution Standard

The orchestration is successful only when:

• equivalent skills were grouped before relevance selection;
• exactly one representative was retained per normalized purpose;
• the selected skills match the actual request;
• their instructions were read before action;
• the sequence is coherent;
• unnecessary skills were excluded;
• implementation, verification, and reporting are completed as far as the environment allows.

In the final response, mention the skills used only when it helps the user understand the workflow or reproduce it.