怎么写专业的 Skill
你有没有过这种经历:给 AI Agent 写了一个 Skill,它能跑,但总是触发不准、执行不稳、隔两天就出 bug?就像做菜——照着网上的菜谱做,味道对,但跟大厨做的差了点什么。
差的那点东西,就是专业性。
我维护过一个 10 万行级别的 Skill(WeWrite 公众号全流程助手),从最初的一个简单脚本迭代到现在。过程中踩过的坑、总结的方法论,今天系统性地分享出来。
先搞清楚:Skill 是什么
30 秒版本:Skill = 给 AI Agent 的工作手册。
不是提示词(prompt),不是 API 文档,而是一份结构化的操作指南,告诉 Agent:
- 什么时候该被触发(trigger)
- 怎么一步步完成任务(workflow)
- 什么情况下会出错以及怎么处理(pitfall)
- 做完之后怎么验证结果(verification)
一个 Skill 的物理结构长这样:
SKILL.md 是唯一必需的文件,其他都是辅助。但专业的 Skill 和入门级 Skill 的差距,恰恰就在这些辅助文件里。
能跑 vs 专业:一个对比
我用两个真实案例来说明差距。
案例 A:入门级 Skill(aihot)
这是一个查询 AI 资讯的 Skill,核心功能正确,结构清晰。它的 frontmatter 长这样:
工作流部分只有一段核心命令:
能用吗?完全能用。 239 行代码,11KB 大小,功能完整。
案例 B:专业级 Skill(WeWrite)
同样是完成一个任务,WeWrite 这个公众号写作 Skill 有这些额外的东西:
文件大小:11KB vs 103KB+。 不是故意写长,而是每个字节都在解决一个实际问题。
专业 Skill 的五个关键维度
1. Frontmatter:Agent 决定是否加载你的 Skill 的唯一依据
这是最重要也最容易被忽视的部分。
Agent 在加载 Skill 之前,只能看到 frontmatter 里的 name 和 description。 如果这两个字段写得不好,你的 Skill 就像一本没有封面的书——再好也没人打开。
入门级写法:
问题:太泛。"帮我做 X 事"可以匹配任何请求,导致过度触发(在不该用的时候被加载)或者触发不准(在该用的时候没被选中)。
专业级写法:
关键改进:
- description ≤ 1024 字符(Hermes 硬性限制),但要把触发条件写清楚
- 明确反向触发词(Do NOT use for):减少误触发
- 添加 metadata:tags 用于分类检索,related_skills 用于关联推荐
- 版本号:方便后续迭代追踪
2. 结构化指令:让 Agent 能"按图施工"
入门级的指令通常是段落式的:
先拉数据,然后处理一下,最后输出结果是 Agent 对"处理一下"的理解可能跟你完全不同。
专业级用分步骤 + 表格 + 代码块的组合。下面是一个工作流片段的写法示例——先定义参数表,再给命令:
输出格式:JSON 数组,每项包含 {id, title, category, url, published_at}。下一步将输出传入 Step 2 进行过滤。
注意这几个细节:
- 表格定义参数:Agent 不需要猜
- 代码块可直接复制运行:不省略任何参数
- 明确输出格式:下一步知道该怎么接
- 兼容性处理:macOS 和 Linux 的 date 命令不同
3. 错误处理:专业和业余的分水岭
入门级 Skill 假设一切顺利。专业级 Skill 假设一定会出错。
下面是一段 pitfalls 章节的写法示例——每个坑都按"现象→原因→处理"三段式展开:
Pitfall 1:API 返回空结果
items 数组为空,但 HTTP 状态码是 200。原因:时间窗口内无数据,或 since 参数格式错误。