| name | parallel-subagent-writing |
| description | 并行子 Agent 写作技能:将多文件写作任务分解为独立模块,用 runSubagent(全权限)在 .agent_cache 任务区域内并行创作;通过 brief.md、outline.md、deliverables.json 约束共享上下文与接口,再由主 Agent 收敛提升。Use when: 需要同时生成多个 md 文件、重构并拆分现有文档、批量创建模块骨架。 |
并行子 Agent 写作技能
用途
当任务需要同时写多个文件时,使用 runSubagent(全工具权限)并行分发写作,但不要让子 Agent 直接修改正式内容。
更合适的模式是:让子 Agent 在 .agent_cache/ 的任务区域内创作,并且共享同一份任务契约,由主 Agent 最后统一读取、筛选、验证、打包并提升到正式文件。
本技能把可重复的动作脚本化,包括:创建任务工作区与契约模板、解析绝对路径、列出产物并校验、生成 promotion bundle、清理缓存。
标准结构
SKILL.md:入口、适用范围、脚本索引
references/structure.md:sandbox 边界模型
references/workflow.md:主 agent 与 subagent 的协作流程
references/checklist.md:任务开始前、进行中、完成后的检查项
references/scripts.md:脚本逐个说明、输入输出、典型命令与串联示例
scripts/*.sh:工作区脚手架、路径解析、产物列举、缓存清理
任务契约文件
scaffold_task_workspace.sh 会在任务根目录自动生成三份契约文件:
brief.md:任务目标、受众、文风、共享上下文、术语、命名规则、全局约束
outline.md:全局目录结构、文件关系、依赖与去重边界
deliverables.json:每个 agent 的工作区、候选文件 source、正式目标 target、引用/去重约束、允许新增文件与备注
这些文件的作用是把并行写作从“自由散稿”升级为“共享合同下的并行生产”。
何时使用
- 将一个大的
.md 文件拆分为多个子文件
- 新建一个含多篇文章的知识模块
- 批量生成多个模块的骨架(如
introduction.md + 子文档)
- 任何需要并行产出多个候选文件的写作任务
核心原则
- 子 Agent 负责在 sandbox 内产出候选内容,不直接改正式文件
- 子 Agent 必须遵守
brief.md、outline.md 与 deliverables.json 的共享上下文和接口约束
- 主 Agent 负责分配工作区、读取产物、收敛结果并提升到正式模块
- sandbox 只划定边界,不强制内部目录分层
- 能脚本化的操作优先脚本化,不靠人工手拼路径、人工比对产物或手管缓存
脚本入口
./scripts/scaffold_task_workspace.sh:创建 .agent_cache/<task>/<agent>/ 工作区,并生成 brief.md、outline.md、deliverables.json
./scripts/resolve_workspace_path.sh:返回某个 agent 工作区的绝对路径
./scripts/list_task_artifacts.sh:列出任务或单个 agent 工作区内的产物文件,支持 --json 与 --verify
./scripts/prepare_promotion_bundle.sh:根据 deliverables.json 收拢已声明产物,生成 promotion bundle 与 manifest
./scripts/cleanup_task_workspace.sh:把任务缓存区归档到 .agent_cache/_trash/
具体用法、输入输出和示例命令见 ./references/scripts.md。
使用流程
- 先读
./references/structure.md,确认 sandbox 边界模型。
- 运行
./scripts/scaffold_task_workspace.sh 创建任务区、各 subagent 工作区与三份任务契约。
- 在
brief.md、outline.md、deliverables.json 中补齐共享上下文,并把每个候选产物声明为 deliverables[].source/target。
- 用
./scripts/resolve_workspace_path.sh 把绝对路径注入到 subagent prompt,并明确 Shared Context 与 Interfaces。
- 在分发 subagent 之前,先跑一次
./scripts/list_task_artifacts.sh --verify,确认契约字段完整且 schema 合法。
- subagent 在自己的工作区内创作,但必须遵守任务契约。
- 主 agent 再次运行
./scripts/list_task_artifacts.sh --verify 查看产物与契约符合度,再读取关键文件。
- 运行
./scripts/prepare_promotion_bundle.sh 生成 promotion bundle,集中审阅待提升结果。
- 主 agent 复制、摘取、
apply_patch,把结果提升到正式模块。
- 任务结束后,按需运行
./scripts/cleanup_task_workspace.sh 清理缓存。
参考文档
- 结构规则:
./references/structure.md
- 协作流程:
./references/workflow.md
- 验收清单:
./references/checklist.md
- 脚本说明:
./references/scripts.md
Anti-patterns
- 用
search_subagent / Explore agent 只读探索,再由主 agent 串行补写全部文件
- 让多个 subagent 直接写正式模块
- 不定义
outline.md 与 deliverables.json 就直接并行写
- 只把正文贴在回复里,不在 sandbox 落盘
- 明明可以脚本化的路径创建、路径解析、产物枚举、契约校验、提升打包,却仍靠人工处理
详细规范和具体约束放在 references/ 与 scripts/ 中维护,避免主入口堆砌细节。