Skip to content
Back to search

routing-subagents

SkillWorks with Claude CodeGitHub

Use in OpenAI Codex when a main agent needs to decide whether to handle a task directly or delegate bounded work, especially for multi-step, parallel, high-risk, or cost-sensitive tasks.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rocyan98--routing-subagents/badge.svg)](/listings/rocyan98--routing-subagents)

HTML

<a href="/listings/rocyan98--routing-subagents"><img src="/api/listings/rocyan98--routing-subagents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://learn.chatgpt.com/docs/build-skills) for the current discovery locations, explicit invocation syntax, and built-in installer behavior.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 90 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: routing-subagents
  3. description: Use in OpenAI Codex when a main agent needs to decide whether to handle a task directly or delegate bounded work, especially for multi-step, parallel, high-risk, or cost-sensitive tasks.
  4. compatibility: Designed for OpenAI Codex CLI, IDE extension, and Codex in the ChatGPT desktop app with local Agent Skills. Delegation requires host-provided subagent tools; model and reasoning-level selection are optional.
  5. ---
  6. # Codex Skill:自适应子 Agent 路由
  7. 本 Skill 面向 OpenAI Codex CLI、IDE 扩展和 ChatGPT 桌面应用中的 Codex,遵循 Codex 的本地 Skill 目录与 Hook 生命周期约定。
  8. 如果当前 Agent 是被委派的子 Agent,只完成父 Agent 指定的任务,不使用本 Skill 再次拆分或创建下级 Agent。
  9. ## 使用与边界
  10. 显式请求使用 `routing-subagents`,或通过宿主的技能发现机制和项目规则加载本 Skill。无需 Hook、用户级配置、固定模型表或其他技能。技能只定义路由方法;工具调用、模型选择和权限由当前宿主提供,始终服从用户要求与宿主指令。
  11. 每个新主任务判断是否委派。补充信息、继续、授权答复、追问和状态查询沿用已有任务状态;范围扩展只评估新增或实质变化部分。
  12. ## 运行时能力
  13. 从当前宿主公开的工具描述或能力接口确认:能否创建子 Agent、可选模型或角色、模型能力、可选推理档位、并发限制、等待或读取结果的方法,以及上下文传递方式。只使用明确支持的工具和参数,不假定任何工具名、参数名、模型名单或档位名称跨平台通用。
  14. 当前主模型与档位仅取宿主提供的当前任务运行时信息。未提供时记为 `unknown`;宿主明确不支持档位设置时记为“不适用”。允许运行时 Hook 仅读取宿主提供的 transcript_path,并验证 session_id、turn_id 与 model 后,从本轮最新 turn_context.effort 补全档位,必须标注来源。该值是宿主记录的本轮设置,不等于后端执行确认。不扫描其他会话,不使用环境变量、配置默认值或其他轮次补全;未验证的值保持 unknown。若提交提示时尚未写入本轮记录,可在 PreToolUse 后使用更新的元数据。
  15. - **可以选择模型:** 按运行时候选能力选型;执行前验证模型和参数仍被宿主支持。
  16. - **只能使用默认模型或固定角色:** 根据宿主已公开的能力评估能否胜任,披露“宿主默认”或实际角色。底层模型未公开则为 `unknown`;不声称完成了跨模型优化。
  17. - **没有推理档位参数:** 省略该参数,以模型或角色能力判断;不能为了遵循表格而构造参数。
  18. - **没有子 Agent 工具:** 由主 Agent 完成可胜任的工作;确有能力缺口时说明限制和所需信息,不模拟已派发的 Agent。
  19. 信息未知不等于能力不足。使用可获得的能力描述和同类任务验证证据继续判断;无法确认执行者能否胜任时,不把它当作确定充分的候选。
  20. ## 路由判断
  21. 使用 [评分与选型参考](references/scoring.md) 为每个候选子任务单独评分。默认策略为 `balanced`,用户可选择 `economy` 或 `quality`。选择满足质量要求的模型、角色和可用档位,再评估交接、验证与返工成本。
  22. 本 Skill 明确要求:宿主允许覆盖模型时,逐任务主动选择模型与推理档位,不默认复制主模型或上一子任务的选型。存在多个可用模型时,每项至少比较两个能力相关的候选,包含一个非主模型;记录选中理由、另一候选未选理由及档位依据。只有唯一候选或用户固定模型时记录该约束。依据每个子任务实际权限、交付物和验收难度评分,不把整个项目的最高风险套到所有子任务。
  23. `balanced` 优先满足要求且能力范围贴近子任务的执行者;价格未知只限制成本结论,不阻止能力选型。所有任务选择同一模型是允许的,但必须逐项说明为何其他候选不适配或选中者证据更充分;“主模型足够强”“保险起见”“没有价格”不能单独作为选择理由。不要为了模型多样性强行降级。
  24. 三种执行模式:
  25. 1. **主 Agent 直接执行:** 极短任务、上下文高度耦合、需要重做才能验收,或没有明确委派收益时采用。
  26. 2. **串行委派:** 一个边界清晰的任务交给一个执行者;主 Agent 等待结果,只做必要验收,不重复主体工作。任务必须串行本身不排除委派。
  27. 3. **按依赖关系委派:** 独立任务可并行;有依赖的任务等待前置结果;共享写入目标必须分配唯一所有权或串行处理。
  28. 成本型委派必须有当前主执行者与候选之间的同口径成本优势证据,且能力充分、工作量足以覆盖交接成本、结果易于验证、风险分不超过 1。缺少成本证据时不以省钱为由委派;仍可因主 Agent 能力不足、独立并行收益或复核收益委派。主模型未知不阻止这些非成本型判断。
  29. 价格和速度依据需记录来源、日期、计费口径及适用条件。缺失时记为 `unknown`;不按模型名称、代际、列表顺序或能力描述猜测价格与速度,单价也不等于任务总成本。
  30. 只有在路由边界不清、错配代价明显且复核收益能覆盖调用成本时,才创建只读路由评审任务。评审者仅返回建议,不执行原任务或再创建 Agent。其他工作流确有用户确认要求时,遵循有效的确认要求;不预设其他技能、角色注册表或私有工作流存在。
  31. ## 执行披露
  32. 创建执行 Agent 前,先说明当前主模型、档位与适配状态(`sufficient`、`overqualified`、`insufficient`、`unknown`),再用一张表展示已明确的任务:
  33. | 任务 ID | 任务 | 模型/档位 | 执行关系 | 权限范围 |
  34. | --- | --- | --- | --- | --- |
  35. | T1 | 有明确交付物的子任务 | 运行时选定值,或宿主默认/不适用 | 串行:主 Agent 等待 | 本任务获授权的范围 |
  36. 表后逐任务用一句话列出“比较候选 → 选择依据;档位依据”,让模型选择可核查。若用户固定模型或宿主仅有唯一候选,写明约束即可。
  37. 表格是格式示例,不是待派发任务。宿主不支持表格时,用逐任务列表保留相同信息。每个真实任务只占一行;长说明放在表外。角色执行者可在模型栏写角色,并注明底层模型未知。评分、选择依据、成本证据和状态保留在内部记录,按用户需要展示。
  38. 披露后立即执行已获授权的明确任务,不另设路由批准步骤。缺少必要任务信息或权限时只暂停受影响部分。不得把自动执行规则解释为新增权限;任务包不得扩大用户授权范围。
  39. ## 派发与状态管理
  40. 为每个逻辑任务分配稳定 ID,维护 `任务 ID → Agent ID → 状态 → 尝试次数`。状态为 `planned → running → completed | failed | blocked`。创建成功后立即记录返回的 Agent ID;`running` 或 `completed` 的任务不得重复派发。
  41. 给执行者发送最小、自包含的任务包:目标、必要上下文、依赖结果、交付物、验证标准、权限范围和写入文件所有权。说明其他执行者可能同时工作,不得覆盖或回退他人改动。宿主支持控制历史继承时,选择满足任务所需的最小上下文;不支持时遵循其实际行为,并计入交接成本。
  42. 宿主允许选择模型或档位时显式传入选定的受支持值;只支持默认执行者时使用其默认机制并披露。不把工具示例当成所有宿主都支持的 API。
  43. 同时验证上下文继承与模型覆盖的组合约束。若当前宿主的完整历史继承禁止覆盖,选用允许覆盖的最小历史方式和自包含任务包;仅当当前工具明确支持时才使用 `fork_turns: "none"` 或轮数。宿主无法提供合法覆盖组合时使用合法默认并披露,不照搬旧技能中的相反说明。已运行或完成的任务沿用原 Agent,不为重新选型重复派发。
  44. 遵守运行时并发限制;限制未知时先串行执行,不自行假设可用槽位。按宿主支持的完成事件、等待或结果查询机制获取输出,避免高频轮询。依赖关系、披露和实际派发必须一致;子任务必须使用已取得的前置结果。
  45. 模型、角色、档位、依赖或执行方式变化时更新披露;任务目标不变时复用稳定 ID。新增范围另建任务 ID。追问和继续消息不得导致重复执行。
  46. ## 失败与重试
  47. 每个稳定任务最多自动重试 1 次,首次执行不计,更换模型也计入同一预算。重试前检查实际状态;仅只读、明确幂等或确认尚未产生副作用的任务可自动重试。有检查点时从检查点继续。
  48. 模型或参数不可用时,重新检查运行时能力,排除失败组合;有合法且充分的替代项时先披露变化再重试。不得扩大任务或权限。副作用不明、非幂等或高风险写入失败时停止该任务并报告证据。预算耗尽后不继续派发;主 Agent 接手也不能绕过重试与副作用检查。
  49. 无合法替代项时,主 Agent 只有在能力充分、执行安全且不会重放不明副作用时才能接手。否则标记 `blocked`,说明能力、权限或信息缺口。其他独立任务可继续。
  50. ## 验收与汇总
  51. 主 Agent 按任务包的验收标准验证结果,再汇总实际执行状态、已知模型或角色、档位、关键结果及证据。区分事实、推断和未知信息;说明失败、重试、替代、模型变化、未完成项和必要风险。不得只依据子 Agent 的完成声明报告验证成功。
README.md · README · 223 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # routing-subagents
  2. **English** | [简体中文](README.zh-CN.md)
  3. > **Target:** OpenAI Codex CLI, IDE extension, and Codex in the ChatGPT desktop app<br>
  4. > **Type:** Local Codex Agent Skill
  5. **Match each task with a suitable subagent based on task difficulty and the capabilities Codex exposes.**
  6. `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](https://agentskills.io/specification) and uses only the tools and capabilities exposed by the current Codex host.
  7. ## What it provides
  8. - Keeps short, tightly coupled tasks with the main agent.
  9. - Selects an appropriate subagent, model, role, and reasoning level when Codex supports those choices.
  10. - Shows the execution plan before dispatching work.
  11. - Runs independent tasks in parallel and waits for dependencies.
  12. - Prevents duplicate dispatches and limits automatic retries.
  13. - Verifies delegated results before reporting completion.
  14. ![Routing plan card showing task assignments and execution relationships](assets/routing-table.png)
  15. ## Install the Skill in Codex
  16. 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`.
  17. ### Repository-scoped installation
  18. Run this from the repository where you want to use the Skill:
  19. ```bash
  20. mkdir -p .agents/skills
  21. git clone https://github.com/RocYan98/routing-subagents.git \
  22. .agents/skills/routing-subagents
  23. ```
  24. This makes the Skill available to Codex sessions started in that repository and its subdirectories.
  25. ### User-scoped installation
  26. Use the user directory when the Skill should be available in every repository:
  27. ```bash
  28. mkdir -p "$HOME/.agents/skills"
  29. git clone https://github.com/RocYan98/routing-subagents.git \
  30. "$HOME/.agents/skills/routing-subagents"
  31. ```
  32. If you downloaded a ZIP instead, copy the directory containing `SKILL.md` to the same location and preserve `references/scoring.md`.
  33. ### Verify the installation
  34. In Codex CLI or the IDE extension, run `/skills` and confirm that `routing-subagents` appears. You can then invoke it explicitly:
  35. ```text
  36. Use $routing-subagents to review this task, decide whether delegation is useful,
  37. show the routing plan, and then carry out the authorized work.
  38. ```
  39. Codex normally detects Skill changes automatically. Restart Codex if a new or updated Skill does not appear.
  40. See the [Codex build skills guide](https://learn.chatgpt.com/docs/build-skills) for the current discovery locations, explicit invocation syntax, and built-in installer behavior.
  41. ## Install with a Codex Agent
  42. 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:
  43. ```text
  44. Use $skill-installer to install the routing-subagents Codex Skill from
  45. https://github.com/RocYan98/routing-subagents.
  46. If the installer cannot fetch a custom repository, clone the repository and
  47. install the directory containing SKILL.md at the user scope
  48. ($HOME/.agents/skills/routing-subagents) or the current repository scope
  49. (.agents/skills/routing-subagents), choosing the scope I request. Preserve
  50. references/scoring.md, hooks/, assets/, and agents/openai.yaml. Before replacing
  51. an existing routing-subagents Skill, compare the files and report differences.
  52. After installation, run a discovery check only: do not start a real subagent
  53. task. Report the installed path and whether Codex needs a restart.
  54. ```
  55. 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.
  56. ## Use the Skill
  57. After installation, mention the Skill explicitly or let Codex invoke it when the task matches its description:
  58. ```text
  59. Use $routing-subagents to analyze this project, document its module structure
  60. and test coverage, and write the improvement report to docs/review.md.
  61. ```
  62. In Codex CLI and the IDE extension, `$routing-subagents` is the explicit invocation form. `/skills` lists the Skills Codex can currently discover.
  63. ## Optional Codex runtime metadata Hook
  64. The optional [`hooks/runtime-context.py`](hooks/runtime-context.py) script gives the main agent its current model and reasoning effort, with the source of that information.
  65. | Effort source | How it is resolved |
  66. | --- | --- |
  67. | Hook event | Prefers a valid `reasoning_effort` supplied by the event. |
  68. | Current turn record | Otherwise reads only the host-provided `transcript_path`, verifies the session ID, and reads `turn_context.effort` from the newest context matching both the turn ID and model. |
  69. | No matching evidence | Returns `unknown`; never substitutes configuration defaults or a previous turn’s effort. |
  70. 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.
  71. 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.
  72. ### 1. Put the script in a stable location
  73. 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.
  74. ### 2. Register the Hook in `hooks.json`
  75. For a user-wide Hook, create or edit `~/.codex/hooks.json`. For a repository-only Hook, use `<repo>/.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.
  76. 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.
  77. ```json
  78. {
  79. "description": "Add Codex runtime metadata to routing-subagents",
  80. "hooks": {
  81. "SessionStart": [
  82. {
  83. "hooks": [
  84. {
  85. "type": "command",
  86. "command": "python3 \"/absolute/path/to/routing-subagents/hooks/runtime-context.py\"",
  87. "timeout": 5,
  88. "statusMessage": "Loading routing-subagents runtime metadata"
  89. }
  90. ]
  91. }
  92. ],
  93. "UserPromptSubmit": [
  94. {
  95. "hooks": [
  96. {
  97. "type": "command",
  98. "command": "python3 \"/absolute/path/to/routing-subagents/hooks/runtime-context.py\"",
  99. "timeout": 5,
  100. "statusMessage": "Loading routing-subagents runtime metadata"
  101. }
  102. ]
  103. }
  104. ],
  105. "PreToolUse": [
  106. {
  107. "hooks": [
  108. {
  109. "type": "command",
  110. "command": "python3 \"/absolute/path/to/routing-subagents/hooks/runtime-context.py\"",
  111. "timeout": 5,
  112. "statusMessage": "Loading routing-subagents runtime metadata"
  113. }
  114. ]
  115. }
  116. ]
  117. }
  118. }
  119. ```
  120. Codex also supports inline Hook tables in `config.toml`; the event and handler structure is the same. The [Codex Hooks documentation](https://learn.chatgpt.com/docs/hooks) is the source of truth for current events, fields, trust behavior, and configuration syntax.
  121. ### 3. Review and trust the Hook
  122. 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.
  123. ### 4. Test the command
  124. From the Skill directory, send a sample event to the script:
  125. ```bash
  126. printf '%s\n' '{"hook_event_name":"UserPromptSubmit","model":"example-model","reasoning_effort":"high"}' \
  127. | python3 hooks/runtime-context.py
  128. ```
  129. 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.
  130. 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`.
  131. The Hook is optional; the Skill remains usable without it.
  132. ## Strategies
  133. | Strategy | Preference |
  134. | --- | --- |
  135. | `balanced` (default) | Meet capability and verification requirements, prefer a capability scope that fits the subtask, then consider evidence about cost and speed. |
  136. | `economy` | Prefer a lower estimated total cost among capable candidates; do not promise savings when costs are unknown. |
  137. | `quality` | Prioritize complexity, risk, and verification needs without automatically selecting the highest reasoning level. |
  138. ## Codex compatibility and limitations
  139. | Codex capability | Skill behavior |
  140. | --- | --- |
  141. | Subagents and model selection are available | Selects from candidates exposed by Codex. |
  142. | Only a default model or fixed roles are available | Uses documented capabilities without inventing model options. |
  143. | Reasoning levels cannot be configured | Omits the reasoning-level parameter. |
  144. | The current main model is not exposed | Records `unknown` and continues feasible assessments. |
  145. | The Hook event lacks reasoning effort | Tries a strictly matched current-turn record; otherwise keeps `unknown`. |
  146. | Concurrency limits are unknown | Starts with sequential execution. |
  147. | No subagent tools are available | Completes the work the main agent can handle and explains the limitation. |
  148. 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.
  149. ## Project structure
  150. ```text
  151. routing-subagents/
  152. ├── SKILL.md # Codex Skill metadata and routing rules
  153. ├── agents/
  154. │ └── openai.yaml # Codex UI metadata and invocation policy
  155. ├── references/
  156. │ └── scoring.md # Scoring and agent selection guidance
  157. ├── hooks/
  158. │ └── runtime-context.py # Optional Codex runtime metadata Hook
  159. ├── assets/
  160. │ ├── routing-table.png # README preview image
  161. │ ├── routing-table.html # Preview layout source
  162. │ └── codex-routing-table.png # Original Codex screenshot
  163. ├── README.md # English (default)
  164. └── README.zh-CN.md # Simplified Chinese
  165. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.