1. 为什么你的 Skill 总是“叫不醒”很多人第一次写 WorkBuddy 的 Skill都会经历同一个尴尬目录建好了脚本也写了可对着对话框说半天AI 同事就是不理你。问题几乎都出在同一份文件上——SKILL.md。你可以把SKILL.md理解成 Skill 的“身份证 岗位说明书”。WorkBuddy 扫描技能目录时只读这一份文件来决定三件事加载不加载、怎么向用户描述、什么时机唤醒。写对了你的 Skill 才算被“雇佣”写错了它永远躺在目录里无人问津。这篇聚焦SKILL.md的完整结构从顶部 YAML 头部到触发条件、Skill 描述、执行入口逐段拆开讲。同时给出一份可直接复制的骨架以及用 TaoToken 统一 Key/API 通道的config.toml配置片段最后演示一次触发条件验证动作。适合已经会装 WorkBuddy、想从“用 AI”升级到“给 AI 造工具”的人。2. 前置准备TaoToken 统一 Key 与 API 通道在写 Skill 之前先把模型通道理顺。Skill 真正干活时往往要调用大模型做意图判断或内容处理如果每个 Skill 各配一套 Key维护起来会很乱。我的做法是用 TaoToken 做统一入口一个 Key 走所有模型调用。TaoToken 在这里扮演的是“统一 API 通道”的角色你拿到一个 Key就能在 Skill 脚本、WorkBuddy 配置、本地调试脚本里复用同一套地址和凭证不用来回切换。先到控制台创建 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建后你会得到一串以sk-开头的 Key先复制到安全的地方。注意Key 只显示一次丢了只能重建。注意不要把 Key 硬编码进SKILL.md或提交到 Git 仓库。正确做法是写进config.toml或环境变量SKILL.md只负责“自我介绍”和“接单条件”。API 基础地址统一用https://taotoken.net/api这个地址不加 UTM 参数直接填进配置即可。3. SKILL.md 完整结构逐段拆解3.1 YAML 头部Skill 的“身份证”SKILL.md顶部是一段用---包裹的 YAML Front Matter这是系统读取的第一段内容。字段语义和最佳实践如下字段必填作用最佳实践name是技能唯一标识符小写下划线如pdf_extractor避免中文与空格version是语义化版本 SemVer严格主.次.修1.0.0 首发、1.1.0 加功能、1.0.1 修 bugdescription是给用户和模型看的“一句话岗位说明”写“能做什么 适合场景”别写“我是谁”author否作者标识个人昵称或组织名便于溯源license否开源协议开源建议显式标注 MIT/Apache-2.0homepage否文档或仓库链接指向说明页方便用户深读description是最影响命中率的字段。调度模型靠它判断“这个 Skill 是否对口”。写得太泛比如“处理文档”会被淹没带上场景动词“抽取/转换/校验/生成”命中更准。name一旦发布就别随意改它是其他配置和历史对话引用该 Skill 的锚点。改名等于换身份证号旧引用全部失效。要改展示名改description别动name。3.2 触发条件决定“唤不唤醒”光有元数据系统只知道“有这个 Skill”触发条件才决定“用户说这句话时该唤醒它”。WorkBuddy 支持四类触发触发类型机制典型场景关键词触发命中特定词或正则即激活固定术语、命令式短语意图触发NLU 理解语义后激活说法多变、同义表达多事件触发文件变化、定时、Webhook后台自动化任务组合触发多条件 AND/OR 逻辑精确控制触发范围实际写法上触发条件通常以“正例 负例”的形式写在正文里给调度模型做 few-shot 判断依据。给负例往往比堆正例更管用因为模型最难的是“该不该用”负例直接划清边界。3.3 Skill 描述与执行入口元数据和触发条件之后正文部分要写清楚“怎么用”。这一段是给模型看的操作说明也是给用户看的文档。建议包含使用方式调用哪个脚本、传什么参数、输出到哪里分支说明什么情况走哪条路径比如扫描件走 OCR依赖引用指向references/下的知识文件执行入口一般指向scripts/目录下的脚本。SKILL.md本身不干活它只负责把活派给脚本和知识库。4. 可直接复制的 SKILL.md 骨架把上面三段拼起来一份真实可加载的SKILL.md长这样--- name: pdf_extractor version: 1.2.0 description: 从 PDF 抽取表格与正文支持扫描件 OCR并导出为 Markdown/Excel author: your_name license: MIT homepage: https://example.com/pdf_extractor --- # PDF 抽取技能 ## 触发条件Trigger 当用户需要从 PDF含扫描件中抽取表格、正文或结构化字段时使用例如 - 把这份 PDF 的表格导成 Excel - OCR 一下这张扫描合同 - 从招股书里提取所有财务数据 以下情况不要使用 - 用户要总结网页文章用通用对话即可 - 用户要写新文档这是创作任务不是抽取 ## 使用方式 1. 调用 scripts/extract.py传入 PDF 路径与输出格式 2. 扫描件自动走 OCR 分支见 references/ocr_notes.md 3. 结果写入用户指定位置这份骨架可以直接复制改掉name、description和触发条件里的例子就能用。5. config.toml 配置接入 TaoToken 通道Skill 脚本要调模型就得有统一的 Key 和地址。在 WorkBuddy 的配置目录里新建或编辑config.toml[llm] provider taotoken base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-20250514 timeout 60 [skill] dir ./skills auto_reload true几个关键点base_url填https://taotoken.net/api不要带多余路径。api_key从控制台复制建议用环境变量注入比如api_key ${TAOTOKEN_API_KEY}避免明文写死。model按你实际可用的模型填不同模型在意图判断上的表现会有差异。如果你要长期跑编码类或 Agent 类 Skill可以关注 Coding Plan额度更划算Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite配置改完后重启 WorkBuddy或者触发一次auto_reload让新配置生效。6. 验证触发条件一次可复现的测试写完SKILL.md和config.toml别急着高兴先验证触发条件是否真的生效。我试过最直接的办法是写一个最小测试脚本模拟调度判断。import os import requests API_KEY os.environ.get(TAOTOKEN_API_KEY) BASE_URL https://taotoken.net/api def check_trigger(user_input: str, skill_desc: str) - bool: prompt f你是一个技能调度器。判断下面这句话是否应该触发该技能。 技能描述{skill_desc} 用户输入{user_input} 只回答 yes 或 no。 resp requests.post( f{BASE_URL}/v1/messages, headers{ x-api-key: API_KEY, anthropic-version: 2023-06-01, content-type: application/json, }, json{ model: claude-sonnet-4-20250514, max_tokens: 10, messages: [{role: user, content: prompt}], }, timeout30, ) answer resp.json()[content][0][text].strip().lower() return answer.startswith(yes) if __name__ __main__: desc 从 PDF 抽取表格与正文支持扫描件 OCR cases [ (把这份 PDF 的表格导成 Excel, True), (OCR 一下这张扫描合同, True), (帮我写一份新合同, False), (总结一下这篇文章, False), ] for text, expect in cases: got check_trigger(text, desc) flag PASS if got expect else FAIL print(f[{flag}] {text} - {got})运行后你会看到类似输出[PASS] 把这份 PDF 的表格导成 Excel - True [PASS] OCR 一下这张扫描合同 - True [PASS] 帮我写一份新合同 - False [PASS] 总结一下这篇文章 - False如果负例被误判成 True说明你的触发条件里负例写得太弱回去补几条“不要使用”的例子。如果正例被漏判检查description是不是太泛把场景动词补上。想直接在对话里验证模型行为可以用模型对话页快速试模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite7. 本篇常见错排查7.1 YAML 头部解析失败最常见的是---没写对或者字段里出现了未转义的特殊字符。检查方法把SKILL.md顶部内容复制到任意 YAML 校验工具里跑一遍。冒号后面记得留空格中文冒号不行。7.2 Skill 加载了但从不触发先看description是不是太泛。其次看触发条件里有没有负例。最后确认config.toml里的skill.dir路径是否正确auto_reload是否开启。改完配置记得重启。7.3 调用模型报 401 或 403多半是 Key 没读到。检查环境变量名是否和配置里一致base_url是否写成了https://taotoken.net/api。如果用的是config.toml明文 Key确认没有多余空格或换行。7.4 触发条件验证脚本超时把timeout调大或者换一个响应更快的模型。如果频繁超时检查网络出口是否稳定。脚本里max_tokens设成 10 就够别设太大浪费额度。7.5 name 改名后旧引用失效这是设计使然。name是主键改名等于换身份证。要改展示名改description。如果确实要改name记得同步更新所有引用它的配置和历史对话。8. 下一步把 Key 和文档用起来SKILL.md这张“身份证”办好了接下来就是让它真正干活。建议你先做两件事第一把config.toml里的 Key 换成环境变量注入别明文写死。接入文档在这里接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite第二如果你要写的是编码类或 Agent 类 Skill直接上 Coding Plan额度更稳Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite下一篇我们拆scripts/与references/两棵目录树入口脚本怎么命名、参数怎么传、依赖怎么管、知识库怎么切分才不会把模型撑爆。别让你的 Skill“有身份证却没人派活”。