| 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/ 中维护，避免主入口堆砌细节。
