夜雨聆风说个真事。三个月前我写了个 Skill，自认为逻辑清晰、边界明确。丢给 Agent 跑了一遍，完美通过。当时还挺得意。
然后第二次跑，换了组数据，整个流程直接跑偏。第三次换了个场景，Agent 干脆绕过了我的 Skill 去干别的事了。
我盯着日志看了半天，脑子里就一个念头：这东西没我想的那么简单。
这半年我从零开始做 AI Skills，踩过的坑比我预想的多得多。不是要当老师，就是想把踩过的坑摊开说说——说不定你正在哪个坑边上站着。
一、Skill 不是会写 prompt 就能搞定的事
我最早犯的错误就是太轻敌。觉得自己写了大半年 prompt，写个 Skill 还不是手到擒来。
真正动手才发现完全不是一回事。写 prompt 是跟模型对话，你告诉它"怎么做"就行。写 Skill 是在设计一套工作流——触发条件、执行边界、异常处理、输出标准，少想一环就翻车。
最惨的一个例子是同事写的 Skill，上线第一天就把不该执行的 SQL 给跑了。好在是测试环境，但也把大家吓出一身冷汗。
Skills 这事，轻敌的代价比你想象的大。
二、Skills 不是装得越多越好
有段时间我特别热衷装各种 Skills，看到别人推荐就装上，总觉得"早晚用得上"。
一个月后回头看，十几个 Skills 里真正用得上的不到三分之一。剩下的要么跟我的工作场景八竿子打不着，要么就是老被误触发——Agent 莫名其妙调了一个不该调的 Skill，输出还不如不调。
而且 Skills 装多了，每次启动都要加载元信息，上下文占得不少。
后来我给自己定了规矩：装之前先问三个问题——这个任务我每周做几次？没有它我做这事要多花多久？它跟现有的 Skills 会不会打架？
过一遍这三个问题，至少能过滤掉一半用不上的。
三、description 随便写写？那你等着被坑吧
这个坑我实打实栽过。
最早写 Skill，description 就一句话："一个代码审查工具"。结果 Agent 该审查的时候不审查，不该审查的时候瞎审查。
后来琢磨明白了：description 就是 Agent 的路牌。写不清楚，Agent 就只能靠猜。猜对了是你运气好，猜错了是你活该。
现在的写法是长这样：
"审查当前 diff 中的代码变更，检查逻辑错误、测试覆盖和破坏性变更。当 diff 中包含代码修改时自动触发。"
把触发场景说清楚，误触发的概率至少降一半。
四、用 Skills 真不一定省钱
这个我得展开说说。
Skills 的好处是渐进式加载，这没问题。但如果装得太多，启动时元信息的 Tokens 消耗也是个不小的数。
还有个更隐蔽的问题：很多人为了"省 Tokens"，把 Skill 写得特别短。结果模型倒是省 Tokens 了，做的事完全不是你要的。我见过一个发布类的 Skill，因为写得过于精简，Agent 直接把草稿发出去了——没有确认，没有预览，就这么发出去了。
省几十块钱的 Tokens，废掉一次关键输出，这账怎么算都不划算。
五、知识应该放哪里？看它变不变
刚开始做 Skill 的时候，我纠结过一个问题：领域知识是写死在 SKILL.md 里，还是放外部知识库？
现在的结论很简单：不变的知识写进 Skill，变的知识走外部调用。
举个例子。团队的代码规范基本不会变，这种直接写进 Skill。但数据库表结构这周改了三次——这种就应该通过脚本实时拉取，而不是固化在 Markdown 里。
把 Skill 理解成"流程封装"而不是"知识容器"，设计思路会清晰很多。
六、Skill 真不只是一份 Markdown
很多人觉得 Skill 就是写个 Markdown 文件。这个印象太片面了。
Markdown 只是告诉模型"怎么做"。真正干活的是背后绑定的脚本、模板和工具链。Skill 可以带脚本、带模板、带素材，不只是一堆文字。
我现在比较推崇的做法：确定性的操作交给脚本，需要判断和创造的部分留给模型。脚本负责格式转换、文件处理、API 调用这些——让模型干这些事反而容易翻车，脚本一次写对永远对。
各司其职，效率最高。
七、拆得太粗或太细，都是坑
这个我走了不少弯路。
一开始我喜欢一个大 Skill 包揽所有功能。结果场景一多，触发逻辑变得特别拧巴，改一次要调半天。
后来走向另一个极端：一个功能拆成七八个小 Skill。结果是 Agent 自己在那做"路由选择"的时间，比干活的时间还长。
现在的经验是：按调用边界切分，别按文件大小切。用户主动调用的 Skill，可以整合得粗一点；需要 Agent 自动触发的，切得细一点反而好用。
八、别指望 Skill 自己打通外部系统
这个认知我一开始就有，但没太当回事。直到第一次让 Agent 操作飞书文档，翻车了才重视。
Skill 能干的事其实很明确：告诉 Agent 先做什么后做什么、做到什么程度算完。它不负责打通系统。
真要连外部系统，还得靠 MCP、API、SDK、脚本这些。Skill 是在这些能力之上做编排，不是替代它们。
如果你的 Agent 连不上数据库，问题不是 Skill 写得不好，是缺了一层连接能力。
九、工具声明当不了安全锁
有些平台支持在 Skill 里声明 allowed-tools。我一开始以为这就是"紧箍咒"——写上去了，Agent 就不会越界。
后来发现不是这么回事。这个声明很大程度上取决于宿主平台执不执行。有些平台只是当个参考，Agent 该用还是用。
所以真正敏感的操作——写数据库、发消息、删文件——不能指望 Skill 的声明来兜底。权限系统和人工确认才是最后一道防线。
我的原则：写操作一定要经过人确认，不管 Skill 里怎么写的。
十、同一个 Skill 在不同平台，表现可能完全不同
这个坑我实打实踩过。
同一个 Skill 文件，在 Claude Code 里跑得好好的，丢到 Codex 里就完全不按预期走。后来才发现两个平台的触发机制根本不一样——一个认 SKILL.md 的 frontmatter 字段，另一个认 agents 目录下的 YAML 配置文件。
所以设计 Skill 不能只写一份 Markdown 就完事。要想清楚这个 Skill 在什么平台上跑、谁来触发、怎么触发。
有些 Skill（发布文章、执行部署、删数据）必须做成手动触发，千万别让模型自己决定。
十一、没有验收标准的 Skill 是半成品
我最早写 Skill 只写步骤："第一步做什么，第二步做什么"。结果模型每一步都做了，但做出来的东西跟我想要的天差地别。
后来加上了验收标准：什么叫完成、什么叫合格、什么情况算失败。效果立竿见影。
比如一个文章解读的 Skill，我现在的写法是：
必须抓取原文完整内容并落盘 必须区分作者观点和自己的分析 必须给出可操作的结论，不能停留在"文章说了什么" 如果文章内容与已有知识冲突，必须明确指出 字数控制在 1500 字以内，超出则分段
模型有了这些"标尺"，输出质量稳定太多了。
十二、"跑通一次"不等于"稳定可用"
这一条可能是最重要的。
我最早犯的错误：一个 Skill 跑通一次就觉得自己做完了。后来发现，同一个任务换组输入，结果可能天差地别。
现在我的做法是：给每个核心 Skill 配一个评测集，覆盖正常场景、边界场景、异常场景。每次改完 Skill，跑一遍评测集，看输出质量和稳定性有没有下降。
这听起来麻烦，但长远看是省时间的。没有评测的 Skill 就像没有测试的代码——你永远不知道它什么时候会炸。
写了这么多，其实核心就一句话：做 Skills 真正难的从来不是"写出来"，而是"写好、用稳、持续迭代"。
回看这半年，我最庆幸的不是做了多少个 Skill，而是踩了这些坑之后，终于知道什么东西值得做、什么东西不该碰。
如果你也在折腾 AI Skills，希望你从这些坑上面跨过去，别往里跳。
