持久化文件规划
用磁盘上的规划文件帮助编码代理跨越上下文丢失、清除会话和崩溃持续完成复杂任务。
证据显示技能主要写入项目目录中的规划文件，并提供路径解析、哈希校验、提示注入边界和门控上限；但允许 Bash、Write、Edit 等宽权限，钩子会执行 shell 命令并读取/注入本地文件，旧模式下认证默认关闭，缺少明确的用户确认、完整数据流披露和回滚机制，因此扣分。
脚本包含多种路径解析、输入校验、错误提示、计数上限和停滞检测，显示正常路径设计较完整；但本次为静态审查，没有执行或测试证据，且依赖 Claude 风格钩子、Unix 工具、PowerShell 及不同宿主行为，异常环境覆盖不足，按静态上限保守计分。
描述明确面向多步骤、长运行和上下文丢失场景，支持传统规划、并行计划及多种宿主；但触发条件主要是“5+ tool calls”等宽泛表述，非适用边界、中文交互支持和各宿主差异说明不足。核心功能为本地文件操作，不依赖海外在线服务，因此未因中国网络可达性额外扣分。
SKILL.md 具有较好的分层说明、模板、示例、脚本清单、版本元数据和已知宿主限制；但许可证、维护责任、发布流程、变更记录和稳定更新路径未在目标技能文档中充分明确，安装依赖与故障排查仍有隐藏假设，且发布者身份未验证，因此扣分。
文件化计划、恢复流程、进度记录和完成门控能够覆盖核心规划目标，示例输出也较直接可用；但“抗崩溃”“跨多个代理/宿主”和门控效果没有静态可验证的执行结果，用户仍需维护计划内容，边际收益与成本缺少比较证据，按静态上限保守计分。
脚本注释、示例和实现细节提供了一定可审计依据，且包含确定性规则和错误路径；但没有可见的测试套件、CI 覆盖或独立第三方复现证据，引用的外部材料也未形成可核验的多源证据，因此维持低分。
- 宽泛的 Bash、Write、Edit 权限与本地钩子执行可能扩大文件系统影响范围；使用前应审查工作目录、脚本路径和计划文件内容。
- 旧版模式下计划认证不是默认开启，计划文件可能包含未可信内容并被注入模型上下文；不要把计划数据当作指令。
- 宿主支持和脚本依赖差异可能导致钩子静默失效或门控降级；应在目标环境中单独验证关键路径。
- 未提供执行测试、CI 覆盖或维护责任的充分证据；发布者身份也未在 FollowSkills 注册表中验证。
这个 Skill 能做什么，适合哪些场景？
planning-with-files 是面向 AI 编码代理的文件化规划技能。它在项目目录中维护 task_plan.md、findings.md 和 progress.md，用于保存阶段、研究结果、错误与进度。技能通过生命周期钩子重新读取规划、提醒更新状态，并在停止前检查完成情况。它支持 Claude Code、Codex CLI、Cursor、GitHub Copilot、Kiro、OpenCode 等多种代理环境，并提供英语、阿拉伯语、德语、西班牙语及简体和繁体中文变体。
创建并维护 task_plan.md、findings.md 和 progress.md；在工具调用、会话开始或阶段转换时重新注入规划内容；在文件写入后提醒代理更新进度；记录研究结果和错误；通过 Stop hook 检查规划阶段是否完成；在 /clear、上下文压缩或新会话后从本地会话存储和规划文件恢复上下文；可选地使用自主模式、门控模式、运行记录账本、并行计划目录隔离和 SHA-256 计划完整性证明。
- 开发者处理包含三个以上步骤的编码任务，需要跨多个工具调用保持阶段和目标。
- 研究型代理需要持续保存浏览或分析发现，避免把所有信息塞入上下文窗口。
- 长时间运行的自主编码任务需要在上下文压缩、/clear 或崩溃后恢复进度。
- 多代理或并行会话需要通过磁盘上的计划目录共享或隔离执行状态。
- 使用 Claude Code、Codex CLI 或其他 Agent Skills 兼容环境，并希望自动检查任务是否完成。
这个 Skill 有哪些优点和局限？
- 规划状态写入磁盘，可在上下文丢失、/clear 和崩溃后恢复。
- 提供错误记录、阶段复选框和完成检查，便于追踪长任务。
- 支持自主模式、门控模式、计划隔离、账本和 SHA-256 完整性证明等可选能力。
- 覆盖多种编码代理，并提供多语言技能变体。
- 采用 MIT 许可证。
- 需要代理能够运行 shell 脚本并读写本地文件。
- 完整的生命周期自动化依赖目标平台的钩子支持；不同平台的能力并不完全相同。
- SKILL.md 的具体内容未在源材料中提供，因此无法核实其实际前置元数据和全部运行细节。
- 复杂任务会增加规划文件维护和钩子处理开销。
- README 中的 96.7% 基准仅针对 v2.21.0、claude-sonnet-4-6 的文件模式遵循度，不代表所有版本、模型或平台的整体效果。
如何安装这个 Skill？
使用 Node.js 提供的 npx 执行：npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g。也可以安装其他语言变体，例如 planning-with-files-zh。Claude Code 的高级插件安装方式是先执行 /plugin marketplace add OthmanAdi/planning-with-files，再执行 /plugin install planning-with-files@planning-with-files。具体安装路径由目标代理和安装方式决定；源材料未提供所有环境的统一手动路径。
如何使用这个 Skill？
安装后，为复杂任务触发规划工作流，例如在 Claude Code 中使用 /planning-with-files:plan，或使用 /planning-with-files:start。代理会创建三份规划文件，并在执行期间读取和更新它们。简单问题、单文件编辑和快速查询不适合使用该技能。
这个 Skill 与同类方案有什么区别？
README 将该技能与代理记忆工具区分开来：记忆工具主要用于跨会话检索事实，而 planning-with-files 管理当前任务的阶段、状态、依赖和完成检查。两者被描述为互补关系。