技能规划器：把"想法"自动拆成可执行的分阶段实现计划
- 定位清晰：skill-planner（技能规划器，技能 ID 12873）是一个"薄包装器"技能，它本身不直接写计划，而是把计划创建委托给
planner-agent子代理，自己负责前后流程的把控。 - 关键创新：它实现了"技能内部后置飞行"，即在子代理返回后由技能自己完成状态更新、工件链接与 git 提交，从而消除技能返回与编排器之间反复出现的"继续"提示问题。
- 状态可追踪：全程围绕
state.json与TODO.md做状态机流转（[NOT STARTED]/[RESEARCHED]→[PLANNING]→[PLANNED]），每个任务的推进情况都能看得见。 - 产物可落地：最终会在
specs/{NNN}_{SLUG}/plans/下生成实现计划文件，并自动登记到工件列表与 TODO 清单中，同时完成一次带会话 ID 的 git 提交。 - 适合谁用：需要把"已经调研完但还没动手"的需求正式化、需要阶段拆分与工时估算的开发者、小团队与技术负责人。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | 技能规划器 |
| 技能英文名 | skill-planner |
| 技能 ID | 12873 |
| 核心作用 | 基于研究发现，为一个任务创建分阶段的实现计划 |
| 触发方式 | 任务状态允许规划时、调用 /plan 命令时、需要正式化实现方法时 |
它解决什么问题
在实际开发中，最常见的时间黑洞不是"写代码"，而是"从调研结论到动手落地"这一段：需求已经摸清，但没人把它拆成阶段、估算工时、识别风险，于是任务长期停在"已研究"状态。skill-planner 就是为这一步设计的——它把"写计划"这件事标准化、自动化，并让计划产出物具备可追溯的文件形态，而不是散落在聊天记录里的一段话。
一键安装的思路与步骤
安装环节的具体命令、入口与市场地址，技能详情中并未给出，因此这里只描述通用路径，具体操作以官方说明为准：
- 确认运行环境前提：该技能声明了
Task、Bash、Edit、Read、Write等工具权限，并依赖 git、jq、mkdir 等命令行能力，因此需要在一个支持「技能（Skill）+ 子代理（Subagent）」机制的 AI 编程助手环境中使用，且项目需为 git 仓库。 - 按技能 ID 检索并安装：在技能市场或技能仓库中使用技能 ID 12873 或英文名 skill-planner 进行检索，选择一键安装。安装命令与安装入口以官方说明为准。
- 确认依赖文件就位：技能会引用
.opencode/context/core/formats/return-metadata-file.md、.opencode/context/core/patterns/postflight-control.md等上下文文件，但这些文件由委托的子代理按需加载，技能本身只做引用、不做急加载，通常无需手动干预。 - 验证是否生效：最直接的验证方式是观察技能是否被正确触发——当某个任务处于"未开始"或"已研究"状态时执行
/plan {任务号}，若技能正常激活，任务状态会先被置为planning，随后在specs/目录下出现计划产物与元数据文件。
这种"一键安装 + 命令触发"的思路，本质是把成熟工程流程（调研 → 规划 → 执行 → 归档）固化成可复用的技能单元，装一次，后续每个任务都能复用同一套规范。
2. 该技能的主要功能和特点
- 薄包装器 + 子代理委托：技能自身只做流程编排，真正的计划撰写交给
planner-agent子代理完成。子代理会加载规划上下文、分析任务需求与研究成果、拆分为逻辑阶段、识别风险与缓解措施。 - 技能内部后置飞行（Postflight）：这是它区别于普通规划工具的最大特点。子代理返回后，技能会自行完成状态更新、工件链接与 git 提交，然后才返回，避免了"技能已返回但流程没走完"导致的反复续推问题。
- 双写状态机管理：同时维护结构化状态文件
state.json与人类可读的TODO.md，状态从[NOT STARTED]/[RESEARCHED]推进到[PLANNING]，成功后落到[PLANNED]。 - 文件化元数据交换：子代理不直接返回 JSON，而是把元数据写入
specs/{NNN}_{SLUG}/.return-meta.json，技能再读取该文件解析状态与工件信息，返回给用户的则是一段简要文本摘要，可读性更好。 - 标记文件防早终止：通过
.postflight-pending标记文件声明"后置飞行待处理"，防止流程在关键收尾阶段被提前打断。 - 工件去重与安全追加：更新工件列表时，先用两步 jq 模式过滤掉旧的
plan类型工件，再追加新工件，规避了 jq 转义问题（问题 #1132）导致的解析失败。 - 失败可恢复：子代理默认超时 1800 秒；若超时或元数据文件缺失，任务状态会保持在
planning，清理动作不执行，用户可以再次运行命令续跑，而不是从零重来。 - 自动 git 提交：计划产出后自动执行提交，提交信息中带上会话 ID，便于回溯"哪一次会话产出了哪份计划"。
与普通"让 AI 直接生成一份计划"相比，它的强项在于流程闭环：有前置校验、有状态流转、有产物落盘、有提交记录、有失败恢复策略。
3. 如何使用该技能？
以下为基于技能详情整理的分步骤使用指南。
第 1 步：确认任务已存在且状态允许规划
技能会先在 state.json 的 active_projects 中按任务号查找任务。若任务不存在会直接报错；若任务状态为 completed，同样会返回"任务已完成"的错误。因此请先确保任务尚未完成。
第 2 步：确保任务已完成研究（推荐） 技能支持加载研究报告路径。若该任务此前已有研究产出，规划质量会明显更高；没有研究也能运行，但计划会更依赖任务描述本身。
第 3 步：调用命令触发规划
/plan 414
其中 414 是任务号（task_number）。这是技能的主要调用入口。
第 4 步：观察状态变化
技能会先执行预飞行更新，把 state.json 中该任务的状态改为 planning 并写入 last_updated 与会话 ID，同时把 TODO.md 中的状态标记改为 [PLANNING]，随后创建 .postflight-pending 标记文件。
第 5 步：等待子代理产出计划
技能通过 Task 工具（而不是 Skill 工具）派发 planner-agent 子代理，携带任务上下文、委托链路、研究路径和元数据文件路径。子代理会在 specs/{NNN}_{SLUG}/plans/ 下生成实现计划文件，并把结果写入 .return-meta.json。
第 6 步：查看返回摘要 成功时返回的是一段纯文本，形如：
为任务 414 创建计划：
- 定义了 5 个阶段，估计 2.5 小时
- 覆盖：代理结构、执行流程、错误处理、示例、验证
- 计划创建于 specs/414_create_planner_agent/plans/implementation-001.md
- 状态更新为 [PLANNED]
- 更改已提交，会话 sess_1736700000_abc123
第 7 步：查阅落盘产物
打开计划文件阅读阶段划分；TODO.md 中会出现形如 - **计划**：[implementation-414.md](...) 的工件链接；state.json 中该任务的 artifacts 数组会追加 plan 类型条目。
第 8 步：异常时的处理
若返回的是"部分创建"摘要（例如"在超时前定义了 3 个阶段，共 5 个"），说明子代理超时，状态会保持在 [PLANNING]，此时重新运行 /plan 414 即可继续完成。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| skill-planner（技能规划器） | 面向任务工作流的自动化规划技能 | 委托子代理生成分阶段计划、状态机流转、工件链接、自动 git 提交、失败可恢复 | 需支持 Skill + Subagent 的运行环境，依赖 git 与 jq；按技能 ID 安装，具体入口以官方说明为准 | 已有研究结论、需要正式化落地的开发任务；多任务并行的项目 | 优势：流程闭环、产物可追溯、可续跑；不足：对目录结构与状态文件有约定，首次接入需要理解其工作流 |
| AI 助手对话式规划 | 直接对话让 AI 输出计划 | 根据提示词生成步骤列表 | 门槛最低，无需额外安装 | 一次性、轻量的思路梳理 | 优势：零配置、即问即答；不足：无状态、无产物文件、无提交记录，计划容易丢失在聊天记录中 |
| 人工编写设计文档 / 计划模板 | 传统工程实践 | 由人按模板撰写阶段、工时、风险 | 依赖人的经验与时间投入 | 需求复杂、需要多方评审的项目 | 优势：质量上限高、可评审；不足：耗时，小任务性价比低，容易拖延 |
| 通用任务管理工具（看板/待办类） | 任务跟踪与协作 | 任务拆解、指派、进度看板 | 门槛低，但需手动录入 | 团队协作与进度可视化 | 优势：协作能力强；不足：不生成具体实现方案，拆分动作仍需人完成 |
可以看出，skill-planner 的差异化不在于"能不能生成计划"，而在于把计划生成嵌入到任务状态机与版本控制中，让计划成为项目资产的一部分。
5. 该技能的典型应用场景与实际体验情况
场景一：独立开发者的"调研完但不敢动手"
角色：独立开发者。痛点是调研做完后，面对一个大需求不知道从哪一步开始，容易陷入无限期拖延。使用方式是调研任务完成后直接 /plan {任务号}，拿到阶段划分与工时估算，再按阶段逐个击破。实际体验：上手难度中等偏低，只要理解"先有任务、再调命令"的顺序即可；效果上，把模糊需求变成可执行条目是最直接的收益。
场景二：小团队的需求交付与评审
角色：技术负责人。痛点是多人协作时，"计划"存在于某个人脑子里，评审时说不清。使用方式是把规划产物作为评审材料，因为它落盘为固定路径下的 Markdown 文件，并自动登记到 TODO.md，评审时可以直接对照阶段与风险项。实际体验：产物的可追溯性很强，提交记录里带会话 ID，事后复盘也能定位。
场景三：多任务并行的项目推进
角色：承担多个任务的全栈开发者。痛点是在多个任务间切换时容易丢失上下文状态。使用方式依赖技能的状态机能力：[PLANNING] 与 [PLANNED] 的标记让人一眼看出哪些任务卡在规划阶段。实际体验：这是该技能最被低估的价值——它让"卡住的任务"变得可见。
场景四：长任务超时后的续跑
角色：处理复杂需求的工程师。痛点是规划本身可能耗时较长（子代理默认超时 1800 秒），一次没跑完就得重来。使用方式是在收到"部分创建"摘要后，直接重跑同一条命令，因为状态被有意保留在 planning。实际体验：恢复机制设计合理，但需要注意重跑前不要手动改动状态文件。
注意事项：该技能对 state.json 的结构、任务目录命名（{NNN}_{SLUG}）有明确约定，手动改动这些文件可能导致后续 jq 查询失败；另外 git 提交失败被定义为非阻塞错误，会继续返回成功响应，因此建议事后自行确认提交是否真的落地。
6. 该技能能为用户带来的价值
效率层面：把"从研究到计划"这一步从手工劳动变成一次命令调用。原本需要半小时到一小时整理的阶段划分、工时估算与风险清单，变成一次命令触发的自动产出，且产出格式统一。
门槛层面：规划能力通常依赖经验——初级开发者往往不知道该拆几层、该不该估时。技能通过 planner-agent 固化了规划方法论（阶段拆分、风险识别、缓解措施），让经验不足的人也能拿到结构完整的计划。
可量化收益：可直接观察到的指标包括——每次规划节省的撰写时间、计划中定义的阶段数与估算工时、任务从 [RESEARCHED] 到 [PLANNED] 的状态流转耗时，以及 TODO.md 中可点击的计划产物链接数量。
长期价值：所有计划都以文件形式沉淀在版本库中，形成可复用的项目知识资产；状态机与提交记录让项目历史可审计；而"后置飞行"这种把收尾动作内聚到技能内部的设计思路，也为搭建其他自动化技能提供了可参考的范式。
7. 常见问题 FAQ
Q1：这个技能怎么安装？
在支持技能机制的环境中，按技能 ID 12873 或英文名 skill-planner 检索并一键安装即可。具体安装命令、市场入口与配置方式以官方说明为准。安装前请确认环境支持 Skill 与 Subagent（Task 工具），并且项目是 git 仓库。
Q2：使用它收费吗？ 技能本身是否收费取决于其发布渠道与授权方式，本技能详情中未包含定价信息，请以官方说明为准。需要注意的是，它依赖底层 AI 模型的调用额度，这部分成本由你所使用的模型服务决定。
Q3：它适合谁用？ 最适合已经完成需求调研、需要把结论转成可执行阶段计划的开发者与技术负责人；也适合需要统一团队规划产出格式的小团队。如果只是想要一个随口的思路梳理，直接用对话式规划更轻便。
Q4：和直接让 AI 生成一份计划有什么区别？ 区别在闭环。直接对话生成的是"一段文本"，用完即散；skill-planner 会校验任务状态、更新状态机、把计划写入固定目录、登记到 TODO 清单、追加到工件列表，并完成一次带会话 ID 的 git 提交。计划因此成为可追溯的项目资产。
Q5：规划中途失败或超时了怎么办？
状态会被有意保留在 planning，后置飞行的标记文件也不会被清理。此时重新执行 /plan {任务号} 即可续跑。如果返回的是"部分创建"摘要，说明已生成的阶段会被保留。另外若 git 提交失败，技能会记录但不阻塞返回，建议自行确认提交状态。