把经验写进仓库

最近读 OpenAI 那篇讲 Skills 和 Agents SDK 的文章，脑子里一直在转一个很小的问题。

我们到底是在使用 AI，还是在把自己的工作方式，一点点整理成 AI 也能接住的东西。

以前总觉得，所谓“AI 提效”，核心是模型越来越强。它会写代码，会解释报错，会总结文档，也能把一段模糊的需求翻译成还算可用的实现。可真把它放进日常工程里，事情很快又会变得具体起来。

你会发现，问题常常不是它不够聪明，而是它不知道你们平时到底怎么做事。

同样是改完代码之后的“检查一下”，有人会顺手把 format、lint、test 全跑完，有人只会跑当前模块，有人记得补 typecheck，有人则默认 CI 会兜底。
同样是准备提 PR，有人会把改动背景、影响范围和验证方式写得很清楚，有人只留下一个简短标题，像往河里扔下一颗石头，剩下的涟漪全交给 reviewer 自己理解。

这些差别，看起来像是个人习惯。可如果往下想一层，它其实是一种没有被正式写下来的经验。

而 Skills 有意思的地方就在这里。

它不是让模型再多会一点东西，也不是再给 prompt 换一个更精致的名字。它更像是在说：如果一件事会一遍遍发生，如果它背后已经有了相对稳定的做法，那为什么不把它认真写下来，写进仓库，写成一种能被调用的能力。

这件事让我有点触动。因为它不是在追求一种更炫的智能感，反而是在做一件很朴素的事：把原本只存在于人脑子里的工作习惯，慢慢整理成系统的一部分。

Skill 像什么

如果只从表面看，skill 很容易被理解成“提示词模板”。

但我越来越觉得，它更像是一个很小的工作单元。
它知道自己该在什么时候出现，知道自己要完成什么，也知道哪些地方该交给模型判断，哪些地方该交给脚本执行。

OpenAI 的文章里提到，一个 skill 通常会有自己的说明文件，也可能带着脚本、参考资料，甚至一些辅助资源。换句话说，它并不是一句轻飘飘的“帮我做这个”，而是一套被稍微整理过的经验。

我很喜欢这种感觉。

因为很多时候，团队里的知识并不是没有，只是它们以一种很松散的形式存在着。它可能藏在某个资深工程师的习惯里，藏在某次 code review 的评论里，藏在一个只被提过一次的内部约定里。你问起来，大家都知道一点；真要写下来，又总觉得“这种事不是理所当然的吗”。

可一旦要交给 Agent，很多“理所当然”就突然变得不再理所当然了。

它不会天然知道，改了这几个目录意味着什么。
它不会天然知道，某一类改动是必须完整验证的，另一类改动却只需要最小检查。
它也不会知道，你们习惯怎样描述一次改动，怎样把上下文交代给下一个接手的人。

于是 skill 的意义开始变得清楚起来。
它不是替代经验，而是在保存经验。
不是制造新的流程，而是把原来那些靠默契维持的东西，慢慢落成可以复用的形状。

真正难的，不是写“做什么”，而是写“什么时候做”

我觉得 OpenAI 那篇文章里最值得反复想的一点，是它对 skill description 的强调。

一个 skill 是否真的有用，关键不是写得多完整，而是写得够不够准。
尤其是那个“什么时候该触发”的边界。

这件事听起来很细，可其实很像平时和人协作。
真正让一段协作顺畅起来的，从来不只是步骤本身，而是时机。

如果你只说“运行验证流程”，这当然没错，但几乎没什么帮助。
因为接下来最重要的问题都还没回答：

什么样的改动算需要验证？
只是改了文档呢？
只是重命名文件呢？
如果动到了测试或者构建链路，是不是就应该升级为完整检查？
这个动作是建议性的，还是必须性的？

当这些边界没被说清楚时，一个 skill 就很容易变得像一件摆设。它存在，但不稳定；偶尔会被调用，偶尔又会被忽略。最后的问题不在模型，而在于这个能力没有真正定义好自己出现的时刻。

我会觉得，写 skill 有点像在写一种很轻的制度。
制度不是靠语气强硬，而是靠边界清楚。
什么时候该发生，什么时候不该发生，什么属于例外，什么必须执行，这些东西一旦明确了，后面的流程反而会变简单。

仓库里其实一直缺一种“写给 Agent 的文档”

文章里还提到了 AGENTS.md。这个设定我也很喜欢。

它有一点像过去我们写给新同事的 onboarding 文档，只不过这次读者不是人，而是 Agent。

仓库有自己的脾气。
目录结构是怎么分的，哪里是核心路径，哪些约定看起来不显眼却不能碰，某些模块的测试为什么要这么跑，某些 API 的行为到底应该信源码还是信文档，这些都是仓库内部的语言。

平时这些东西靠人来理解，问题也不大。人会猜，会追问，会顺着上下文补全很多隐含信息。
但 Agent 不太一样。它当然会推理，可它最怕的是那些所有人都默认存在、却没有人认真写下来的东西。

所以 AGENTS.md 给我的感觉，不是又多了一份文档，而是终于出现了一种明确的载体，去承接那些“本来应该早就写清楚”的仓库共识。

如果说 AGENTS.md 更像总说明，那 skill 就更像一个个局部工作流。
前者回答“这里是一个什么样的地方”，后者回答“在这里，某件事该怎么做”。

再往下，还有 GitHub Actions 这种更确定的自动化兜底。
这样一层层看下来，会觉得这个结构其实很顺。

人负责形成经验。
文档负责表达经验。
skill 负责调用经验。
脚本和 CI 负责执行经验。

这和我过去想象的“AI 改变工程”很不一样。它没有特别戏剧化，反而很像软件工程一直以来最熟悉的路径：把不稳定的手工操作，慢慢整理成稳定的系统行为。

模型不需要什么都做

这篇文章里还有一个我很认同的判断：模型不应该负责一切。

这件事说出来很简单，但真正做的时候，太容易贪心了。
因为模型看起来什么都能处理，于是我们会不自觉地把理解、判断、执行、格式化输出，全部揉成一团交给它。

结果通常不会太好。

需要理解上下文、做比较、做总结、做判断的事，模型很擅长。
但需要按固定顺序执行命令、收集状态、输出可预期结果的事，本质上还是脚本更适合。

这个边界一旦想清楚，很多设计问题就会顺下来。

比如判断一个改动是不是行为变更，这种事要靠模型。它需要读 diff，理解意图，也理解周边上下文。
但“先跑哪些命令、失败了该怎么汇总、从哪里收集 git 状态和分支信息”，这些就该尽量交给脚本。

我一直觉得，好的系统不是把能力堆在一个点上，而是把职责分开。
模型负责那些本来就不确定的部分。
脚本负责那些应该尽量确定的部分。

Skill 之所以让我觉得它更接近“工程”，也在这里。它没有把模型想象成一个全能的主体，而是愿意承认：真正稳定的工作流，往往来自不同能力的合作，而不是单一能力的膨胀。

说到底，Skills 在整理的是“隐性经验”

我后来越想越觉得，Skills 最值得珍惜的地方，可能不是它能提升多少效率，而是它逼着团队去面对一件平时不太愿意面对的事：我们的很多工作，其实建立在隐性经验上。

这些经验平时并不显得稀缺。
因为总有人知道。
一个团队里，总会有一些人对仓库很熟，对流程很熟，对各种“虽然没写，但大家都这么做”的东西很熟。于是问题看起来总能被解决，流程看起来总能被跑通。

可一旦团队变大，项目变复杂，或者引入 Agent，这些隐性的部分就会立刻暴露出来。

因为 AI 不会自动继承团队默契。
它也不会天然理解某些“本来不用说”的规则。

于是很多以前能被熟人网络悄悄消化掉的问题，现在都必须被明说了：

什么是必须做的？
什么只是建议？
哪些步骤必须自动化？
哪些判断仍然需要人来做？
哪些知识应该写进仓库，而不是留在聊天记录里？

这让我觉得，Skills 表面上是在帮助 Agent，实际上也在帮助团队重新认识自己。
你们到底是怎样工作的。
哪些经验是可迁移的。
哪些流程值得固化。
哪些依赖于个人记忆的地方，早就该被替换掉了。

从这个角度看，它不是一个单纯的新功能，而像一次很安静的整理。

我会从什么地方开始

如果真要在一个仓库里慢慢把 skill 建起来，我大概不会一上来就做一个很大的系统。

我更愿意从那些已经足够重复、足够明确、而且失败成本又不低的事情开始。

比如验证流程。
这几乎是最自然的一类。改动之后该跑什么、顺序是什么、哪些情况需要附加检查、失败时怎么把结果说清楚，这些都很适合被整理成 skill。它高频、重复，而且一旦依赖记忆，就特别容易漏。

再比如 PR 的整理工作。
标题怎么起，改动怎么概括，影响范围怎么交代，验证方式怎么写得让 reviewer 不费力。这种事情本身不算难，但很消耗注意力。一个好的 draft 往往就能省掉很多来回解释。

还有文档核对。
OpenAI 在文章里提到，涉及平台或 API 行为时，他们会让 Agent 去查当前文档，而不是凭记忆回答。这个原则我很喜欢。因为变化快的东西最怕“我记得好像是这样”。把“先查文档再回答”变成一种默认动作，本质上是在给系统加一个很必要的约束。

再往后，可能是发版前检查。
这种流程不一定每天发生，但一旦出错，往往会让人很后悔。版本号、changelog、示例是否可运行、release note 草稿、breaking changes 的确认，这些都很适合被慢慢沉淀下来。

它们有一个共同点：都不是创造性的工作，而是重复性的工作。
也正因为如此，它们才更值得被写进仓库。

我为什么会对这件事有一点点乐观

这几年关于 AI 的讨论很多，热闹也很多。
可越往后，我反而越容易被一些安静的东西打动。不是模型又刷新了哪个 benchmark，不是 Agent 又完成了多复杂的任务，而是像 Skills 这种，看起来没有那么耀眼，却很接近真实工作现场的设计。

它让我觉得，AI 真正进入工程，不一定是靠一次 dramatic 的替代，而更可能是靠这种缓慢的渗透：先接住一个小流程，再接住一种工作习惯，再把一种原本只存在于经验里的做法，慢慢变成仓库的一部分。

这件事的迷人之处在于，它不是在制造新的神话，而是在保存那些原本就有价值的东西。

我们一直说，软件工程是在把手工经验系统化。
某种程度上，Skills 只是把这句话继续往前推了一步。

以前我们把经验写成文档，写成脚本，写成 CI。
现在，我们开始尝试把经验写成 Agent 也能理解和使用的能力。

我挺喜欢这种变化。

因为它让我第一次觉得，Agent 不是突然闯进工程体系里的一个外来者。
它更像一个新的参与者。
而一个新的参与者，最重要的不是“它能做多少事”，而是“我们愿不愿意认真把自己的工作方式告诉它”。

说到底，skill 不是在教模型怎么工作。
它是在逼我们先想清楚，自己到底是怎么工作的。