Token Efficient Subagent Decomposition

Default to one agent; delegate only bounded side work that repays its coordination cost.

默认单代理；只在边界清晰且收益覆盖协调成本时才拆分给子代理。

English

This repository packages a Codex skill for deciding when subagents are worth using and how to keep delegation lean once you decide to use them. The skill is intentionally small: it gives you a routing rule, a compact handoff template, and a few coordination rules that reduce token waste without sacrificing task quality.

Why This Skill Exists

Many multi-agent setups spend tokens on the wrong things: repeated planning, overlapping exploration, long handoffs, and unnecessary synchronization. This skill pushes work back toward the critical path and only delegates side work when the coordination cost is justified.

What You Get

• A default single-agent routing rule
• A bounded-task delegation checklist
• A compact handoff template for subagents
• Lightweight coordination rules for low-overhead parallel work
• Practical delegation patterns and anti-patterns

Repository Layout

• SKILL.md: the skill itself
• agents/openai.yaml: UI metadata for Codex
• references/patterns.md: concrete patterns, anti-patterns, and a minimal spawn prompt
• assets/hero.svg: original MIT-licensed GitHub hero artwork
• MARKETING_COPY.md: bilingual launch copy for GitHub, posts, and repo descriptions

Install

Install directly from GitHub:

python3 "$HOME/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo RichradsY/token-efficient-subagent-decomposition \
  --path . \
  --name token-efficient-subagent-decomposition

This exact command was validated against the published GitHub repository.

Or install manually after cloning:

git clone https://github.com/RichradsY/token-efficient-subagent-decomposition.git
cp -R token-efficient-subagent-decomposition "$HOME/.codex/skills/token-efficient-subagent-decomposition"

Invoke

Prompt invocation:

Use $token-efficient-subagent-decomposition to decide whether delegation is worth it and how to keep subagent handoffs lean.

Natural-language invocation:

Use Token Efficient Subagent Decomposition to split this task and keep the subagent handoff lean.

Example:

Use $token-efficient-subagent-decomposition to decide which parts of this coding task should stay local and which parts can be delegated in parallel.

Background

This skill was distilled from an iterative workflow rather than invented in one pass. It started from a practical question: how do you measure token efficiency for agent systems, and how do you reduce tokens without reducing output quality? From there, the work moved through three stages:

• building a synthetic token-efficiency benchmark inspired by autoresearch
• extending that benchmark from static multi-agent settings to dynamic collaboration
• adding explicit decomposition metrics such as merge tax, blocked tax, and decomposition score

The skill emerged after those experiments repeatedly converged on the same pattern: default to single-agent execution, protect the critical path, spawn side workers only when they are clearly bounded, and keep handoffs structured and compact. In other words, the skill is the operational summary of what the benchmark kept rewarding.

Visual

The repository hero artwork in assets/hero.svg is original to this project and covered by the same MIT license as the repository. It is designed to show the core operating rule visually: keep the critical path local, route only bounded side work to subagents, and merge results back through a lean handoff.

Best Fit

Use this skill when:

• the user explicitly asks for subagents or delegation
• the task has independent side work that can run in parallel
• you need a low-overhead handoff structure
• you want to avoid chatty multi-agent orchestration

Keep work local when the task is tightly coupled to the current critical path.

中文

这个仓库打包了一个 Codex skill，用来判断什么时候值得启用子代理，以及在决定拆分后如何把委派成本压到最低。这个 skill 刻意保持精简：它提供一套路由规则、一个紧凑的交接模板，以及几条低开销协作规则，用来减少 token 浪费，同时尽量不牺牲任务质量。

为什么需要这个 Skill

很多多代理系统把 token 花在了错误的地方：重复规划、重叠探索、冗长交接，以及没有必要的同步。这个 skill 的目标是把工作尽量拉回关键路径，只在协调成本确实值得时才把旁路任务拆给子代理。

你会得到什么

• 默认单代理的路由规则
• 边界清晰任务的委派检查清单
• 面向子代理的紧凑交接模板
• 低开销并行协作规则
• 实用的 delegation patterns 与 anti-patterns

仓库结构

• SKILL.md：skill 主体
• agents/openai.yaml：Codex UI 元数据
• references/patterns.md：具体模式、反模式和最小 spawn prompt
• assets/hero.svg：原创的 GitHub 头图，随仓库一并采用 MIT license
• MARKETING_COPY.md：适合 GitHub 与发布渠道的中英文文案

安装

直接从 GitHub 安装：

python3 "$HOME/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo RichradsY/token-efficient-subagent-decomposition \
  --path . \
  --name token-efficient-subagent-decomposition

上面这条命令已经针对当前公开 GitHub 仓库实际验证通过。

或者先 clone 再手动复制：

git clone https://github.com/RichradsY/token-efficient-subagent-decomposition.git
cp -R token-efficient-subagent-decomposition "$HOME/.codex/skills/token-efficient-subagent-decomposition"

调用方式

在提示词里直接调用：

请使用 $token-efficient-subagent-decomposition 帮我判断这个任务是否值得拆给子代理，并尽量压缩交接成本。

也可以自然语言调用：

请用 Token Efficient Subagent Decomposition 帮我拆这个任务，并保持子代理之间的交接尽量精简。

示例：

请使用 $token-efficient-subagent-decomposition 帮我判断这项编码任务里，哪些部分应该留在本地处理，哪些部分适合并行委派。

产生背景

这个 skill 不是一次性拍脑袋写出来的，而是从一轮轮实验里蒸馏出来的。起点是一个很实际的问题：怎样衡量 agent system 的 token efficiency，以及怎样在减少 token 的同时不降低输出质量。围绕这个问题，整个过程大致经历了三步：

• 先搭建一个受 autoresearch 启发的 synthetic token-efficiency benchmark
• 再把 benchmark 从静态多代理扩展到动态协作
• 最后加入更直接的拆解评估指标，比如 merge tax、blocked tax 和 decomposition score

这个 skill 就是在这些实验之后形成的。因为 benchmark 一再收敛到同一组原则：默认单代理执行，保护关键路径，只在 side work 边界清晰时才启用子代理，并且始终使用结构化、紧凑的交接方式。换句话说，这个 skill 本质上就是实验结果的操作化总结。

配图说明

assets/hero.svg 是这个仓库的原创头图，并且与整个仓库保持同样的 MIT license。它把这个 skill 的核心原则可视化了出来：关键路径留在本地，只把边界清晰的 side work 拆给子代理，再通过精简交接回流到主流程。

适用场景

这个 skill 适合在以下情况下使用：

• 用户明确要求使用子代理或 delegation
• 任务里存在可并行的独立 side work
• 你需要低开销的交接结构
• 你希望避免啰嗦的多代理编排

如果任务和当前关键路径高度耦合，就应优先本地处理，不要拆分。