长任务翻车，很少是因为模型不会做，而是因为它忘了自己做到哪。上下文一压缩，前面想清楚的取舍就没了；会话一断，昨天定下的阶段顺序也没了。planning-with-files 的全部野心，就是把这件事从「求模型记性好」变成「求文件还在」。

它是 2026 年上半年最出圈的规划类 Skill 之一，作者 OthmanAdi，README 自述「不到 24 小时就引爆」。2026 年 6 月中旬的公开数据是约 2.3 万星、2000 多次 fork。它没有脚本、没有 MCP、没有向量库，全部内容就是一份 Markdown 协议加两个延伸文档。

也正因为薄，它特别适合逐行拆。下面按 SKILL.md 的原始顺序，一段一段看它到底做对了什么。

一、开头两句话，先重新定义问题

SKILL.md 的第一句是：

Work like Manus: Use persistent markdown files as your "working memory on disk."

这句话干了三件事。借势：Manus 是长程 Agent 的公开样板，读者立刻知道它想复刻什么。给心智模型：working memory on disk，把「规划」翻译成「一块不会掉电的内存」。给手段：persistent markdown files，具体到文件格式，不留解释空间。

注意它没有写「帮你更好地规划任务」。那种写法是在功能层面竞争，而这句话是在问题层面竞争：它不说自己规划得更聪明，它说自己解决了「记忆会丢」这个更底层的问题。整份 SKILL.md 后面的所有设计——为什么用 Markdown、为什么落磁盘、为什么是三个文件——都是这句话的推论。

写 Skill 的人常犯一个错：开头急着罗列能力。这份文件开头只做定位，能力留到后面用表格说。

二、Quick Start：四个动词，四个时间点

紧接着是：

Before ANY complex task:

1. Create task_plan.md in the working directory
2. Define phases with checkboxes
3. Update after each phase - mark [x] and change status
4. Read before deciding - refresh goals in attention window

四行全是动词开头：Create、Define、Update、Read。它们不是四个步骤，而是四个时间点：任务开始前、计划建立时、每个阶段结束后、每次决策前。

这是整份文件最值得抄的写法。多数提示词会写「要经常维护计划」「保持计划更新」，模型读完点头，然后继续凭记忆干活。这里把「经常」拆成了「after each phase」和「before deciding」两个可判定的时刻——阶段结束是一个事件，重大决策是一个事件，都能被模型识别。

第四条尤其关键：Read before deciding。大多数规划类提示词只要求「写计划」，不要求「读计划」。结果计划写完就变成存档，模型该跑偏还是跑偏。这一条把「读」变成了决策的前置动作，理由也写得很准确：refresh goals in attention window——不是「提醒自己」，而是把目标重新放回注意力窗口。

「Before ANY complex task」里的 ANY 用了全大写，看起来像要把触发范围拉到最大。但别急，文件后半段有一节专门踩刹车，后面会讲。

三、三文件表：一份文件契约

第三个板块是一张三列表格：

三列分别是：文件、职责、更新时机。这实际上是一份契约——每个文件只干一件事，每件事只在特定时机发生。

最妙的是第三行的 [deliverable].md。它不是固定文件名，而是一个占位符：交付物叫什么，由任务本身决定。前两个文件是过程文件，第三个是结果文件。所以「三文件」并不是机械地创建三个空 Markdown，而是三种角色的分工：

• task_plan.md 存状态：我在哪、下一步是什么、做过哪些决定。
• notes.md 存素材：查到什么、出处在哪、综合判断是什么。
• [deliverable].md 存产物：最终要交出去的东西。

理解了这个角色划分，就不会出现「把研究笔记塞进计划文件、把计划状态写进交付物」的混乱。很多团队照抄三文件却用不好，问题就出在只抄了文件名，没抄职责边界。

四、四个 Loop：写盘节奏才是核心

Core Workflow 用 code block 画了四个循环：

Loop 1: Create task_plan.md with goal and phases
Loop 2: Research → save to notes.md → update task_plan.md
Loop 3: Read notes.md → create deliverable → update task_plan.md
Loop 4: Deliver final output

看起来像四个阶段，其实不是。Loop 2 和 Loop 3 都以「回写 task_plan.md」结尾，这才是设计重点：任何一次素材增加或产物生成，都必须同步回状态文件。计划不是开工时写一次的文档，而是整个任务期间不断被修正的当前真相。

Loop 3 的顺序也值得注意：先 Read notes.md，再 create deliverable，最后 update plan。它强制模型从原始笔记里组织交付物，而不是从上下文记忆里凭印象写。笔记里有什么、出处是什么，写交付物时就能对上；记忆里剩下什么，只有模型自己知道。

再往下，SKILL.md 把三个动作和三个目的绑在一起：

Read task_plan.md  # Refresh goals in attention window
Edit task_plan.md  # Mark [x], update status
Write notes.md     # Don't stuff context, store in file

用 bash 注释写「为什么」，是这份文件的一个小技巧。模型看到 Read、Edit、Write 就知道该调什么工具，看到注释就知道调用的目的。比起抽象地说「你应该保持计划更新」，这种写法把工具名、对象、意图压进三行里，执行成本低得多。

五、模板逐字段：每个字段都在防一种失败

task_plan.md 的模板有六个区块，一个都不是装饰。

Goal：[One sentence describing the end state]。一句话，描述终态。这个约束逼你把「做一个数据分析系统」改写成「运营能在后台按周导出三类报表」。前者是方向，后者是验收条件。写不出终态，通常说明任务还没想清楚。

Phases：四个带 checkbox 的默认阶段——Plan and setup、Research/gather information、Execute/build、Review and deliver。它给了一个通用骨架，但不强制四段。checkbox 的价值不在好看，而在模型每次读文件时都能一眼看到「哪些已经 [x]」。

Key Questions：把未知显式列出来。这一栏防的是模型自作主张：遇到没定的问题时，它要么停下来问，要么替你做假设。先写进计划，等于把假设摊在桌面上。

Decisions Made：格式是「决策：理由」。它防的是反复摇摆——长任务里模型经常做到一半推翻前面的选择，有了这一栏，推翻之前至少要先读一遍当初为什么这么定。

Errors Encountered：格式是「错误：解决方式」。这栏是跨会话的疫苗。同一个报错第二次出现时，模型不用从零开始试。

Status：一行「Currently in Phase X - 我正在做什么」。这是给「下一个接手的自己」看的交接班记录。会话被清空、进程崩溃、换了一个模型，读这一行就能接上。

notes.md 的模板则只有两层：先 Sources，再 Synthesized Findings。每个来源记名称、URL、要点；综合判断单独成节。顺序不能反。先写综合、后补出处，很容易把推断写成事实；先存原始出处，再写综合，至少每个结论还能往回走一步。

六、五条铁律：覆盖五个时间点

Critical Rules 一共五条：

1. ALWAYS Create Plan First — Never start a complex task without task_plan.md. This is non-negotiable.
2. Read Before Decide — Before any major decision, read the plan file.
3. Update After Act — After completing any phase, immediately update the plan file.
4. Store, Don't Stuff — Large outputs go to files, not context. Keep only paths in working memory.
5. Log All Errors — Every error goes in the "Errors Encountered" section.

五条分别对应：开始前、决策前、行动后、存储时、出错时。时间点铺满了一个任务的全生命周期，没有一条是「态度要求」。

语气控制也很克制。「ALWAYS」只出现一次，「non-negotiable」只出现一次。整份文件没有满屏的大写和感叹号。规则的可信度靠稀缺性维持——如果每条都是 MUST，模型会把它们都当成背景噪音。

第四条是上下文工程的核心：Store, Don't Stuff。大块内容进文件，工作记忆里只留路径。这和「把上下文塞满」是两种完全不同的策略。前者的瓶颈是磁盘，后者的瓶颈是窗口；长任务里，窗口永远先满。

七、When to Use / Skip for：给触发装刹车

这一节分两半。适用场景是五条：三步以上的任务、研究任务、构建类任务、跨多次工具调用的任务、需要组织的任务。不适用场景是三条：

Skip for: - Simple questions - Single-file edits - Quick lookups

这三条是整份文件最被低估的部分。绝大多数 Skill 只写「我适合什么」，巴不得所有请求都触发自己。结果就是模型给一句「今天天气怎么样」也先建三个文件。这里明确列出否定场景，等于给触发词装了刹车。

尤其是 single-file edits。日常开发里大量请求都是改一个函数、修一行配置。这类任务创建计划文件、维护状态、回写进度，开销远大于收益。SKILL.md 自己承认这一点，反而让它在真正复杂的任务上更可信。

一个 Skill 的专业度，往往不看它说自己能干什么，而看它敢说自己不干什么。

八、反模式表：把失败案例写成动作

Anti-Patterns 是两列表格，左边是「不要」，右边是「改成」：

左列全是模型真实会犯的错，不是抽象的「不够好」。右列全是可执行动作，不是「要更加注意」。

第一行最见功力：它没有说 TodoWrite 不好，而是说「用 TodoWrite 做持久化」不好。工具本身没错，错在场景。TodoWrite 活在会话里，会话结束就没了；磁盘文件活在工作目录里，换一个会话还在。把这句话写成「不要用 TodoWrite」，会误导读者放弃一个有用的工具；写成「不要用 TodoWrite 做持久化」，边界就清楚了。

这种精确度，比多写十条口号有用。

九、两个链接文件：渐进式披露的边界

SKILL.md 末尾没有把方法论铺完，而是留了两个入口：

See reference.md for: Attention manipulation techniques / Error recovery patterns / Context optimization from Manus

See examples.md for: Real task examples / Complex workflow patterns

这是典型的渐进式披露：主文件只放「能跑通最小闭环」的内容，深水区放到链接里按需加载。好处是触发时 token 成本低，模型不会被一大堆暂时用不上的细节淹没。

代价也很明显：如果模型不点链接，深度内容等于不存在。所以主文件必须自足——读完这 100 多行，你应该能立刻开始用一个任务。reference.md 和 examples.md 是加速器，不是前提。

判断一个 Skill 的拆分是否合理，有个简单标准：把主文件单独拿走，能不能完成一次最小可用流程？这份文件可以。三文件表给了结构，四个 Loop 给了节奏，模板给了字段，铁律给了约束，停用条件给了边界。剩下的都是优化项。

十、五个可以立刻复用的写法

拆完这份文件，真正能迁移到你自己 Skill 里的，是五个模式。

1. 状态外置。 凡是跨会话、跨压缩、跨崩溃的任务，都把状态从上下文搬到文件。文件是唯一不会因为窗口满了而消失的东西。

2. 时间点绑定。 不写「经常」「及时」「注意」，写 before deciding、after each phase、at completion。模型对事件敏感，对频率副词不敏感。

3. 契约表格。 用「对象 / 职责 / 时机」三列定义每个文件、每个工具、每个角色的边界。表格比段落更难含糊。

4. 负向触发。 除了「什么时候用我」，一定写「什么时候别用我」。否定条件越具体，触发精度越高。

5. 反模式对照。 把观察到的真实失败写在左列，把替代动作写在右列。模型不需要理解原则，照着右列做就行。

如果只记一条，记第二条。同一份方法论，写成「保持计划更新」和写成「每个阶段结束后立刻回写」，效果差一个量级。

十一、边界与短板

这份 Skill 不是没有代价。

它没有强制力。 SKILL.md 是建议，不是钩子。模型完全可能口头说「已更新计划」，实际没写文件。要硬约束，得在 Agent 外层加校验：检查文件修改时间、检查 Status 行是否变化、检查 checkbox 是否真的被勾选。纯文本协议解决的是「知不知道」，不解决「做不做」。

小任务会被拖慢。 三个文件、四轮循环、六段模板，对一次单文件修改来说是重税。SKILL.md 用 Skip for 主动放弃这类场景，是明智的，但使用者仍然要自己判断「复杂」的阈值。

并发会打架。 三个文件名是固定的。同一目录下并行跑两个任务，task_plan.md 会互相覆盖。实际使用时，应该给每个任务开子目录，把三件套放进去，而不是全部堆在工作区根目录。

模板不保证判断。 阶段拆错了，后面的 checkbox 只会把错误执行得更整齐。Goal 写不清楚，一句话终态反而会锁死一个模糊目标。文件是脚手架，不是设计师。

笔记会无限膨胀。 notes.md 没有清理机制。研究型任务跑久了，笔记可能比交付物还大。需要自己加一条规则：每个阶段结束，把已经被计划吸收的素材折叠成结论，原始链接移到附录。

十二、评测对比

把 planning-with-files 和另外两种常见做法放在一起看。评分是使用体验判断，不是基准测试。

三者的差别不在功能多少，而在状态活多久。TodoWrite 活在会话里，胜在零成本，输在一清空就没。writing-plans 把计划做成更重的流程件，适合需要评审和交接的团队，但学习曲线更陡。planning-with-files 卡在中间：比 TodoWrite 重，比完整流程件轻，靠三个文件和一套读写节奏撑住长任务。

十三、安装与验证

安装有两种方式。用 skills CLI：

npx skills add OthmanAdi/planning-with-files

或者直接克隆到 Skills 目录：

git clone https://github.com/OthmanAdi/planning-with-files \
  ~/.claude/skills/planning-with-files

装完不要只看它有没有出现在列表里，做一次真实回归：

1. 给 Agent 一个明确需要三步以上的任务，比如「调研三个竞品、整理对比表、写成一份 800 字简报」。
2. 观察它是否先创建 task_plan.md，再开始搜索。
3. 中途执行 /clear 或直接开一个新会话，让它「读计划继续」。
4. 检查 Status 是否指向当前阶段，Errors Encountered 是否有记录，notes.md 是否有出处。

第三步是关键。不能跨会话续跑，这个 Skill 的最大价值就没拿到。

十四、工作流一张图

flowchart TD
    A["提出复杂任务"] --> B["创建 task_plan.md"]
    B --> C["定义阶段与关键问题"]
    C --> D["研究并写入 notes.md"]
    D --> E["回写计划状态"]
    E --> F["读 notes 生成交付物"]
    F --> G["更新计划并交付"]
    G --> H{"会话是否中断"}
    H -->|是| I["新会话读回计划"]
    I --> C
    H -->|否| J["结束"]

这张图里最重要的不是方框，是两条回边：研究之后回写计划，交付之后回写计划。没有这两条回边，三文件就只是一次性的文档模板；有了它们，计划才变成活的。

十五、按场景选

• 长程自治、跨会话任务：planning-with-files。三文件加读写节奏，是目前最轻的持久化方案。
• 一次性小改、快速问答：不要用。内置 TodoWrite 足够，甚至什么都不用。
• 需要评审、交接、多人接力的项目：writing-plans 这类重流程件更合适，计划本身就是交付物。
• 最值得学的写法：时间点绑定。把「经常更新」改成「每个阶段结束后立刻更新」，一句话就能让执行率上一个台阶。
• 最容易被忽略的写法：Skip for。敢写自己不干什么，触发才准。

十六、自己写一个的最小骨架

如果你要照着写一个同类 Skill，不必从三文件开始，先把五块写出来：

# 你的 Skill 名

一句话定位：用什么东西，解决什么失忆问题。

## 三个时间点
- 开始前：创建什么文件
- 决策前：读什么文件
- 行动后：回写什么字段

## 文件契约
| 文件 | 职责 | 更新时机 |
|------|------|---------|

## 模板
（只放必需字段，每个字段写一句它防什么失败）

## 停用条件
- 什么情况下不要用我

五块齐了，再考虑要不要加 reference.md。主文件先做到「单独拿走也能跑」，这是渐进式披露的前提。

planning-with-files 真正稀缺的地方，不是它发明了「把计划写进文件」——这件事很多人都想过。它稀缺的是克制：三个文件、五个时间点、三条停用条件，没有一句多余的口号。一个 Skill 写到这个程度，读者不需要相信作者，只需要照着做。

参考来源

1. OthmanAdi/planning-with-files — 仓库与 SKILL.md、reference.md、examples.md 原文
2. Claude Code Skills 文档 — Skill 的加载机制与渐进式披露设计
3. Equipping agents for the real world with Agent Skills — Agent Skills 的结构与设计原则

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。