<!-- title: 留存王当字帖：仿写第一课 -->

# 留存王当字帖：从 17K 星的 planning-with-files 逐行学写你的第一个 Skill

## 概述

这是本系列第 8 轮，方法论收官轮：不从零发明写法，而是找一件经过四个月市场检验的 Skill 当字帖，逐行拆它为什么这样写，再照着仿出你自己的第一件。本期样本是 planning-with-files——5 月基线榜以 17,700+ Star 登顶、9 月对账时仍是 5 月 Top8 中唯一整包幸存的「留存王」。核心发现有三：其一，最热的那件恰恰是最简单的——零脚本、零依赖，一份纯文本协议打天下；其二，它的每一段都在对模型说话而不是对人说话，「读者是模型」这一条贯彻到了行级；其三，全文可提炼出七个可直接抄的写法模式，本文附一件完整的仿写示范。

## 一、为什么是它当字帖

先对账热度与留存，数据均为本专栏历轮实测记录的转引（Star 数记录于 2026-05-16 基线报告，9 月未复测）：

- **5 月基线榜第 1 名**：17,700+ Star，是当时 GitHub 上单个 Skill 的最高 Star 数，综合评分 4.85；
- **9 月对账唯一幸存**：2026-09-13《装机对账》复核 5 月 Top8，Humanizer、Impeccable、Superpowers 均已退场或散包，唯 planning-with-files 以同名整包留在本机装机清单里，当期综合评分 4.60；
- **跨宿主通用**：基线报告记录其兼容 Claude Code、Cursor、Gemini CLI、Codex CLI 等 40+ agent 平台——一份纯 Markdown 协议，不绑定任何一家的工具命名；
- **本机在列**：`~/.claude/skills/planning-with-files/`，本文逐段引用的即这份装机版全文，含 reference.md、examples.md 两处外链结构。

一句话：它是生态里罕见的「热度、留存、跨平台、可教学」四项全满的样本，基线报告当时就给出过「最佳教学 Skill」的评语。字帖，非它莫属。

## 二、评测对比表：谁来当第一本字帖

评分维度沿用本系列权重：功能完整度 25%、设计质量 25%、实战效果 20%、上手难度 15%、社区活跃度 15%。前三行的综合分转引自本专栏已发布评测，后两行为本轮编辑评级：

| Skill | 出处 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 社区活跃度 | 综合 |
|-------|------|-----------|---------|---------|---------|-----------|------|
| planning-with-files | OthmanAdi（社区） | ★★★★★ | ★★★★ | ★★★★★（四个月留存） | ★★★★★ | ★★★★ | **4.60** |
| skill-creator | anthropics/skills（官方） | ★★★★★ | ★★★★★ | ★★★★ | ★★★★★ | ★★★★★ | **4.8** |
| pdf | anthropics/skills（官方） | ★★★★★ | ★★★★ | ★★★★★ | ★★★★★ | ★★★★ | **4.7** |
| superpowers | obra（社区） | ★★★★ | ★★★★ | ★★★（整包已退场） | ★★ | ★★ | 3.8 |
| gstack | 社区 | ★★★★ | ★★★★ | ★★★ | ★★ | ★★★ | 3.7 |

注意一个反直觉的排序：设计质量的满分给了官方造件机 skill-creator，但**字帖适宜度**的第一名是 planning-with-files。原因很朴素——skill-creator 教你造件但它自身是个多文件体系，初学者模仿它等于第一堂课就学整机装配；而 planning-with-files 一个目录、一份 SKILL.md 就是全部，抄完就能跑。第一本字帖要薄。

## 三、SKILL.md 逐段开盖：九段结构，段段有企图

以下按装机版原文顺序拆。引文保留英文原句，设计意图为本文分析。

### 第 1 段：开头一句借势

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

正文第一行不解释自己是什么，直接 borrow 信誉：Manus 的上下文工程方法论当年刷屏过，懂的一秒钟建立信任，不懂的也不妨碍往下读。你的第一件也可以这样写——如果你的 Skill 背后站着某个公认方法论（GTD、OKR、用户故事地图），开头一句话点名，比三段自我介绍都省。

### 第 2 段：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

正文最顶上给四步最小闭环，每步一个动作、一个文件名、一个符号（[x]）。这是写给模型的「30 秒上手卡」：即使模型只读到前 20 行，也已经能正确开工。给初学者的启示是——**把能跑通的路径写在第 10 行之前**，细节和理由都往后放。

### 第 3 段：三文件契约表

| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Track phases and progress | After each phase |
| `notes.md` | Store findings and research | During research |
| `[deliverable].md` | Final output | At completion |

三列分别是「产出什么、干什么用、什么时机更新」。这张表是整个 Skill 的接口文档：模型对「何时写哪个文件」的所有疑问都由它一次性回答。注意第三行文件名是个占位符 `[deliverable].md`——契约定格式，不定名字，留出适配空间。**用表格定契约**，比三段散文描述省一半 token 且无歧义。

### 第 4 段：核心工作流的循环写法

> 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

配上三行伪代码（每次大动作前 Read 计划、每阶段后 Edit 计划、存信息用 Write 落盘），它把「工作流」写成循环而不是流程图。这个选择很讲究：流程图是给人的，**循环 + 触发条件是给模型的**——模型执行时需要的是「在什么时刻做什么」的祈使句，不是视觉示意。

### 第 5 段：两个焊死的模板

task_plan.md 的模板包含六个固定小节：Goal（一句话终态）、Phases（勾选框）、Key Questions、Decisions Made、Errors Encountered、Status。notes.md 模板则固定为 Sources 与 Synthesized Findings 两大块。模板直接以完整 Markdown 代码块焊进正文，模型每次生成都逐字套用。

这是全文最值得抄的一手：**把输出格式焊死，消灭格式漂移**。不焊模板的 Skill，模型每次会现场发明一种文件结构，十次跑出十个样子；焊死了，第十次和第一次一模一样。尤其 Status 小节固定为「Currently in Phase X - 正在做什么」，下次会话接手时一眼找到断点——这是它做跨会话续命的机关。

### 第 6 段：Critical Rules 五条铁律

> 1. ALWAYS Create Plan First — This is non-negotiable.
> 4. Store, Don't Stuff — Large outputs go to files, not context. Keep only paths in working memory.

五条规则全是编号祈使句，每条一个名字（Read Before Decide / Update After Act / Log All Errors）。第一条甚至写明 non-negotiable——对模型而言，明确的强制语级差是有效的注意力权重。反面教材是「建议在合适时机考虑规划」这种客气的说法，模型会把它当耳旁风。

### 第 7 段：何时不用

> Use for: Multi-step tasks (3+ steps), research, building, multi-tool-call tasks.
> Skip for: Simple questions, single-file edits, quick lookups.

给出了精确的量化边界：三步以上才用。很多作者只写「什么时候用我」，漏掉「什么时候别用我」；没有这条，Skill 会在简单任务上被误触发，把「查个端口」搞成先立计划后开工的行为艺术。**边界写清楚，召回才干净。**

### 第 8 段：反模式对照表

| Don't | Do Instead |
|-------|------------|
| Use TodoWrite for persistence | Create `task_plan.md` file |
| State goals once and forget | Re-read plan before each decision |
| Hide errors and retry | Log errors to plan file |
| Stuff everything in context | Store large content in files |
| Start executing immediately | Create plan file FIRST |

五组「别这样/改那样」。这是对模型纠偏效率最高的文体：每一行左格是被命名过的具体坏行为，右格是替代表达。比正面说教强在——模型上下文里对「错误做法」的识别往往比「理想做法」更锐利，点名坏行为等于给判别器喂负样本。

### 第 9 段：结尾只留两扇门

> See [reference.md](reference.md): Attention manipulation techniques, Error recovery patterns, Context optimization from Manus.
> See [examples.md](examples.md): Real task examples, Complex workflow patterns.

正文到此为止，进阶内容只给链接和一行目录。SKILL.md 正文保持轻装，重货全部外置——这是渐进披露的最小实现：不命中进阶需求，那两个文件永远不会被读入。

## 四、七个可抄的写法模式

把上面九段收拢成七个可移植模式，按「第一个 Skill 该先抄谁」排序：

1. **模板焊死**：正文内嵌完整输出模板，逐字给出。消灭格式漂移，收益最大的一个模式。
2. **反面清单**：写一张 Don't/Do Instead 对照表。每行点名一个具体坏行为，不给抽象形容词。
3. **契约表格化**：产出物用「文件/用途/更新时机」三列表定义，占位符留适配空间。
4. **速查卡前置**：四步以内最小闭环写在正文最顶，理由和细节全部后置。
5. **磁盘当内存**：明说 Store, Don't Stuff——大产出落盘，上下文里只留路径。
6. **出错入档**：模板里固定 Errors Encountered 小节，错误写进文件而非现场重试，失败变成跨会话记忆。
7. **借势一句 + 重货外置**：开头一句话站上公认方法论，结尾只留链接门——正文轻装，是纯文本件能四个月不散包的原因。

## 五、照着仿：你的第一个 Skill

仿写的对象要换个领域，才能证明模式可迁移。以「万字调研报告」为例，一份可直接落盘的 SKILL.md：

```markdown
---
name: longform-report
description: 写万字级调研报告时使用。把长文写作拆为大纲、素材、成稿三个
  文件分阶段推进，跨会话可断点续写。简单短文不要触发本技能。
---

# Longform Report

Work like a serial author: 大纲是骨架盘，素材是弹药库，成稿是唯一交付物。

## Quick Start
1. 先建 report_plan.md：一句话目标 + 章节勾选清单
2. 每查到一个素材立即写入 report_notes.md，标注出处
3. 每完成一章：回读 report_plan.md，勾选该章
4. 全部勾完才动笔写结论

## 三文件契约
| 文件 | 用途 | 更新时机 |
|------|------|---------|
| report_plan.md | 章节与进度 | 每章完成后 |
| report_notes.md | 素材与出处 | 查到即写 |
| report.md | 最终成稿 | 成稿阶段 |

## 铁律
1. 没有大纲不准开写。This is non-negotiable.
2. 动笔前必读 plan，刷新本章目标
3. 素材进文件，不进上下文
4. 引用必须有出处，查不到出处的素材作废

## 反模式
| 别这样 | 改成 |
|--------|------|
| 开头就冲进正文 | 先写大纲再动笔 |
| 素材贴在对话里 | 写进 notes 并记出处 |
| 卡壳了硬编 | 记入 plan 的 Open Questions |
```

**仿写注记**：三处必须改——文件名换成领域词（report_*）、触发边界重写（长文阈值写成描述里的硬条件）、反模式行换成写作场景的真实坏习惯；两处照抄——三列契约表的列结构、Status/勾选框的断点格式；一处克制——第一个 Skill **不要放脚本**，纯文本协议出问题概率最低，这正是留存王给你的隐藏教训。

## 六、它的运行闭环

```mermaid
flowchart TD
    A["新任务进入"] --> B{"是否三步以上"}
    B -->|"否"| C["直接执行"]
    B -->|"是"| D["先建 task_plan"]
    D --> E["研究并写 notes"]
    E --> F["动手前重读计划"]
    F --> G["按阶段执行"]
    G --> H["完成后勾选更新"]
    H --> I{"是否出错"}
    I -->|"是"| J["错误写入计划"]
    J --> F
    I -->|"否"| K["大产出落盘"]
    K --> L["全部勾完交付"]
    C --> M["结束"]
    L --> M
```

整个闭环没有一个脚本节点——每个环节都是「读文件、写文件、改勾选框」。零依赖就是它的护城河：没有任何一行代码会因平台升级而失灵，这也是它能穿四个月活下来的结构原因。

## 七、安装与上手

```bash
# 查看市场在架信息
npx skills find planning-with-files

# 从仓库安装（命令转引自本专栏基线报告，目标路径为本机技能目录）
git clone https://github.com/OthmanAdi/planning-with-files ~/.claude/skills/planning-with-files

# 本机已装的话，直接确认在位
ls ~/.claude/skills/planning-with-files
```

装完无需任何配置。最快的验证方式：给 Claude Code 派一个五步以上的任务，观察它是否主动创建 task_plan.md。

## 八、推荐排行榜

**字帖榜**（第一件该抄谁）
1. planning-with-files —— 一份文件全包，薄、硬、能跑
2. skill-creator（官方）—— 第二课再读，学造件与打包
3. pdf（官方）—— 学渐进披露与脚本化的进阶样本

**优先抄写榜**（七个模式先抄哪个）
1. 模板焊死 —— 当天见效，格式漂移立刻消失
2. 反面清单 —— 半小时写完，纠偏收益最持久
3. 契约表格化 —— 让产出物结构稳定可验收

**避坑榜**（第一件别学谁）
1. 仓库级大件（gstack 类）—— 先学走再学跑仓库管理
2. 已退场整包（superpowers 类）—— 纪律值得学，结构别照抄
3. 人设单段件 —— 数量最庞大的一族，但一段提示词撑不起「工程」二字

## 结语

四个月前它以最高 Star 登顶，四个月后同类大多散包，它还在装机清单里——市场最终把票投给了最不像「产品」的那件：没有脚本、没有界面、没有任何会被平台升级折断的部件，只有一份把模型当读者的说明书。写你的第一个 Skill，先把这份说明书当字帖抄一遍，你学到的不是某个技巧，而是整门手艺的第一性原理：**SKILL.md 的读者是模型，不是人。**

## 参考来源

1. 本机实装技能 `~/.claude/skills/planning-with-files/`（SKILL.md 全文，含 reference.md / examples.md 外链结构）—— 本文逐段拆解的一手文本
2. [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files) — Skill 仓库出处，转引自本专栏基线报告
3. [本专栏基线报告：Claude Code Skills生态评测·第1轮（2026-05-16）](output/2026-05-16/skills-ecosystem-1600.md) — 17,700+ Star、40+ agent 兼容、4.85 综合评分的记录出处
4. [本专栏对账文：装机对账·5月榜单9月还剩谁（2026-09-13）](output/2026-09-13/skills-ecosystem-0117.md) — 唯一整包幸存结论与 4.60 复评出处
5. [本专栏方法论轮：从热门Skill提炼SKILL.md设计模式（2026-09-11）](output/2026-09-11/skills-ecosystem-r8-1904.md) — 官方系写法模式对照参照
6. [anthropics/skills](https://github.com/anthropics/skills) — 官方技能仓库（skill-creator、pdf 等对比样本出处）

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)