routing-subagents

English | 简体中文

Target: OpenAI Codex CLI, IDE extension, and Codex in the ChatGPT desktop app Type: Local Codex Agent Skill

Match each task with a suitable subagent based on task difficulty and the capabilities Codex exposes.

routing-subagents is a Codex Skill for adaptive subagent routing. It helps the main agent decide when to work directly, when to delegate bounded work, and how to coordinate dependencies, verification, and failures. It follows the Agent Skills specification and uses only the tools and capabilities exposed by the current Codex host.

What it provides

• Keeps short, tightly coupled tasks with the main agent.
• Selects an appropriate subagent, model, role, and reasoning level when Codex supports those choices.
• Shows the execution plan before dispatching work.
• Runs independent tasks in parallel and waits for dependencies.
• Prevents duplicate dispatches and limits automatic retries.
• Verifies delegated results before reporting completion.

Install the Skill in Codex

Codex discovers local Skills from .agents/skills directories in a repository and from $HOME/.agents/skills for user-wide use. The repository root contains SKILL.md, so the directory copied or cloned into one of those locations must be named routing-subagents.

Repository-scoped installation

Run this from the repository where you want to use the Skill:

mkdir -p .agents/skills
git clone https://github.com/RocYan98/routing-subagents.git \
  .agents/skills/routing-subagents

This makes the Skill available to Codex sessions started in that repository and its subdirectories.

User-scoped installation

Use the user directory when the Skill should be available in every repository:

mkdir -p "$HOME/.agents/skills"
git clone https://github.com/RocYan98/routing-subagents.git \
  "$HOME/.agents/skills/routing-subagents"

If you downloaded a ZIP instead, copy the directory containing SKILL.md to the same location and preserve references/scoring.md.

Verify the installation

In Codex CLI or the IDE extension, run /skills and confirm that routing-subagents appears. You can then invoke it explicitly:

Use $routing-subagents to review this task, decide whether delegation is useful,
show the routing plan, and then carry out the authorized work.

Codex normally detects Skill changes automatically. Restart Codex if a new or updated Skill does not appear.

See the Codex build skills guide for the current discovery locations, explicit invocation syntax, and built-in installer behavior.

Install with a Codex Agent

Start Codex in the repository or environment where you want the Skill installed, then paste this prompt. It asks the built-in installer to use the repository URL and gives a filesystem fallback when the installer cannot fetch a custom repository:

Use $skill-installer to install the routing-subagents Codex Skill from
https://github.com/RocYan98/routing-subagents.

If the installer cannot fetch a custom repository, clone the repository and
install the directory containing SKILL.md at the user scope
($HOME/.agents/skills/routing-subagents) or the current repository scope
(.agents/skills/routing-subagents), choosing the scope I request. Preserve
references/scoring.md, hooks/, assets/, and agents/openai.yaml. Before replacing
an existing routing-subagents Skill, compare the files and report differences.
After installation, run a discovery check only: do not start a real subagent
task. Report the installed path and whether Codex needs a restart.

The prompt tells the Agent the intended installation scope; Codex still applies its normal permission checks. Review proposed filesystem changes before allowing them, especially when an existing Skill differs.

Use the Skill

After installation, mention the Skill explicitly or let Codex invoke it when the task matches its description:

Use $routing-subagents to analyze this project, document its module structure
and test coverage, and write the improvement report to docs/review.md.

In Codex CLI and the IDE extension, $routing-subagents is the explicit invocation form. /skills lists the Skills Codex can currently discover.

Optional Codex runtime metadata Hook

The optional hooks/runtime-context.py script gives the main agent its current model and reasoning effort, with the source of that information.

The output labels the source in reasoning_effort_source. Transcript evidence represents Codex’s recorded turn setting, not backend confirmation. The transcript format is not a stable API, so future changes may disable this fallback.

The script injects information through hookSpecificOutput.additionalContext on SessionStart, UserPromptSubmit, and PreToolUse. If the current turn record is not yet available when the prompt is submitted, it checks again before a tool call. A response without tool calls may still temporarily report unknown. Python 3 is required.

1. Put the script in a stable location

Keep the cloned Skill directory in a stable path. The examples below assume the script is at /absolute/path/to/routing-subagents/hooks/runtime-context.py; replace that path with the actual absolute path. Codex runs command Hooks with the session working directory, so an absolute script path avoids failures when a session starts in a subdirectory.

2. Register the Hook in hooks.json

For a user-wide Hook, create or edit ~/.codex/hooks.json. For a repository-only Hook, use /.codex/hooks.json; project-local Hooks run only after Codex trusts that project configuration. If the file already contains Hooks, merge these entries and keep the existing ones.

Use one representation per configuration layer. If a layer already uses inline [hooks] tables in config.toml, add the entries there instead of creating a second hooks.json in the same layer.

{
  "description": "Add Codex runtime metadata to routing-subagents",
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"/absolute/path/to/routing-subagents/hooks/runtime-context.py\"",
            "timeout": 5,
            "statusMessage": "Loading routing-subagents runtime metadata"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"/absolute/path/to/routing-subagents/hooks/runtime-context.py\"",
            "timeout": 5,
            "statusMessage": "Loading routing-subagents runtime metadata"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"/absolute/path/to/routing-subagents/hooks/runtime-context.py\"",
            "timeout": 5,
            "statusMessage": "Loading routing-subagents runtime metadata"
          }
        ]
      }
    ]
  }
}

Codex also supports inline Hook tables in config.toml; the event and handler structure is the same. The Codex Hooks documentation is the source of truth for current events, fields, trust behavior, and configuration syntax.

3. Review and trust the Hook

Restart Codex or open /hooks in Codex CLI to inspect the configured Hook. Codex requires you to review and trust non-managed Hooks before they run, and a changed script or definition may require trust again. Confirm that the command points to the copy you intend to execute.

4. Test the command

From the Skill directory, send a sample event to the script:

printf '%s\n' '{"hook_event_name":"UserPromptSubmit","model":"example-model","reasoning_effort":"high"}' \
  | python3 hooks/runtime-context.py

The command should return JSON containing hookSpecificOutput.additionalContext, with effort high and source codex_hook_input.reasoning_effort. This sample tests the script; it does not reveal the actual effort of your current task.

After enabling the Hook, ask Codex: “What are the current main model and reasoning effort? Include the source.” A successful transcript lookup reports transcript.turn_context.effort. If it reports unknown, check the enabled and trusted state in /hooks and confirm that PreToolUse is registered. Missing or mismatched current-turn evidence legitimately produces unknown.

The Hook is optional; the Skill remains usable without it.

Strategies

Codex compatibility and limitations

This is a prompt-based Codex Skill, not a standalone scheduling service or cross-platform API adapter. Codex executes the rules and controls tool permissions.

Project structure

routing-subagents/
├── SKILL.md                    # Codex Skill metadata and routing rules
├── agents/
│   └── openai.yaml             # Codex UI metadata and invocation policy
├── references/
│   └── scoring.md              # Scoring and agent selection guidance
├── hooks/
│   └── runtime-context.py      # Optional Codex runtime metadata Hook
├── assets/
│   ├── routing-table.png       # README preview image
│   ├── routing-table.html      # Preview layout source
│   └── codex-routing-table.png # Original Codex screenshot
├── README.md                   # English (default)
└── README.zh-CN.md             # Simplified Chinese