【学习笔记】用 AI agent 写了 22 个 skill，总结出这几条心得

上一篇《公众号排版太烦？这个 AI skill 帮你摆平》我讲了怎么把 xiaohu-wechat-format 这个排版 skill 接进自己的流水线，还顺手打了几层补丁让它更好用。文末留了个钩子：这些 skill 到底怎么写、别人的 skill 又怎么接进来、怎么改到顺手？

这篇就来接上。我自己攒了一套中文内容生产工具集，陆陆续续写到了 22 个 Agent Skill——录音转文章、播客切高光、视频渲染、多平台发布，全靠 skill 串起来。经常有人问我这些 skill 是怎么写出来的。

说实话，单品的技巧没那么神秘，frontmatter（skill 文件开头的元数据声明）怎么填、description（描述字段，告诉 AI 这个 skill 是干嘛的、什么时候用）怎么写、正文怎么分层，这些都是网上一搜就有的规矩。真正让我这 22 个 skill 能用、好用、越来越顺手的，是我这半年多攒下来的几个习惯。

这一篇我就把这些习惯讲透。文章末尾我会把那些”写 skill 的技术规矩”快速过一遍，作为补充的注意点——但那不是重点，重点是前面这几条。

一、让 AI 代劳，自己只做判断

在讲具体习惯之前，我得先把一个至关重要的前提摆出来，否则下面几条你会觉得累、做不到。这个前提是：看 skill、研究 skill、写 skill，全部交给 AI 做。你只负责两件事——把需求和问题问清楚，对 AI 产出的东西拍板。

很多人写 skill 是反过来的：自己一个个翻别人代码、自己琢磨结构、自己动手写。我试过，太累了，效率低得让人想放弃。你这哪是在用 AI，分明是在给 AI 打下手。正确的方式是把自己从”执行者”换成”指挥官”——眼睛盯着方向，脏活累活全交出去。AI 负责干活，你负责掌舵。因为”这个设计适不适合我""这个功能要不要保留”——这些只有你清楚，AI 不知道你的工作流。下面这几条心得，全都建立在这个前提上。

二、多看：把别人的好 skill 当免费教材

写 skill 最忌闭门造车。你的需求，大概率别人早就解过，而且解得比你漂亮。

我自己的”渐进式披露""SKILL.md 当目录”这些手感，说白了不是自己悟出来的，是看官方 anthropics/skills 仓库里的 pptx、docx skill 看出来的。你看它们怎么写：正文短，细节全推到 references（参考资料目录）和 scripts（脚本目录）里，SKILL.md（一个 skill 的主文件、入口）本身就像个目录。看几遍这个结构，你的手感自然就有了。

这些好 skill 就是免费教材，而且教材质量比绝大多数教程都高。去哪找？几个方向：

官方仓库首当其冲，anthropics/skills 里的文档处理 skill 是教科书级别的范本；社区里 star 多、被人反复 fork 的 skill 也是富矿，比如那些 awesome-claude-skills 类的合集；本机装的插件 skill 更别忽略——我写这篇文章时翻了自己机器上 skill-creator、writing-skills、diagnosing-skills 这几份官方创作指南，里面的 description 写法争议、测试方法论，都是一手干货，比我之前看的二手转述清楚太多。

一个提醒：别只看二手中文教程。教程常常为了”好懂”把原意转述走样，等你照着做发现不对，回头才发现源头根本不是那个意思。能啃一手 skill 代码就啃一手，看不懂的地方让 AI 给你逐段解释，也比看三手转述强。

看完之后呢？直接照抄不可取，这就是下一条要讲的。

三、先研究再复刻：别急着抄

看到一个牛的 skill，第一反应往往是”拿过来直接接进去”。我劝你忍住。

直接接入的代价我交过学费。你不理解它为什么这么写，环境一变就抓瞎，而且很容易把它的风格和你的需求拧成四不像——人家的 skill 是在他的场景里磨出来的，你硬搬过来，水土不服是常态。

我的做法是先把那个 skill 丢给 AI，让它研究透，给我一份”拆解报告”。具体我会让 AI 总结这几样：这个 skill 的结构是怎么分的，SKILL.md 正文和 references/scripts 各承担什么；frontmatter 的 name（skill 的名字字段）和 description 怎么写的、为什么这么写；它用 references 还是 scripts 承载细节，哪几处设计是真功夫、哪几处是可有可无的花活。

拿我自己举个例子。我有个负责视频渲染的 skill，里面有个兜底脚本，专门在 agent 生成 HTML 之后，幂等地强制补上 agent 最常遗漏的结构性规则。这个设计不是我凭空想出来的——是看到别的成熟 skill 把”agent 容易翻车的确定性逻辑”抽成脚本兜底，让 AI 帮我拆解明白这套思路之后，我才把它复刻进自己的渲染流程的。

等你自己理解了这套设计思路，再挑出确实用得上的那部分功能，让 AI 按你自己的仓库风格复刻过来。

这里有个关键区分：复刻不是复制粘贴。复制粘贴是把别人的代码原样搬过来，你不知道哪行该改哪行该留；复刻是把别人的设计精髓——那个”为什么这么设计”——融进你自己的体系。这样进来的东西才是你的，你才改得动、养得起，环境变了你也知道怎么调。

四、经常用经常改：skill 是磨出来的

skill 不是写完就定型的，是磨出来的。

我这 22 个里，没有哪个是初版、甚至改了好几版就顺手的——都是一边用一边磨合，慢慢才好用起来。拿我最复杂那个 skill 说，我改了不知道多少版。每真用一次，就可能发现新问题：这里 agent 又走捷径了、那里该补个脚本兜底、这个 description 换个说法触发更准。

前面提的那个渲染兜底脚本，就是这么来的——不是一开始就规划好的，是 agent 在同一个结构性规则上屡次翻车，我反复被坑之后，才下定决心写个脚本强行兜住。这种改进，你坐在那里想是想不出来的，得真用。

所以我的节奏就是一句话：用，发现问题，改，再用。循环往复。

一个 skill 用上十来次，才算初步成型；用上几十次，它才会真的顺手。别指望一劳永逸地写出完美 skill，也别怕改——skill 这东西，越改越值钱。你现在看我这 22 个 skill 觉得有点门道，其实每个背后都是几十轮”用了就改”磨出来的。

五、重复三次，就把它做成 skill

还有一条判断标准，是我这段时间最管用的——只要有一个操作让你重复做了三次，那你就要考虑把它做成 skill。

三次是个很准的信号。第一次你手做，正常；第二次你又手做一遍，会想”好像刚才弄过”；到第三次，你心里就该拉警报了：这玩意儿我大概率还会做第四次、第五次，每次都手动来一遍，又累又容易出错。这时候就别犹豫，把它沉淀成 skill。

我那 22 个 skill，一大半就是这么来的。不是说某天坐下来规划”我要建一个工具集”，而是用着用着发现：这个排版流程我每周都手动走一遍、那个发布步骤我每篇都要重复操作、这段处理我上个月刚写过几乎一样的——重复到第三次，我就知道该把它固化下来了。把重复劳动变成一次性的搭建，往后全是省。

反过来说，只做一次两次的事，别急着做 skill，过度工程化也是一种累。三次，是个刚刚好的阈值：既不会太早（避免给一次性需求过度投资），也不会太晚（避免在重复劳动里耗太久）。

这几条心得，才是我真正想输出的东西。至于下面这些写 skill 的技术规矩，你心里有个数就行，写的时候对照着注意点，别踩坑就够了。

六、写的时候，这几点注意一下

前面几条是”怎么把 skill 越写越好”的心法。这一节是”写的时候别犯低级错误”的清单，快速过一遍。

description 是唯一的路由信号，没有关键词匹配器。 agent 不会扫你所有 skill 的正文，它只看每个 skill 的 description（还会截断到约 250 字符）判断要不要加载。所以 description 写得不好，这个 skill 就等于不存在。写法上：第三人称、“Use when”开头、触发词前置在前 250 字符里。我的 skill 还会在 description 里直接列出”触发场景：用户提到……”这类短语，让它一身两职。

frontmatter 有硬规矩。 name 要小写 kebab-case（就是全小写、单词之间用连字符连接，比如 whisper-transcribe）、1 到 64 字符、和目录名一致；description 上限 1024 字符，超了 skill 直接被丢弃，而且最好写成单行——多行 description 会破坏注册和路由，这是社区里反复被踩的坑。

SKILL.md 是目录不是说明书。 正文控制在 500 行以内，细节推到 references/ 和 scripts/。引用文件保持一层深——reference 别再去引用另一个 reference，不然 agent 遇到嵌套引用可能只读一部分就走。

路径和密钥走 config，别硬编码。 我仓库里每个 skill 都有个 config.json（配置文件，存路径、模型名等参数）当唯一来源，解释器路径、模型名、API key 都从这读。注意 config 里存的是环境变量名（比如 MIMO_API_KEY），不是密钥本身。还有，别假设 PATH 上的 python 是对的，统一用 config 里指定的解释器。

长流程加状态机。 跑多个阶段、可能中途失败的 skill，写个 state.json（状态记录文件，记下每一步做到哪了）记录进度，启动时跳过已完成步骤。有个反直觉的原则：信任文件系统，胜过信任状态记录——文件存在且非空才是真的完成，state 只是提示。

派子 agent 的话，验证后只重试一次。 goal 里写死输出路径，子 agent 返回后立刻读文件验证它存在且非空，失败就带错误上下文重试一次，再失败就记下来跳过——别让一个子 agent 的失败卡死整条流水线。

给你一张核对清单，写完对照着勾：

• description 说清”何时用”，且触发词在前 250 字符？
• name 是 kebab-case、≤64 字符、和目录名一致？
• description 单行、≤1024 字符？
• 正文在 500 行内，细节进了 references/scripts？
• reference 只一层深？
• 路径密钥走 config，没硬编码？
• 长流程写了 state.json？
• 派子 agent 的话，goal 写死路径且有验证？
• 拿 3 种不同说法测过 description 触发？

有用就点个在看，收藏备用，转发给也在折腾 AI agent 的朋友。这些心得是我从 22 个 skill 里磨出来的，写下来既是复盘，也希望能帮你少走点弯路。