napkin v6.0 SKILL.md深度解析:为什么它是runbook而不是流水账
napkin v6.0 SKILL.md深度解析:为什么它是runbook而不是流水账
📌 napkin 是一个为 Claude Code 打造的 skill,它让 AI Agent 拥有按仓库隔离的持久记忆:Agent 会在仓库里维护一份 .claude/napkin.md,持续记录自己踩过的坑和你纠正过的习惯。而 v6.0 版本 SKILL.md 最核心的设计决策只有一个——把这份文件当成**持续精选的 runbook(运行手册)**来维护,而不是按时间追加的流水账。本文带你逐节拆解这份 SKILL.md,看它如何用几行规则逼出 Agent 的"复利式成长"。
一、先搞清楚:napkin 解决什么问题
用过 AI 编程助手的朋友都有同款痛点:同一个错误纠正了三次,第四次它又犯。因为 Agent 的上下文是"一次性"的,会话一结束,教训就清零了。
napkin 的答案朴素得惊人,官方 README.md 里一句话概括:
Baby continual learning in a markdown file.(在一个 markdown 文件里的婴儿级持续学习。)
它的工作循环就三步(见 README.md):
- 会话开始:Agent 先读当前仓库的
.claude/napkin.md,没有就创建一份; - 干活过程中:随时把错误、纠正、偏好、有效做法写进去,而不是等到会话结束;
- 跨会话复利:第 1 次会话一切正常,到第 3 次 Agent 开始抢在你之前发现问题,第 5 次它"已经是另一个工具了"。
每个仓库一份 napkin,你既可以把它提交进仓库(团队所有贡献者的 Agent 共享同一份经验),也可以加进 .gitignore 保持私人化。
二、v6.0 SKILL.md 逐节拆解
翻开 SKILL.md,文件头部的 frontmatter 就亮出了身份(见 SKILL.md):
version: 6.0.0,发布于 2026-02-21- description 第一句就是定性:"a continuously curated runbook (not a session log)"(持续精选的 runbook,而非会话日志)
- "Activates EVERY session"——无需任何触发词,每个会话无条件激活
2.1 会话开始:先读,顺手做"策展"
v6.0 最有意思的设计在 SKILL.md 的 Session Start: Read And Curate 一节。它要求 Agent 每次会话第一件事就是读完 napkin 并"静默应用"——注意细节:不许宣布自己读了,直接把学到的东西用上。
更关键的是"每次读,必须立刻做一次策展":
| 策展动作 | 目的 |
|---|---|
| 按重要性重新排序(最重要的在前) | 保证 Agent 注意力永远花在高价值条目上 |
| 合并重复、删除过期/低信号笔记 | 防止文件膨胀成垃圾堆 |
| 只保留反复出现的高频指导 | 一次性杂音直接过滤 |
| 每条必须带显式的 "Do instead" 动作 | 把"发生了什么"翻译成"下次怎么做" |
| 每个分类最多保留 10 条 | 硬性容量上限,倒逼取舍 |
如果 napkin 还不存在,SKILL.md 直接给了一份初始模板(见 SKILL.md),内置四个分类:Execution & Validation(最高优先级)、Shell & Command Reliability、Domain Behavior Guardrails、User Directives。模板要求 Agent 可以根据仓库领域调整分类内容,但必须保持分类结构和优先级顺序,并且明确禁止"原始日记式条目"("Do not use raw journal-style entries")。
2.2 写入标准:什么能进,什么不能进
Continuous Runbook Updates 一节(SKILL.md)给出了非常明确的收录标准:
✅ 值得写入:本仓库/工具链里高频出现的坑、反复奏效的非常规技巧、影响重复行为的用户指令
❌ 明确拒收:一次性的时间线备注、没有可复用动作的冗长复盘、没有 "Do instead" 的纯错误日志
条目格式也定死了三要素(见 SKILL.md):
- 加入日期
[YYYY-MM-DD] - 简短的规则标题
- 显式的
Do instead:行,措辞简洁、动作导向
SKILL.md 末尾给了一个标准范例(SKILL.md):
**[2026-02-21]rgfails on giant expanded path lists**Do instead: runrgon directory roots or iterate files viawhile IFS= read -r.
注意这条记录的结构:错误现象 + 日期 + 可复制粘贴的正确做法。三个月后回看,它依然能直接指导执行。
2.3 分类与优先级策略:少而精是铁律
Category And Priority Policy(SKILL.md)是全文的"宪法"级条款:
- 按分类组织,每个分类内部按重要性降序排列
- 每次编辑都要重新评估条目的分类归属和优先级
- 单分类硬上限 10 条,超了就把优先级最低的删掉
- 原话:"Prefer fewer high-signal items over broad coverage"——宁可少而高信号,不要广而稀释
三、为什么说它是 runbook 而不是流水账
这是理解 v6.0 的关键。两种文件表面都是 markdown,本质完全不同:
| 维度 | 流水账(session log) | napkin 的 runbook |
|---|---|---|
| 写入方式 | 按时间顺序追加,只进不出 | 边干活边更新,且每次读取都重新策展 |
| 内容性质 | "3 月 2 日我错了"(历史记录) | "遇到 X 就执行 Y"(未来动作指令) |
| 时间维度 | 越长越有价值(历史全貌) | 长度无关,只认复用价值 |
| 三个月后 | 越读越累的信号垃圾 | 10 条以内、每条可直接执行 |
| Agent 使用方式 | 需要"考古"和提炼 | 直接照做 |
SKILL.md 在 Practical Rule 一节(SKILL.md)把这件事说透了:
Think of napkin as a live knowledge base for future execution speed and reliability, not a history file. (把 napkin 当作面向未来执行速度与可靠性的活知识库,而不是历史档案。)
这就是"runbook 而不是流水账"的完整含义:流水账的价值在过去,runbook 的价值在未来的每一次执行。"Do instead" 强制格式 + 10 条硬上限 + 每次读取即策展,三条机制共同保证文件永远处于"可被立即执行"的状态。
四、动手安装:一条命令接入
安装非常简单,把仓库克隆到 Claude Code 的 skills 目录即可(Codex 用户换成 ~/.codex/skills/napkin,原理相同):
git clone https://gitcode.com/gh_mirrors/napkin2/napkin ~/.claude/skills/napkin
装完就生效——skill 每个会话无条件激活,不需要任何额外配置。官方文件结构一览:
五、小结
napkin v6.0 用一份不到 110 行的 SKILL.md,给 Agent 装上了一套自管理的记忆系统。它最值得借鉴的地方不在于"记什么",而在于"怎么管":
- 定性先行:开篇就定义这是 runbook 不是日志,一切规则围绕"未来可执行"展开;
- 写入有门槛:没有 "Do instead" 的纯错误记录直接拒收;
- 容量有上限:每分类 10 条硬顶,超了必须淘汰;
- 读取即维护:每次会话开始顺带重新排序、合并、剪枝。
如果你的 Agent 也在重复犯同样的错,这份"婴儿级持续学习"的 markdown 方案,可能就是成本最低的答案。