9 月 4 日发布 agentsmd-skill v1.0.0 那天，我有一种「完成了」的错觉。CHANGELOG 写好了，README 排干净了，三条核心机制——准入门槛、合并闸、120 行上限——在文档里自洽得挑不出毛病。我当时确信，接下来要做的只是等用户上门。

两个月后版本号走到 v1.5.2，CHANGELOG 里躺了七个版本。回头逐条对，每个版本都不是「新功能」，而是一次被打脸的记录：我在发布那天相信的四个假设，被真实使用逐个证伪。把这几记耳光复盘出来，比讲设计本身诚实得多——设计哲学在上一篇里说过了。

假设一：教训是会话里唯一值得留下的东西

v1.0.0 的世界观很简单：会话里产生教训，教训固化成规则，规则写进 AGENTS.md，一条单行道。头两周用下来，单行道开始堵车——我在会话里想「留下来」的东西，远不止教训。

一份随手生成的对比报告躺在目录顶层，下周还要用；个人 agent 的记忆条目和项目脱节了，该跟着项目走；TODO 和 CHANGELOG 停在上个版本，没人更新。这些东西和「教训」一样，都在问同一个问题：我该去哪，我该活多久？ 而它们各自的寿命完全不同——规则要活到项目死掉，报告活到下次对比，记忆条目活到被更正。

v1.1.0 于是加了两个条件步骤：agent 有记忆机制，就按宿主格式沉淀项目记忆，先查重再写入；项目有进度文件，就同步更新。散落的产出文档则给了归集流程——先查引用再提方案，批准后才移动，移动后修断链。

这一记耳光教会我的事，比加几个步骤重要：固化知识的本质不是「写进文件」，是给每条信息找到正确的寿命和位置。 AGENTS.md 只是众多容器里寿命最长的那一个。

假设二：AI 生成的命令可以信任

v1.0.0 还有一个没写进文档的假设：为新项目生成 AGENTS.md 时，从 README 和配置文件摘出来的构建命令是可信的。毕竟它们「有出处」。

直到某个新项目上，生成文件里的第一条命令就是一个死命令。README 里的测试脚本早在两个版本前就改名了，skill 不知道，照抄，写进 AGENTS.md，还加了个体面的对勾。下个会话的 agent 读到它，不会怀疑——这个文件的定位就是「可信上下文」——照着执行，第一脚踩空，然后花十分钟排查一个本不该存在的错误。

这件事的恶劣程度超过一般的功能缺陷：十条缺规则，agent 会自己摸索；一条假规则，agent 会信以为真地执行。对一份专门写给 AI 看的文件来说，假命令是毒药而不是空缺。

v1.2.0 的回应是命令可执行验证：写入的每条命令逐条实跑；部署、迁移这类不便实跑的，与 package.json scripts、Makefile、CI 配置逐一核对，对不上不写入。同版本还引入 agents.md 官方示例作成稿锚点，让生成的文件有颗粒度参照。

现在回头看，「生成」和「可执行」之间隔着一整个运行时——任何没被运行过的命令，都只是看起来像命令。

假设三：来用它的都是程序员

这个假设藏得最深，因为它从来没被我当成假设——「项目规范」这个词在我的脑子里自动等同于「代码项目规范」。120 行上限、命令验证、章节语义，全部默认读者手里有一个 package.json。

然后有人把它装进了一个纯文档协作目录。没有源码，没有构建配置，首版扫描无从下手；「Build & Test Commands」章节对报告库毫无意义，它真正要管的是数据口径、命名归档、交付复核。整套流程在那个目录上静默失灵——最糟的一种失败，不报错，只是没用。

v1.5.0 的场景适配由此而来：流程开始前先判定 coding 还是 work 场景，骨架不变，适配三处——coding 核命令，work 核文中引用路径真实存在；归集也分家，文档归 docs/，CSV、JSON 这类机器可读数据归 data/，数据表不再被当文档塞错地方。

这一记耳光最疼，因为它戳破的不是功能缺失，是我对「用户」的想象。工具一旦发布，就会立刻离开你为它设计的语境——抽象层级必须跟着使用者走，而不是跟着设计者走。

假设四：发出去，自然有人用

功能稳定后我默认剩下的事是等。事实上 skills.sh 确实早早自动收录了仓库，第一批安装就是这么来的——但「被收录」和「被找到」之间隔着渠道自己的语法。

v1.5.1 主动完成了 ClawHub 与 LobeHub Skills Marketplace 的上架，同时把收到的最高频提问写回 README：「Hermes、OpenClaw 这类有记忆的个人 agent 能不能用？」——能，纯 Markdown 无依赖，有记忆机制就按宿主格式沉淀。答案一直成立，只是没人问就没写。

v1.5.2 处理语言问题：Skills Hub 的索引与审核以英文为主，正文和 README 全部切英文默认，中文译文退到 docs/zh-CN/。但有个东西不能跟着一刀切——frontmatter 的 description 做成双语：英文主句供索引，中文触发短语保留，中文会话里说「总结经验写进 AGENTS.md」照样触发。

分发不是上传动作，是逐个渠道学习它的语法，然后在不丢核心的前提下迁就。

发布之后的事，是换掉自己的假设

四个假设，四个版本，一条规律：每一次有价值的迭代，都不是「想到了」，而是「被证明了想错了」。 命令跑不通才有了实跑验证，文档目录失灵才有了场景适配——没有一版来自闭门推演。

所以现在我对「发布」的理解变了。发布那天交付的不是成品，是一组待检验的假设清单；之后的每个 issue、每个反直觉的使用场景，都是清单在逐项兑现。CHANGELOG 里的七个版本，与其说是功能史，不如说是七次认错记录。

给同样在维护小工具的人一个可操作的建议：发布时把自己确信的东西写成一张假设清单——「用户都会写代码」「生成的命令可信」「发出去自然有人用」——然后等着它们挨个被打脸。被打脸的速度，就是你迭代的速度。

agentsmd 的仓库在 GitHub，npx skills add kelegele/agentsmd-skill 一句话安装；0 依赖 skill 的写法心得在这篇。