Skill 编写最佳实践（Anthropic + Trae）
Skill 是 AI Agent 的能力扩展单元。把它理解为工具箱里的工具：每把工具只做一件事，但每把都要好用到极致。
本文分两部分：Anthropic 官方设计原则，以及在 OpenClaw 场景下的实践经验。本文默认你会写 Skill。
Skill 旨在解决模型上下文长度问题+能力复用
模型上下文长度有限，Skill 通过渐进披露大幅减少上下文占用，通过 skill 规范让 skill 可打包，可分享，成为所有 bot 的 skill。
一、Skill 设计原则（Anthropic 官方）
1.1 每个 Skill 只做一件事，可组合
为什么这样要求？
-
AI 每调用一个 Skill，系统会注入该 Skill 的全部上下文。如果一个 Skill 塞了太多功能，token 会被稀释，真正需要的知识反而被冲淡。
-
更关键的是：单一职责的 Skill 更容易测试、复用和调试。多个简单 Skill 可以自由组合，复杂的工具链由调用方（Agent 或工作流）负责编排。
反面例子：
-
一个 Skill 既能"查询数据库"又能"发送邮件"还能"生成报告"。三个功能绑在一起，description 没法写清楚触发条件，模型也不知道什么时候该调用。
正面例子：
-
三个独立 Skill——query-database、send-email、generate-report，由工作流按顺序调用。description 写得精准，模型只在相关场景才触发。
举例子：
elastic-debug 这个 Skill 只负责一件事：根据 task_id 或场景关键词，查内部服务的日志和监控数据，输出结论。它不负责修复、不负责发送告警、不负责创建工单。这些能力由其他 Skill 负责，或者由调用它的 Agent 自己判断下一步。
description 写的是：
触发场景：(1) 给出 task_id 要求排查 (2) 询问某服务/场景的失败率、产能、吞吐 (3) 要求查某场景的失败原因 (4) 提到 ai 平台等关键词。自动执行查询，直接输出结论。
四个字说明触发条件，模型一看就知道什么时候该用它。
1.2 渐进披露：Metadata（~100词元）→ Instructions操作说明（<5k）→ Resources附件（按需）
Metadata（description）是触发条件，必须简短。
Instructions 是使用说明，控制 Skill 的调用方式。
Resources 是附件，在确实需要时再加载。
这个三层结构的本质是：把决策信息放在前面，把执行细节放在后面。
模型决定"要不要调用"，只需要看 description，不需要读完整份 SKILL.md。description 读完了再读 Instructions，了解怎么用。Resources 只有在前两步确定需要时才加载。
反面例子：
Description 写了两百字，把 API 参数、返回格式、错误码全塞进去。description 过长，模型反而抓不住重点。
正面例子（elastic-debug）：
description 只有上面引用的四行。Instructions 写的是具体的查询命令和决策逻辑。references/ 目录下有 fields.md 等参考文档，详细列出了字段和场景的对应关系。
SKILL.md 主文件读下来不到 100 行，但核心指令全在里面。查某个字段的细节时，Agent 自己去 references/ 下找。
1.3 Description 是触发器：写"什么时候用"，不写"做什么"
这是最容易犯的错误。
反例：
Description: "这个 Skill 可以查询知识库文档、创建文档、修改权限。"
这个描述没有说明白什么时候应该用它。模型会困惑："用户想操作知识库了，但我不确定这是不是最佳方式"。
正例：
Description: "当用户提到'知识库URL'、'查询文档'、'创建文档'、'文档权限'时触发。用于知识库文档管理。"
描述的是触发场景，不是功能清单。模型看到前者会判断："用户想操作知识库文档了，我应该调用这个 Skill"。
关键区别：
-
触发器：用户说了什么（场景关键词）
-
功能清单：Skill 能做什么（能力列表）
1.4 写 Skill 的 Gotchas（踩坑点）
以下 9 条是大量实践中总结出的避坑清单，按重要程度排列。
第一条：Description 写触发条件，不写功能描述
见 1.3。核心是把"什么时候用"和"做什么"分开。前者放 Description，后者放 Instructions。
第二条：不写通用知识，只写团队特有逻辑
Skill 不是知识库。模型本身已经具备通用能力（写代码、查文档、搜索等），Skill 的价值在于补充团队特有的业务逻辑、流程和系统接入方式。
反面例子：
在 Skill 里写"HTTP 请求需要包含 Authorization header，响应是 JSON 格式"。这是通用常识，不需要写。
正面例子：
eac内部 Skill 应该写"EAC-UGate Token 的缓存机制在哪里、有效期多久、过期后怎么刷新"，而不是"什么是 Token"。
elastic-debug 里写的是"按 task_id 查时，格式是 数字-类型（如 123-gemini_image）"，这是内部特有的 ID 格式约定，模型不可能预先知道。
第三条：必须加 Gotchas
每个 Skill 都应该有 Gotchas 节，即使只有一条。
常见 Gotchas 类型：
-
认证信息过期后的处理方式
-
哪些操作是不可逆的（删除、取消、覆盖等）
-
特殊参数格式要求
-
调用频率限制
elastic-debug 的 Gotchas：
沿数据链往上追是进阶手段，仅在以下情况使用：task_error 的报错和实际原因对不上、错误看起来不合理怀疑输入数据本身有问题、同一个 task 大面积失败报错模式异常。
这条 Gotchas 来自真实案例：曾经有人追查gemini 生图的 JSON 解析失败，追到上游发现是生图规划大模型输出重复爆炸，导致数据被截断。表面上是前者的 bug，实际根因在上游。没有这条 Gotchas，Agent 可能会一直在gemini这层绕。
第四条：用文件夹结构，渐进披露
如果一个 Skill 包含多个子主题，用文件夹组织：
skill/ SKILL.md # 主文件，包含 Instructions 和触发条件 references/ # 参考文档（API 参数、详细说明） scripts/ # 预制脚本
主文件只放最核心的指令，具体细节放到 references/ 下的独立文件。elastic-debug 就是这样组织的：SKILL.md 里写决策逻辑，references/fields.md 里放字段映射表。
第五条：用 config 做配置流程
需要用户提供配置（如 API Key、Token）的 Skill，应该在 SKILL.md 里写清楚环境变量或配置文件的位置，而不是每次都要求用户手动输入。
反面例子：
每次调用都让用户输入密码。
正面例子：
从 ~/.skill_prefs.json 读取用户上次输入的手机号，如果文件不存在再询问。
第六条：不过度约束，给模型灵活性
Skill 指令不等于程序代码。AI 需要一定的灵活性来适应用户的具体语境。
反面例子：
"必须按顺序执行以下步骤：第一步...第二步...第三步..."
如果模型本身能够通过对话自然引导用户完成这些信息，不需要写死这个顺序。
正面例子：
"通常按 A → B → C 的顺序执行，但如果用户明确指定了顺序，按用户意图优先。"
elastic-debug 的决策逻辑里写了"大多数情况 处理器 接口返回的 task_flow_error 就够定位问题"，而不是写死"必须先查 A 再查 B 再查 C"。
第七条：加记录（有状态 Skill）
如果 Skill 需要跨对话记住某些状态（比如用户的偏好、Token 有效期等），在 SKILL.md 里说明状态存储方式。
反面例子：
每次调用都让用户重新输入手机号。
正面例子：
从 ~/.openclaw/hair-salon-prefs.json 读取用户上次选择的店铺、发型师、手机号。
这个理发 skill就是这样设计的：首次用需要提供手机号，后续自动从配置文件读取，用户只需要说"还约上次那个发型师"就行。
第八条：预制脚本避免重复
重复的 shell 命令、Python 代码片段，应该抽成独立脚本放在 scripts/ 目录。SKILL.md 里只写"调用方式"，不写具体实现细节。
好处：
-
不会被加载进入上下文。一个脚本可能有几千 token，大模型能执行就行，加载进上下文不仅占用上下文长度，还容易影响大模型注意力。
-
修改脚本逻辑时不需要改 SKILL.md
elastic-debug 的 elastic-query.sh 就是预制脚本，所有 Elastic 查询都走这一个脚本，不需要在 SKILL.md 里写 curl 命令。
第九条：按需 Hooks（危险规则非常驻）
对于可能产生破坏性后果的操作（删除文件、取消订单、撤销支付等），可以设计 Hooks 机制——这类规则平时不加载，只在特定操作触发时才介入校验。
例如 ：某人在使用知识库管理 skill 时，把自己的知识库删光了
就可以在 skill 里加入：
## 危险操作 Hook
执行以下操作前，必须先获得用户明确确认：
- 删除文档
- 修改权限
- 导出数据
### 确认模板
执行 {operation} 前，必须：
1. 列出受影响的对象
2. 询问："确认执行 {operation} 吗？（是/否）"
3. 只有用户回复"是"才继续二、Skills 实践经验（TRAE 团队的分享）
以下经验来自内部 OpenClaw Agent 建设过程中的踩坑和验证。
2.1 Session-Learning：把每次解决问题的经验沉淀下来
多轮对话中，AI 容易"越跑越偏"——前面已经验证过的正确方向，在后续对话中被推翻。
实操方式：
-
每完成一个复杂任务，主动问用户："这个解决方案要不要固化到 Skill 里？"
-
固化时更新对应的 SKILL.md 或 Gotchas 节
-
多轮对话的最后阶段，做一次"路径回顾"，确保这次用到的经验在下一次还能用上
一个真实场景：
用 elastic-debug 排查一个任务失败的问题，第一次查的时候发现 processor 接口和 Elastic 日志都要看，第二次排查类似问题时，Agent 直接把这条经验写进了 Gotchas：同类型的失败优先查 processor 接口，不够再查 Elastic。
2.2 代码优先：把 SOP 和业务知识沉淀成可复用 Skill
团队特有的 SOP（标准操作流程），比通用知识更需要 Skill 化。
反面案例：
每次部署流程都用文字描述："先去 XX 系统申请权限，然后登录 XX 主机，执行 XX 命令"。模型每次都要重新理解这些步骤，而且文字描述容易漏掉细节。
正面案例：
把这些步骤写成 deploy skill，里面包含具体的系统地址、命令模板、权限申请入口。新工程师入职后，直接说"帮我执行部署流程"，剩下的 AI 自动完成。
2.3 按需加载：让 AI 只加载真正需要的知识
不是所有 Skill 都要在每次对话中激活。OpenClaw 的 Skill 触发机制基于 description 匹配——description 写得精准，AI 只在真正相关时才加载。
按需加载的好处：
-
省 token（上下文越小，模型响应越快）
-
减少干扰（无关 Skill 的指令不会混入推理过程）
-
便于维护（单个 Skill 修改不影响其他）
三、快速检查清单
写完一个 Skill 后，对照以下问题自检：
Description 部分：
-
是否写的是触发条件（什么时候用），而不是功能清单（能做什么）？
-
模型看到这段描述，能否准确判断是否应该调用？
-
字数是否控制在 100 token 以内？
Instructions 部分：
-
是否只写了团队特有逻辑，没有重复通用知识？
-
是否有 Gotchas 节，列出常见的坑？
-
破坏性操作（删除、取消、覆盖）是否有提醒？
-
给模型的约束是必要的还是过度的？
整体结构：
-
是否符合渐进披露原则？（核心指令在前，详细参考在后）
-
是否有状态持久化需求？如果有，是否说明了存储方式？
-
是否有重复代码片段？是否应该抽到 scripts/ 目录？
四、常见错误案例
案例一：把 Skill 写成使用手册
错误写法：
Description: "这个 Skill 是内部代码搜索工具的使用说明..."
这是说明书思维，不是触发器思维。
clawhub 上的很多热门 skill 的 Description 都存在这个问题
例子 1：tavily-search：
通过Tavily API进行AI优化的网页搜索。为AI代理返回简洁、相关的结果。
例子 2：humanizer：
从文本中移除人工智能生成写作的痕迹。适用于编辑或审阅时使用 使文本听起来更自然，更像人工编写的。基于维基百科的 全面的“AI写作迹象”指南。检测并修正以下模式： 夸张的象征意义，浮夸的宣传语言，肤浅的表面化分析，模糊不清 归因、破折号过度使用、三法则、人工智能词汇、否定 并列结构过多，以及过多的连词短语。
正确写法：
Description: 当用户询问大模型用量、模型额度、AI消费、LLM使用情况、One API剩余额度、本月/今天用了多少钱时触发使用。
如果你发现一个新安装的 skill 改触发却没被触发，那可以看看他的 Description，有时候不是模型笨，是 skill 写的不行，你二次优化一下 Description，触发效果会好很多。
案例二：塞入过多功能
一个 Skill 同时支持：抖音视频下载，抖音视频转 mp3，语音转文字，内容优化+总结
分成多个 skill，灵活性更强。
这点看具体情况，我就是不想拆 skill，一个 skill 就够用了，那也行。
案例三：缺少 Gotchas
没有说明认证 Token 有效期，导致用户在关键操作时突然失败。Gotchas 里一定要写清楚认证方式和失效处理。
案例四：给模型太多约束
"你必须先确认用户手机号，再确认预约时间，最后才能提交订单。"
如果模型本身能够通过对话自然引导用户完成这些信息，不需要写死这个顺序。保留灵活性，减少过度约束。
五、总结
Skill 编写的核心心法：
-
触发器（description）要精准——让模型一看就知道该不该用
-
指令要专注——只写团队知识，不写通用常识
-
结构要渐进——核心在前，细节按需加载
-
坑要提前标——Gotchas 是经验沉淀，不是废话
做到这四点，一个 Skill 就是好用的工具。这些你大概了解就行，但是得让你的龙虾记住。
如果你还不会写 skill，把简单的小需求告诉龙虾，让他写一个 skill，你看看他写出来的 skill 文件，大概就清楚 skill 的写法了，而你只需要关注他是否完成上面几点，未完成就 督促+提供龙虾所需的内容 即可
六、参考资料链接
Anthropic 官方：
OpenAI 官方：
企业实践（TRAE）：
-
2026 企业级AI编程实践手册（完整版，含六大方法论 + 开发实践）
第三方：
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
5
0- 0
已为社区贡献1条内容
所有评论(0)