Agent Skill 怎么写:SKILL.md 的结构、触发描述和 5 个常见错误

Skill 是把一段可复用的做事方法打包给 AI 的文件夹,核心是一个 SKILL.md。这篇讲清楚 SKILL.md 由哪几部分组成、description 为什么决定它会不会被调用、什么内容该拆到附件里,以及写 Skill 时最常见的 5 个错误。

Agent SkillSKILL.mdSkill 怎么写Claude Skill技能包

同一个任务,你每次都要给 AI 交代一遍步骤、格式和注意事项,这时就该把它写成一个 Skill。Skill 本质上是一个文件夹:里面一个 SKILL.md 写清楚「什么时候用、怎么做」,再按需放脚本、参考资料和模板。AI 平时只看到每个 Skill 的名字和一句描述,判断用得上时才读取全文,所以装几十个 Skill 也不会挤占上下文。

SKILL.md 由三部分组成

第一部分是开头的元信息,最关键的是 name 和 description。name 是简短的标识,description 用一两句话说明这个 Skill 做什么、在什么情况下该用。第二部分是正文,写具体步骤:先做什么、再做什么、输出什么格式、遇到异常怎么处理。第三部分是附件,放在同一个文件夹里,比如处理数据的脚本、长篇的规范文档、输出模板,正文里写明什么时候去读哪个文件。

description 决定它会不会被调用

很多 Skill 写得很好却从来没被用上,原因几乎都在 description。AI 是靠 description 判断「这个请求要不要用这个 Skill」的,所以它要像搜索关键词一样具体:写出用户会怎么说、处理什么类型的文件、产出什么结果。「帮助处理文档」太模糊;「把会议录音转写稿整理成带待办事项的会议纪要,用户提到会议纪要、整理录音、会后总结时使用」就清楚得多。

正文写步骤,不写道理

正文是给 AI 执行的,不是给人读的说明书。用编号步骤,每一步一个动作;把判断条件写明白,比如「如果文件超过 100 行,先拆分」;给一个完整的输入输出示例,比写三段原则有用。需要精确执行的部分,比如格式转换、数据计算,尽量写成脚本放进文件夹,让 AI 调用脚本而不是每次自己重写一遍。

写 Skill 最常见的 5 个错误

一是 description 太泛,结果该触发时不触发,不该触发时乱触发。二是把所有内容都塞进 SKILL.md,几千字的正文每次都要读,又慢又容易漏看重点,长资料应该拆成附件。三是只写原则不给示例,AI 对「简洁专业」的理解和你不一样。四是没有测试,写完就上线,应该准备几条真实请求,看它会不会被正确调用、输出是否合格。五是把密钥、账号写进 Skill,Skill 往往会被分享和复制,敏感信息要放在环境变量里。

从个人 Skill 到企业技能包

个人用的 Skill 写完能跑就行;要在团队或企业里共享,还要考虑版本管理、安全审查、效果评测和统一分发。这就是从「一个好用的 Skill」到「企业 Skill 技能包」之间的距离。

图解 Skill 这门课用 56 讲图解,从 Skill 的原理讲起,带你从纸上草图开始,一步步做出一个经过测试、安全审查、能发布到企业 SkillHub 的技能包,前 6 讲免费。