skill-planner（技能规划器）Skill 是什么？如何安装？

技能规划器Skill：把「想到哪做到哪」变成可执行的分阶段实施计划

一条命令即可生成实施计划：调用 /plan 后，技能规划器Skill 会把工作委托给 planner-agent 子代理，自动完成任务分析、阶段拆分、风险识别，并产出可执行的计划文档。
不只是「写一份计划」：它内置技能内部后处理流程，计划生成后会自动更新 state.json 与 TODO.md 状态、链接计划文档、执行 Git 提交并清理临时文件，形成一个完整流程。
解决 AI 长任务的「中断抖动」：通过 .postflight-pending 标记文件协议，防止子代理返回后流程被过早终止，减少反复输入「继续」的沟通成本。
失败可恢复：子代理默认 1800 秒超时，超时或元数据缺失时保持 [PLANNING] 状态，可再次执行 /plan 续跑，不会污染已完成的任务状态。
适合谁用：使用 AI 编程代理做中大型任务、需要留下计划痕迹、需要状态可追溯的开发者与技术负责人。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能规划器Skill（英文名 skill-planner，技能ID 12886）是一个「按需调用、专注一件事」的技能：从已有的研究结论出发，为某个具体任务创建分阶段实施计划。

它解决的问题很具体：当任务从「调研完成」走向「动手开发」时，人往往容易直接开始写代码，结果做到一半才发现漏了边界条件、忘了错误处理、也没人记得当初为什么这么设计。技能规划器Skill 把这一步规范化——把任务拆成有序阶段，标明风险与缓解措施，落盘成文档，并把任务状态从「已研究」推进到「已规划」。

安装前提

从技能详情可以看出，它依赖一套「规格驱动」的项目结构，安装前建议确认以下几点（具体安装方式与目录约定以官方说明为准）：

具备支持技能（Skill）机制与子代理（Subagent）调用的 AI 编程环境，且已存在 .claude/ 上下文目录；
项目内存在状态文件 specs/state.json（任务状态机）与 TODO.md（状态标记看板）；
环境中可使用 jq（技能内部大量使用 jq 读写 JSON 状态）与 git（计划生成后会执行提交）；
已注册 planner-agent 子代理，否则委托环节无法完成。

安装步骤（通用思路）

获取技能包：从官方技能市场或仓库获取 skill-planner 的技能目录，具体下载地址以官方说明为准。
放入技能目录：将技能目录置于 AI 编程环境约定的技能路径下（通常是项目级或用户级的技能目录），使 /plan 命令可被识别。
准备项目结构：确认 specs/state.json 存在且包含 active_projects 数组，任务具备 project_number、status、project_name 等字段。
确认子代理可用：确保 planner-agent 已在子代理列表中注册，且技能允许使用的工具（Task、Bash、Edit、Read、Write）均已放开。
重启或重载会话：让环境重新扫描技能清单，使新技能生效。

如何验证是否生效

对一个状态为「未开始」或「已研究」的任务号执行 /plan <任务号>，观察 specs/state.json 中该任务 status 是否先变为 planning；
观察 TODO.md 中对应任务标记是否从 [NOT STARTED]／[RESEARCHED] 变为 [PLANNING]；
任务目录下是否短暂出现 .postflight-pending 标记文件（流程结束后应被自动清理）；
最终是否生成 specs/{NNN}_{SLUG}/plans/implementation-{NNN}.md，且 TODO.md 里出现计划文档链接；
用 git log 查看是否新增一条形如「任务 N：创建实施计划」的提交记录。

只要以上任一条链路走通，基本可以确认技能已正确装载。

该技能的主要功能和特点

薄包装设计，职责单一：技能本身只做编排，真正的计划生成交给 planner-agent 子代理，技能侧不塞入冗长的规划提示词，便于维护和替换。
输入校验与状态机守门：先校验 task_number 是否提供、是否存在于 state.json、状态是否允许规划；对已完成任务直接返回「任务已完成」，避免重复劳动。
预飞行状态更新：在调用子代理之前就把状态改为 planning，并写入会话 ID 与时间戳，即便后续中断，也能看出「这个任务正在被规划」。
标记文件协议（.postflight-pending）：通过标记文件防止子代理返回后被过早终止，从机制上缓解「技能返回与协调器之间反复提示继续」的老问题。
元数据文件交换：子代理把结构化结果写入 .return-meta.json，技能读取状态、工件路径、类型与摘要；技能对外只返回一段简短文本摘要，把 JSON 噪音留在文件里。
工件链接的去重逻辑：写入计划工件前，先用「保留非 plan 工件」的两步 jq 模式过滤旧计划，再追加新计划，避免同一任务堆积多份互相矛盾的计划条目。
异常处理考虑充分：元数据缺失时保持 planning 并保留标记；Git 提交失败按非阻塞处理；jq 转义异常会记录到 errors.json 并按规避方案重试；超时则返回部分结果以便恢复。
自动留痕：计划生成后自动执行 Git 提交，把「计划」这一决策过程变成可追溯的版本历史，而不只是聊天窗口里的一段文字。

和普通「让 AI 列个计划」相比，它的差别不在于文笔，而在于状态、工件、提交、恢复这四个工程化环节都被管起来了。

如何使用该技能？

以下按实际操作顺序说明，示例任务号为 414（仅为演示）。

步骤 1：确认任务已就绪 打开 specs/state.json，找到目标任务的 status，确认它不是 completed，通常是「未开始」或「已研究」。若任务已经完成研究，计划质量会明显更好。

步骤 2：发起规划 在会话中执行命令：

/plan 414

技能会自动触发。你也可以在自然语言中描述「需要一份正式实施计划」，由协调器路由到该技能，但命令方式最稳定。

步骤 3：技能完成前置动作 技能会校验任务、把状态切换为 planning、更新 TODO.md 标记、创建 .postflight-pending 标记文件，然后准备委托上下文（包含会话 ID、委托深度、1800 秒超时、任务上下文、研究报告路径、元数据文件路径）。

步骤 4：子代理产出计划 planner-agent 加载规划上下文，分析任务与研究结论，拆分为逻辑阶段，识别风险与缓解措施，在 specs/414_xxx/plans/implementation-001.md 写入计划，并把结果元数据写入 .return-meta.json。

步骤 5：读取结果 技能读取元数据文件，把状态更新为 planned，在 TODO.md 中追加计划链接，执行 Git 提交，清理标记与元数据文件，最后返回一段摘要。你会在会话里看到类似内容：

计划为任务 414 创建：定义了 5 个阶段，估计 2.5 小时；覆盖代理结构、执行流程、错误处理、示例、验证；在 specs/414_xxx/plans/implementation-001.md 创建计划；状态更新为 [PLANNED]；更改已提交。

步骤 6：审阅与修正 打开计划文档，重点看阶段顺序是否合理、风险项是否覆盖、验收标准是否可验证。若某处不认可，可直接编辑文档或让子代理重做——注意重做会替换旧计划工件条目。

步骤 7：中断后续跑 若返回的是部分结果（例如超时），状态会保持 [PLANNING]，计划文件里可能只有部分阶段。此时再次执行 /plan 414 即可从断点继续，而不是从头开始。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
skill-planner（技能规划器Skill）	面向 AI 编程工作流的实施计划编排技能	任务校验、状态推进、子代理委托、计划落盘、工件链接、Git 提交、中断恢复	需具备技能与子代理环境、`state.json` 状态文件、jq 与 git；以官方说明为准	中大型任务、需要可追溯计划与状态流转的项目	优势：全链路自动化、状态一致性强、失败可恢复；不足：依赖项目规范结构，轻量小任务显得偏重
手动撰写实施计划（文档/白板）	传统人工规划	人写阶段、排期、风险清单	零安装，但需要时间与经验	需求复杂、涉及多人协作与多方对齐	优势：灵活、可讨论；不足：耗时长、易遗漏、难以与任务状态和代码仓库联动
通用对话式 AI 直接列计划	用通用大模型对话生成计划文本	输出一段结构化建议	门槛最低，复制粘贴即可	快速头脑风暴、临时参考	优势：上手快；不足：不落盘、不更新状态、不可恢复、每次结果差异大，难以作为工程依据
项目管理工具的拆解模板（如看板/迭代模板）	项目管理层面的任务拆解	子任务、负责人、工时、状态流转	需要账号与配置，团队协作成本较高	多人团队排期与进度跟踪	优势：协作与可视化强；不足：缺少「从研究到计划」的自动生成能力，与本技能的代码仓库联动能力不重叠

从对比看，技能规划器Skill 的核心竞争力不是「更会写计划」，而是把计划接入了任务状态机与版本控制，这是通用对话与文档模板都做不到的。

该技能的典型应用场景与实际体验情况

场景一：独立开发者用 AI 代理做中大型功能 角色是独立开发者，痛点是任务一旦变复杂，AI 代理容易跳步骤，做到一半才发现没处理错误分支。使用方式是先让代理完成任务研究，再执行 /plan，拿到分阶段计划后逐阶段推进。实际体验：上手成本主要在前期项目结构（state.json 等）的准备，一旦跑通，后续每次只需一条命令；效果最明显的是「阶段有明确边界」，代理不容易越界乱改；注意事项是计划文档务必人工过一遍，尤其核对风险项是否覆盖了你的特殊约束。

场景二：技术负责人做需求拆解与评审 角色是小型团队的技术负责人，痛点是要向团队解释「为什么这样分期做」，口头讲完不留痕。使用方式是对每个需求建任务、跑研究、跑规划，把生成的计划文档直接贴进评审会。实际体验：因为计划会写入文件并自动提交，评审时可以对比不同版本的计划差异，讨论有据可依；需要注意的是 Git 提交粒度较粗（一次性 add 全部改动），多人并行开发时建议先提交自己的改动，避免混入无关文件。

场景三：长任务中断后的恢复 角色是长时间挂机跑任务的用户，痛点是代理跑到一半超时，之前的工作全白费。使用方式是在超时后直接重跑 /plan <任务号>。实际体验：技能在超时或元数据缺失时会刻意保留 planning 状态与标记文件，不做清理，正是为了 Resume；效果是大部分中断能从断点继续；注意事项是如果元数据文件损坏，技能会报「无效或缺少元数据文件」，此时需要检查 .return-meta.json 是否被正确写入。

场景四：需要计划留痕的交付型项目 角色是外包或顾问型开发者，痛点是客户或审计方需要看到「方案演进过程」。使用方式是把 specs/ 目录与 Git 历史一起作为交付物的一部分。实际体验：每次规划都有独立提交记录与计划文件，回溯成本极低；需要注意 jq 处理特殊字符时可能出现转义问题（技能已内置两步模式规避，并在 errors.json 里留痕），如遇异常可查看错误日志定位。

该技能能为用户带来的价值

把「想清楚」这件事自动化：从研究结论直接产出分阶段计划，省去人工拆解与反复澄清的时间，中大型任务的规划环节通常能从数十分钟压缩到一次命令加一轮审阅。
降低使用 AI 代理的门槛：不需要写复杂的规划提示词，也不需要手动维护任务状态；状态推进、文档链接、代码提交由技能统一处理。
消除「继续」式沟通损耗：标记文件协议让流程在一次调用内闭环，减少用户在技能返回后反复催促「继续」，在长任务场景中这部分沟通成本往往占据可观的交互轮次。
可恢复、可追溯、可审计：状态机保证任务不会莫名其妙回到起点，Git 提交与计划文档共同构成决策档案，长期积累下来就是一套团队级的「方案库」。
降低协作摩擦：计划文档是天然的对齐材料，评审、交接、复盘都有唯一事实来源，减少「当初说好的是什么」这类争论。

常见问题 FAQ

Q1：这个技能怎么安装？有官方一键命令吗？ 安装方式取决于你所使用的 AI 编程环境，通常是把技能目录放入约定的技能路径并重载会话；技能详情中未提供具体的下载地址与一键安装命令，请以官方说明为准。安装前请确认已注册 planner-agent 子代理，并且项目内存在 specs/state.json。

Q2：它收费吗？ 技能本身在详情中未标注任何价格或授权信息，因此费用取决于你所用平台与技能市场的规则，以官方说明为准。需要留意的隐性成本是调用子代理会消耗模型额度，规划一个中等任务通常是一次子代理调用。

Q3：什么任务适合用它？小改动也需要吗？ 它适合「需要明确分阶段推进、可能涉及多处改动、需要留下计划痕迹」的任务。如果只是改个文案、修个拼写，直接动手更快——为极小任务跑一次规划，反而增加状态流转与提交记录的管理成本。

Q4：和直接让 AI 写一份计划有什么区别？ 关键区别在四件事：状态会被推进（[PLANNING] → [PLANNED]）、计划会写入固定路径、工件会被登记到 state.json、变更会进入 Git 历史。通用对话产出的计划通常停留在聊天窗口里，既不可恢复也不可审计。

Q5：规划过程中断了怎么办？会不会把任务搞坏？ 不会。超时（默认 1800 秒）或元数据缺失时，技能会刻意保持 [PLANNING] 状态并保留标记文件，方便你再次执行 /plan <任务号> 续跑；只有状态正常变为 planned 时才会清理并提交。如果 Git 提交失败，会被视为非阻塞问题，记录后继续返回成功结果。