我给 agent 写了大半年文档才反应过来：读它的早就不是人了
哈喽，我是飞飞。
昨天刷到 Simon Willison 给他的 shot-scraper 加了个录屏命令。本来是个不起眼的小更新，我却盯着他配的一句话看了半天。
他说，他特别喜欢这个做法：把一个命令的 –help 输出写得足够细，细到一个 coding agent 读完就能直接拿去用。用他的原话讲，感觉就像顺手在里面塞了个 SKILL.md。
我上一篇刚聊过怎么把一个 skill 写得不飘。这篇不是那篇的续集。Simon 这句话把我拽到了更上面一层：我突然反应过来，我写了大半年的那些东西，读它的早就不是人了。
先看这个小更新
先说清楚 Simon 干了啥，免得云里雾里。
shot-scraper 是他写的一个命令行小工具，本来是给网页拍截图用的。这次更新加了个 shot-scraper video，你拿一个 storyboard 文件把操作步骤一条条写下来，点哪、填什么、停几秒，它就靠 Playwright 把整个浏览器操作过程录成视频。他配的演示，是录了一段在 Datasette 里粘一段 CSV 进去自动建表的过程。
工具本身很小。诚实说一句，shot-scraper 我没上手用过，所以这篇不谈工具本身。真正戳到我的，是他那句关于 –help 的话。
一个工具作者，在写命令行帮助文档的时候，脑子里装的读者已经从敲命令的人，换成了一个会来读这段帮助、然后自己照着调用的 agent。他甚至把 –help 直接类比成 SKILL.md。我天天写 SKILL.md，这个类比一下就把我点着了。
文档没人读是老毛病
先认个老现实。
写文档，几十年来都是程序员最不爱干的活。README 写了没人看，–help 大家宁愿去 Google，代码注释更新不及时还会骗人。你辛辛苦苦把用法写清楚，多数时候是自我感动，真正的用户扫两眼就关了，遇到问题直接去翻 issue 或者问同事。
这一半我先认下来。文档没成就感、没人读，是真的。
但现在情况变了。文档多了一个读者。而且这个读者，跟人完全是两个物种。它会把你写的每一个字都读完，一字不落。它不跳读，也不脑补。它把你的文档当成指令，读完就照着执行。
写给这种读者的文档，跟写给人的文档，根本不是一回事。
我的触发器写给 agent
这事我其实干了很久，只是从没意识到。
我这个号背后挂着十几个 skill，选题、调研、写稿、润色、配图、分发，串成一条流水线天天跑。这一整套东西全长在 Claude Code 读 skill、认 frontmatter 的脾气上，是我每天干活的地基。每个 skill 顶上都有一行 description。我写这行字的时候，脑子里装的根本不是功能说明，就一个问题：agent 什么时候该来调我。
就说我那个拉 AI 资讯的 aihot skill，还有帮我选题的 content-scout，它俩的 description 我是当开关写的。我甚至专门在里面写了一句「不要 undertrigger」，意思是别在该调用的时候偷懒不调。这行字不是写给我看的，是写给 agent 看的判断依据。这跟 Simon 说的把 –help 写到 agent 能直接用，说的是同一件事。
还有一层区别我也亲手踩过。有些 skill 是让 agent 自己判断该不该触发的，description 就得写成一个精准的触发条件，写宽了它到处乱插手，写窄了它该干活时又装死。有些 skill 得反过来，比如我那个发公众号的，我把它默认状态写成不触发，触发条件卡到必须出现「发公众号」「推送微信」这类明确说法才动。就这一句边界，拦住的是它某天自作主张，把一篇还没配图、没过审的稿子直接推出去。这两种脾气完全相反的接口，我都得亲手写清楚，agent 才知道自己的手该伸到哪儿为止。
接口写模糊就被乱发挥
写给 agent 的东西，模糊一点就出事，这个我有血泪。
我那个配图的 content-artist skill，早期接口就没写死。我本来的意思，是让它只在正文里标个「截图一」「截图二」的占位，真正传图床那步交给后面另一个环节去干。结果我没把这条边界抠死，agent 读到那段含糊的描述就自己发挥了：它把图床那一长串 CDN 链接当普通文本塞进了正文，有时候干脆漏图，该配图的位置就那么空着。我是稿子快发出去、扫最后一眼时才逮到那串裸链接，当场有点哭笑不得。
我后来想明白了。一个人读到写得含糊的文档，会停下来问你一句，或者凭常识猜个八九不离十。agent 不会。它读到模糊的地方，会自己补一个它认为合理的动作，然后一路跑下去，翻了车你都不一定当场发现。
给人的文档，模糊是体验差。给 agent 的接口，模糊就是个漏洞。我把那条规则改成一句不留余地的死命令，只许写占位、绝不许自己上传或粘链接，它才彻底老实。
文档的读者换人了
把这几件事串起来，我看到的是一个正在发生的变化。
软件文档几十年都是写给人的。人读文档的方式是扫一眼、抓重点、跑起来再说，读者是懒的、跳跃的、会自己脑补的。现在冒出来的这个 agent 读者，读法完全颠倒：它全文照读、逐字当真、读完就执行，还特别较真。
于是那些我们一直没太当回事的东西，–help、README、报错信息、API 文档，正在悄悄变成写给 agent 的接口。Simon 那句 –help 就像塞了个 SKILL.md，点破的就是这层。你的工具好不好用，正在多出一个新标准：一个 agent 读完你的文档，能不能不问人就直接上手。
这事想通了还挺带感的。以前写文档像往井里扔石头，听不见响。现在至少有一个读者，是真的会把你写的每个字都当回事的。
今天就能改一个动作
不灌大道理，给一个今天就能试的动作。
挑你最常用的那个脚本、那个内部工具、那个 CLI，把它的 –help 或者 README 拉出来读一遍。读的时候换一个身份：假装你是个刚接手的 agent，只有这段文字，没别的上下文。然后问自己三个问题：什么时候该用它、参数的边界在哪、干完了什么样算成功。有一个答不上来，agent 读到那儿就会开始飘。
答不上来的那几处，就是你接下来要补的地方。补的时候别写给人看，写给那个会照着做的读者看。
说到底，文档真正的读者，已经不在那个扫一眼就顺手关掉的人，在那个会一字一句读完、还认认真真照着做的 agent。这个转变才刚开头，我也还在一边写一边改我那十几个 skill 的接口。每被 agent 将一军一次，就回头把那行字抠得更死一点，这活估计短时间内停不下来。
轮到你了：你写过最后悔「没给 agent 交代清楚」的一段文档或接口是哪个？agent 照着你写的东西，干过什么让你哭笑不得的事？评论区说说。