自定义 skill 从零到可用:我写废三个才明白的两件事
把提示词存成文件就算做成 skill 了吗?写废三个之后我才明白:决定它会不会被自动触发的,是 frontmatter 里那段 description。
我第一个自定义 skill 是这么诞生的:某次修好了 WorkBuddy 内置 bash 的 PATH 残缺问题,觉得这套排查太值钱,于是把它整段复制进一个 SKILL.md,正文写了几百行。结果后来三次再遇到同样的报错,它一次都没被触发过——我都是自己想起来"哦我写过这个",手动去 skills\ 目录里翻。
这件事让我意识到:skill 不是文档,是触发器。 正文决定它触发之后好不好用,frontmatter 决定它会不会被触发。而我前三个 skill 全部栽在后者。
先看官方 skill 的 frontmatter 长什么样
我把机器上 C:\Users\admin\.workbuddy\skills\ 下的 21 个目录都翻了一遍,发现 frontmatter 的字段远比我想的丰富:
---
name: wj-nation-team-etf-monitor
version: 1.0.1
display_name: 国家队买卖ETF监控(望京博格版)
display_name_en: WJ Bogle National-team ETF Monitor
prerequisites: 必须已装金融数据 MCP(Wind 系列)。核心能力三条:① 场内基金日 K(取成交额)② ETF 日频「基金资金净流入额」③ 沪深300 日 K。缺任意一条就跑不通
description: 用 Wind 日频数据估算「国家队」通过宽基 ETF 一级市场申购进出的规模……当用户提到「国家队」「汇金」「证金」「国家队抄底」「国家队买 ETF」「ETF 放量是不是国家队」「宽基 ETF 资金流入」「扫货」时使用。
description_zh: "……"
description_en: "……"
agent_created: true
---这个文件 14803 字节、233 行。注意 description 那一段有多长——它不是一句话,是一整段任务说明 + 一长串触发词。
这就是我第一个认知错误:我以为 description 是给人看的摘要。实际上它是给模型看的路由条件,写得越具体、触发词越贴近用户真实说法,命中率越高。
两种极端的写法,都来自真实文件
对比一下我找到的两个极端:
极端 A:7 行的 skill
---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---正文只有一行:"Call the Skill tool with 'grilling'"。这个 skill 的关键全在 disable-model-invocation: true——它明确告诉系统「别自动触发我,只在用户点名时加载」。适合那种「自动触发会很烦」的场景。
极端 B:正文里塞满报错原文的 skill
---
name: workbuddy-bash-env-repair
description: 诊断并修复 WorkBuddy 内置 bash 的 PATH 残缺问题。当 Bash 工具报错 `dirname: command not found`、`cd: null directory`,或 `head`/`tail`/`ls`/`sed`/`grep` 等 GNU 工具集体不可用,或 WorkBuddy 升级后安全删除链(safe-bin)静默失效时使用。
---这个 4915 字节、111 行。它做对了一件事:把用户会看到的确切报错字符串原样写进 description。
我第一次看到时觉得这样很丑。后来才明白这是唯一正确的做法——用户遇到问题时,脑子里想的是"它报了个 dirname: command not found",绝不会想"我的 GNU coreutils 缺失"。触发词必须用用户的语言,不是技术的语言。
我踩的三个坑
| 坑 | 我当时的写法 | 结果 | 改法 |
|---|---|---|---|
| 只写技术描述 | "修复 POSIX shell 环境变量注入" | 三次都没触发 | 把报错原文抄进 description |
| 正文塞满教程 | 800 行,从原理讲到历史 | 触发后模型读完就跑偏 | 正文只留诊断 3 步 + 修复 1 行 |
| 没写 prerequisites | 默认假设环境齐全 | 触发后第七步才失败 | frontmatter 顶部声明硬依赖 |
第三个坑最贵。我写过一个依赖 Wind MCP 的 skill,正文一路顺畅写到第 40 行才说"需要 get_index_fundamentals"。实际执行时如果 MCP 没挂载,模型会先花几千 token 做一堆无用准备,然后才在中间某步报错。而 wj-nation-team-etf-monitor 的做法是把这句话提到 frontmatter 的 prerequisites 里:
缺任意一条就跑不通,验证方法见
references/data-contract.md
把"跑不通"的判断提前到加载时,而不是执行时。 这一条让我省掉了大量"skill 触发了但白跑一遍"的浪费。
正文该写多长:看那个 70 行的浏览器 skill
我原以为正文越长越好。直到看到内置的浏览器 skill——native-runtimes\browser-use\browser-use\skills\workbuddy-browser-use\SKILL.md,70 行,结构是:
## 使用场景 (8 条,全是用户视角的"我要干什么")
## 使用前准备 (外部浏览器需要用户装扩展的 4 步)
## 操作原则 (7 条铁律)
## 执行规范 (7 条编号流程)全文没有一句"什么是浏览器自动化"。它的每一条都是可执行的动作或不可违反的约束。比如:
5. 页面跳转、表单提交、弹窗变化或内容明显更新后,重新读取 DOM。
元素标识只在当前页面快照中有效,失效后不能继续操作。这句话是在修一个具体的 bug:DOM 节点标识会失效。它没有解释「为什么 DOM 是无状态的」,直接给了动作。
这是我现在写 skill 的模板:每条约束背后必须有一个我真实踩过的坑,写不出坑的条目就删掉。
复盘
一个可用的 skill,我现在的检查清单是四行:
description里有没有至少 5 个用户真实会说的词?(含报错原文)- 硬依赖有没有写进
prerequisites? - 正文里每一条能不能对应到一个具体动作或具体坑?
- 有没有考虑过加
disable-model-invocation: true——有些 skill 自动触发就是灾难。
下一步我想把那个 111 行的 bash 修复 skill 再做一版:把「诊断 3 条命令」单独抽成 references/diagnose.md,正文只留一行指针。这样触发后模型先跑诊断,确认命中才读细节,不命中就直接退出——省掉一整轮无用加载。