napkin v6.0 SKILL.md深度解析:为什么它是runbook而不是流水账

原创2026-11-07 11:37:461,964 阅读

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):

  1. 会话开始:Agent 先读当前仓库的 .claude/napkin.md,没有就创建一份;
  2. 干活过程中:随时把错误、纠正、偏好、有效做法写进去,而不是等到会话结束;
  3. 跨会话复利:第 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] rg fails on giant expanded path lists** Do instead: run rgon 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 装上了一套自管理的记忆系统。它最值得借鉴的地方不在于"记什么",而在于"怎么管":

  1. 定性先行:开篇就定义这是 runbook 不是日志,一切规则围绕"未来可执行"展开;
  2. 写入有门槛:没有 "Do instead" 的纯错误记录直接拒收;
  3. 容量有上限:每分类 10 条硬顶,超了必须淘汰;
  4. 读取即维护:每次会话开始顺带重新排序、合并、剪枝。

如果你的 Agent 也在重复犯同样的错,这份"婴儿级持续学习"的 markdown 方案,可能就是成本最低的答案。

登录后查看全文
napkin