SKILL.md：把程序性记忆写进文件

同一个请求，每个 PR 会话都要重贴一遍：Black 88 字符、Ruff 自定义规则、公共 API 类型注解、Google 风格 docstring、Pytest。这是 L4 p.8 的动机场景。解法是一个文件夹。

动机与解剖：重贴五遍的规范，写一次

判断标准一句话：凡是按固定 spec 反复做的事，就该变成一组文件。技能包（skill package）就是这组文件的标准形状（L4 p.9；Anthropic 工程博客）：

python-review/
├── SKILL.md                       # 必需：YAML 元数据 + Markdown 正文
├── scripts/
│   └── run_checks.py              # 可选：可执行脚本
├── references/
│   └── docstring-style.md         # 可选：按需查阅的参考文档
└── assets/                        # 可选：模板等静态资源

只有 SKILL.md 是必需的，三个子目录都可选。SKILL.md 自身分两截：frontmatter 写元数据，字段是 name、description、when_to_use；正文写操作指引。元数据是索引条目，正文是操作手册，捆绑文件是工具与附录。

官方 PDF 技能是最佳示范：把 forms.md 从正文拆成独立文件，遇到表单任务才载入；脚本交给终端执行，只有输出回到上下文。所以「打包的上下文实际上无限」（L4 p.9）。

与 MCP 的关系是互补而非替代：MCP 扩展 agent 够得着的能力，技能沉淀把这些能力用对的方法。

Claude Code 文档和 agentskills.io 钉了两条硬约束：description 与 when_to_use 合计 1536 字符即被截断，索引条目必须短；SKILL.md 建议控制在 500 行内，连正文也未必全量进窗口。两条约束都指向渐进披露（Progressive Disclosure）。

四回合加载实录：代码永远不进上下文

L4 p.10-11 给出 agent Hermes 的做法：系统提示里放一个 <available_skills> 索引，按类目分组、只收录名称与描述，全库合计约 3k token。配套一条硬规则：任务与某技能「匹配或部分相关」就 MUST 调 skill_view(name)。三层信息量是一个漏斗：

落到 L4 p.11 的一次真实 PR 审查，就是四回合：第 0、1、3 回合对应漏斗的三层，第 2 回合的脚本执行不在这三层里。

预算有具体数字。Claude Code 文档写的是：auto-compaction 之后，每技能保留最近一次调用的前 5,000 tokens，全部技能合计 25,000 tokens。索引常驻是廉价的，正文与参考有配额。

实证：平均 33.9% → 50.5%，但有 13 个反例

SkillsBench（arXiv:2602.12670；L4 p.12-13）在 87 个真实任务、8 个领域、18 种模型 - harness 配置上检验：配上策展技能（curated skills）后，平均通过率从 33.9% 提到 50.5%。但拆开看，增益高度依赖聚焦：

反例的机制：技能可能挤掉模型更好的默认策略。预先注入的操作指引，会让 agent 放弃自己原本更擅长的做法。

所以策展要做的就是少写、写短、只写模型默认做不好的那部分。

三个来源与维护环：技能是运营出来的

L4 p.14 把技能来源归为三个：

• bundled。harness 自带。
• 人写或安装。.agents/skills/ 随仓库入库，经 registry 分发。
• agent 自建。Hermes 用 skill_manage 建改删；OpenHands 的 /skill-creator 从刚完成的工作流生成一份草稿，人审查后才发布。

OpenHands 的建议反直觉但省力：别对着空白文件从零写，在刚跑完一个你想复用的工作流时立刻创建技能，再实测几次。

生态侧已经是一套开放标准：agentskills.io 上，Cursor、Copilot、Codex、Gemini CLI 等数十家支持。Anthropic 官方示例库 anthropics/skills 提供 docx/pdf/pptx/xlsx 四件套起步。

写出来只是开始。OpenHands 对来自仓库的每个 PR 跑 python-review 类技能，L4 p.15 的维护环是：跑技能 → 记日志 → 打分 → 找反复出现的失败 → 补 SKILL.md。

打分交给模型裁判：让模型统计人类采纳了多少条建议、归纳复发原因。实测约 15% 的建议无视仓库规范，约 10% 放过了有致命缺陷的 PR。

再回写两条纪律。发现致命问题必须 request changes，发建议前先对照仓库检查。技能文件随代码入库，同走日志、修复与版本流程。

与本讲的连接

本讲把记忆分成情节、语义、程序三层。技能文件是程序性记忆（Procedural Memory）的最低成本形态：不训权重、不占常驻窗口，把怎么做外置成可版本化的文件资产。

它与 2a 严丝合缝：渐进披露天然缓存友好，索引属于稳定前缀，正文按需进入变化层。聚焦时平均通过率多 16.6 个百分点（=50.5−33.9），堆积时可能倒贴。

加技能先加最痛的那一个，写短一点。