1. 为什么你的 WorkBuddy 技能总是加载失败很多人第一次给 WorkBuddy 写技能都会经历同一个场景文件夹建好了脚本也写完了结果在对话里 它AI 同事要么装没看见要么回一句“我没有这个能力”。问题几乎都出在同一个地方——SKILL.md没写对或者写了但没被正确加载。SKILL.md是 WorkBuddy 技能的入口文件相当于一份写给模型看的 SOP什么场景该触发、按什么步骤执行、调用哪些脚本、产出什么格式全写在这里。它不参与真正的计算但决定了模型“认不认这个技能”。你可以把它理解成新员工入职时拿到的那本操作手册——手册写得含糊员工自然不知道什么时候该干什么。这篇聚焦两件事一是给你一份可以直接复制、改改就能用的SKILL.md配置骨架二是把技能从“文件存在”到“提示词真正生效”的验证动作走一遍。中间会顺带把 TaoToken 的统一 Key 接进 WorkBuddy 的settings.json这样技能里涉及模型调用的部分不用再单独配一套凭证。适合已经装好 WorkBuddy、准备写第一个自定义技能的开发者也适合技能写了但一直不生效、想排查问题的人。2. 前置准备TaoToken 统一 Key 与 WorkBuddy 接入在写SKILL.md之前先把模型通道打通。WorkBuddy 的技能在执行阶段经常需要调用模型做意图判断或内容生成如果每个技能各自配 Key管理起来会很乱。用 TaoToken 的好处是一个 Key 覆盖多种模型技能里只引用环境变量换模型不用改技能文件。2.1 获取 API Key登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。建议按用途命名比如workbuddy-skills方便后面区分。创建后立刻复制保存页面刷新后就看不到完整 Key 了。控制台入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite2.2 写入 settings.jsonWorkBuddy 的模型配置集中在settings.json。找到你的配置目录不同安装方式路径不同通常在用户目录下的.workbuddy或应用数据目录编辑或新建这个文件。下面是一份可直接套用的骨架把YOUR_TAOTOKEN_KEY换成上一步复制的 Key{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: YOUR_TAOTOKEN_KEY, defaultModel: claude-sonnet-4-5, timeoutMs: 60000 }, skills: { enabled: true, directories: [ ./skills, ~/.workbuddy/skills ], autoMatch: true } }几个参数说明一下。baseUrl固定填https://taotoken.net/api注意不要带末尾斜杠也不要加 UTM 参数否则部分客户端会拼接出错误路径。defaultModel按你实际订阅的模型填技能里如果没单独指定模型就走这个默认值。skills.directories是技能搜索路径WorkBuddy 会扫描这些目录下的子文件夹每个含SKILL.md的文件夹视为一个技能。autoMatch打开后支持隐式触发关掉就只能靠 显式召唤。注意apiKey直接写明文只适合本地开发。如果配置要进版本库或多人共享改成读环境变量比如apiKey: ${TAOTOKEN_API_KEY}然后在系统环境变量里设置。2.3 验证通道是否通配置写完先别急着写技能用一条最小请求确认通道没问题。可以用 curl 直接打curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字通了}] }返回里能看到choices[0].message.content是“通了”说明 Key 和 baseUrl 都对。这一步能省掉后面大量“到底是技能写错还是通道不通”的扯皮。如果这里就报 401先回去检查 Key 有没有复制全、有没有多余空格。3. SKILL.md 配置骨架可直接复制的结构现在进入正题。一个能被正确加载的SKILL.md结构上分两大块YAML frontmatter元信息模型靠它做匹配和正文执行说明模型靠它干活。很多人只写正文不写 frontmatter结果技能永远匹配不上这是最常见的坑。3.1 目录结构先看一个完整技能的目录长什么样skills/ └── weekly-report/ ├── SKILL.md # 入口必须有 ├── scripts/ │ └── build_report.py └── resources/ └── template.mdSKILL.md必须在技能文件夹根目录文件名大小写敏感写成skill.md或Skill.MD都可能加载失败。脚本和资源放子目录在SKILL.md里用相对路径引用。3.2 frontmatter 骨架frontmatter 用---包起来放在文件最顶部中间不能有空行或注释。下面这份骨架覆盖了触发匹配需要的核心字段--- name: weekly-report description: 根据销售数据 CSV 生成结构化周报输出 Markdown 文件 version: 1.0.0 triggers: - 生成周报 - 写周报 - weekly report - 汇总本周销售 tools: - read_file - run_script - write_file entry: scripts/build_report.py resources: - resources/template.md ---逐字段说。name是技能唯一标识建议用英文短横线命名和文件夹名保持一致避免中文和空格。description最关键模型做隐式匹配时主要看这句要写清“做什么 输入什么 输出什么”别写成“一个很有用的技能”这种废话。triggers是触发词列表用户话里命中任意一个技能就有机会被选中中英文都写上覆盖更全。tools声明这个技能会用到哪些工具WorkBuddy 加载时会做权限校验没声明的工具在技能里调用会被拦。entry指向主脚本纯提示词技能可以不写。resources列出引用的附加文件。3.3 正文骨架frontmatter 下面是正文用自然语言写执行步骤。模型读这段来决定怎么干活所以步骤要具体、有顺序、有边界。骨架如下## 适用场景 当用户要求生成周报、汇总销售数据时使用本技能。 ## 执行步骤 1. 读取用户指定的 CSV 文件确认包含 date、product、amount 三列。 2. 调用 scripts/build_report.py传入 CSV 路径和 resources/template.md。 3. 脚本按模板生成 Markdown写入工作区 report-{日期}.md。 4. 返回生成的文件路径和一行摘要。 ## 约束 - 数据缺失时不要编造直接报告缺哪一列。 - 输出语言跟随用户输入语言。 - 单次处理不超过 5000 行超出提示用户分批。正文里“执行步骤”是核心写成编号列表每步一个动作。模型对有序步骤的遵循度明显高于大段描述。“约束”部分用来兜底把你不希望它做的事写清楚比如禁止编造数据、限制处理规模这些能显著减少跑偏。3.4 纯提示词技能的简化骨架不是所有技能都需要脚本。如果只是把一套固定的提示词工作流固化下来SKILL.md可以更轻--- name: code-review description: 对用户提供的代码片段做审查输出问题清单和改进建议 version: 1.0.0 triggers: - 审查代码 - code review - 帮我看看这段代码 tools: [] ---正文直接写审查维度和输出格式即可。tools留空数组表示不调用外部工具。这种技能加载快、依赖少适合把团队统一的评审标准沉淀下来。4. 验证技能加载与提示词生效文件写完不等于生效。下面这套验证动作按顺序走一遍能定位绝大多数问题。4.1 确认技能被扫描到重启 WorkBuddy让它重新扫描技能目录。然后在对话里输入一个查看技能列表的指令不同版本指令略有差异常见的是/skills或直接问“你有哪些技能”。如果列表里没有你的技能问题在加载阶段跟提示词无关。检查三件事settings.json里skills.directories路径对不对、SKILL.md文件名和位置对不对、frontmatter 的---有没有闭合。4.2 显式触发测试用 显式召唤排除自动匹配的干扰weekly-report 用这份数据生成周报/workspace/sales.csv如果技能被触发你会看到它开始读文件、跑脚本。如果没反应说明name字段和 的名称对不上或者 frontmatter 解析失败。frontmatter 解析失败时很多客户端会静默跳过不报错所以这一步要仔细。4.3 隐式触发测试显式通过后测自动匹配。直接说一句包含触发词的话不带 帮我把本周销售数据汇总成周报观察模型是否自动选中了weekly-report。如果选错或没选回去改description和triggers——把描述写得更具体触发词加得更贴近真实说法。隐式匹配本质是语义相似度描述越准越稳。4.4 验证提示词真正生效技能被触发不代表正文里的步骤被遵循。验证方法是看输出是否符合你在“约束”里定的规则。比如你写了“数据缺失时不要编造”就故意传一个缺列的 CSV看它是报告缺失还是硬编。再比如你限制了 5000 行就传个大文件看它是否提示分批。这些边界用例跑通才算提示词真正生效。提示验证阶段建议把autoMatch临时关掉只用 触发把“匹配问题”和“执行问题”分开排查效率高很多。5. 本篇常见错误排查把踩过的坑集中列一下对照着查。技能不出现九成是SKILL.md位置或文件名问题。确认它在技能文件夹根目录文件名全大写SKILL.md。另外 frontmatter 顶部不能有空行---必须成对。frontmatter 解析失败YAML 对缩进敏感用空格不用 Tab。triggers列表项前的短横线后要有一个空格。中文冒号不能当 YAML 分隔符必须用英文:。 召唤没反应name字段和文件夹名不一致或者含了大写字母和空格。统一用小写英文加短横线。自动匹配总选错description太泛。把“生成周报”改成“根据销售 CSV 生成含图表和摘要的 Markdown 周报”匹配精度会明显提升。多个技能触发词重叠时把各自的description写得更互斥。脚本调用报权限错误tools里没声明对应工具。用到run_script就加上用到read_file就加上声明和实际调用要一致。模型调用报 401 或超时回到第 2 步的 curl 测试。baseUrl带没带末尾斜杠、Key 有没有多余空格、timeoutMs是不是太短逐个排。技能执行阶段模型调用超时多半是timeoutMs设太小调到 60000 以上试试。改了 SKILL.md 不生效WorkBuddy 一般在启动时扫描技能改完要重启。部分版本支持热重载但别赌重启最稳。6. 下一步把技能接进你的工作流SKILL.md写通之后你会发现真正的价值不在单个技能而在技能之间的组合。一个“读数据”的技能输出可以喂给“生成图表”的技能再交给“写摘要”的技能串成一条自动流水线。这时候统一 Key 的优势就出来了——整条链路共用一个 TaoToken 通道不用为每个环节单独配模型凭证。如果你准备长期维护一批技能建议把模型调用统一走 Coding Plan配额和模型切换都在一个地方管技能文件里只留环境变量引用迁移和共享都省事模型对话体验https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite下一篇会讲技能的安装与管理包括从市场一键装、启用停用、更新卸载以及“装不上”时的排查路径。在那之前先把这篇的骨架复制一份改成一个你自己高频重复的任务跑通“写 SKILL.md → 加载 → 显式触发 → 隐式触发 → 边界验证”这条完整链路。同一件事你打算做第三次以上就值得把它变成技能——现在就可以开始。
唤醒你的AI同事：WorkBuddy从零上手 017：SKILL.md 技能配置骨架与验证
1. 为什么你的 WorkBuddy 技能总是加载失败很多人第一次给 WorkBuddy 写技能都会经历同一个场景文件夹建好了脚本也写完了结果在对话里 它AI 同事要么装没看见要么回一句“我没有这个能力”。问题几乎都出在同一个地方——SKILL.md没写对或者写了但没被正确加载。SKILL.md是 WorkBuddy 技能的入口文件相当于一份写给模型看的 SOP什么场景该触发、按什么步骤执行、调用哪些脚本、产出什么格式全写在这里。它不参与真正的计算但决定了模型“认不认这个技能”。你可以把它理解成新员工入职时拿到的那本操作手册——手册写得含糊员工自然不知道什么时候该干什么。这篇聚焦两件事一是给你一份可以直接复制、改改就能用的SKILL.md配置骨架二是把技能从“文件存在”到“提示词真正生效”的验证动作走一遍。中间会顺带把 TaoToken 的统一 Key 接进 WorkBuddy 的settings.json这样技能里涉及模型调用的部分不用再单独配一套凭证。适合已经装好 WorkBuddy、准备写第一个自定义技能的开发者也适合技能写了但一直不生效、想排查问题的人。2. 前置准备TaoToken 统一 Key 与 WorkBuddy 接入在写SKILL.md之前先把模型通道打通。WorkBuddy 的技能在执行阶段经常需要调用模型做意图判断或内容生成如果每个技能各自配 Key管理起来会很乱。用 TaoToken 的好处是一个 Key 覆盖多种模型技能里只引用环境变量换模型不用改技能文件。2.1 获取 API Key登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。建议按用途命名比如workbuddy-skills方便后面区分。创建后立刻复制保存页面刷新后就看不到完整 Key 了。控制台入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite2.2 写入 settings.jsonWorkBuddy 的模型配置集中在settings.json。找到你的配置目录不同安装方式路径不同通常在用户目录下的.workbuddy或应用数据目录编辑或新建这个文件。下面是一份可直接套用的骨架把YOUR_TAOTOKEN_KEY换成上一步复制的 Key{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: YOUR_TAOTOKEN_KEY, defaultModel: claude-sonnet-4-5, timeoutMs: 60000 }, skills: { enabled: true, directories: [ ./skills, ~/.workbuddy/skills ], autoMatch: true } }几个参数说明一下。baseUrl固定填https://taotoken.net/api注意不要带末尾斜杠也不要加 UTM 参数否则部分客户端会拼接出错误路径。defaultModel按你实际订阅的模型填技能里如果没单独指定模型就走这个默认值。skills.directories是技能搜索路径WorkBuddy 会扫描这些目录下的子文件夹每个含SKILL.md的文件夹视为一个技能。autoMatch打开后支持隐式触发关掉就只能靠 显式召唤。注意apiKey直接写明文只适合本地开发。如果配置要进版本库或多人共享改成读环境变量比如apiKey: ${TAOTOKEN_API_KEY}然后在系统环境变量里设置。2.3 验证通道是否通配置写完先别急着写技能用一条最小请求确认通道没问题。可以用 curl 直接打curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字通了}] }返回里能看到choices[0].message.content是“通了”说明 Key 和 baseUrl 都对。这一步能省掉后面大量“到底是技能写错还是通道不通”的扯皮。如果这里就报 401先回去检查 Key 有没有复制全、有没有多余空格。3. SKILL.md 配置骨架可直接复制的结构现在进入正题。一个能被正确加载的SKILL.md结构上分两大块YAML frontmatter元信息模型靠它做匹配和正文执行说明模型靠它干活。很多人只写正文不写 frontmatter结果技能永远匹配不上这是最常见的坑。3.1 目录结构先看一个完整技能的目录长什么样skills/ └── weekly-report/ ├── SKILL.md # 入口必须有 ├── scripts/ │ └── build_report.py └── resources/ └── template.mdSKILL.md必须在技能文件夹根目录文件名大小写敏感写成skill.md或Skill.MD都可能加载失败。脚本和资源放子目录在SKILL.md里用相对路径引用。3.2 frontmatter 骨架frontmatter 用---包起来放在文件最顶部中间不能有空行或注释。下面这份骨架覆盖了触发匹配需要的核心字段--- name: weekly-report description: 根据销售数据 CSV 生成结构化周报输出 Markdown 文件 version: 1.0.0 triggers: - 生成周报 - 写周报 - weekly report - 汇总本周销售 tools: - read_file - run_script - write_file entry: scripts/build_report.py resources: - resources/template.md ---逐字段说。name是技能唯一标识建议用英文短横线命名和文件夹名保持一致避免中文和空格。description最关键模型做隐式匹配时主要看这句要写清“做什么 输入什么 输出什么”别写成“一个很有用的技能”这种废话。triggers是触发词列表用户话里命中任意一个技能就有机会被选中中英文都写上覆盖更全。tools声明这个技能会用到哪些工具WorkBuddy 加载时会做权限校验没声明的工具在技能里调用会被拦。entry指向主脚本纯提示词技能可以不写。resources列出引用的附加文件。3.3 正文骨架frontmatter 下面是正文用自然语言写执行步骤。模型读这段来决定怎么干活所以步骤要具体、有顺序、有边界。骨架如下## 适用场景 当用户要求生成周报、汇总销售数据时使用本技能。 ## 执行步骤 1. 读取用户指定的 CSV 文件确认包含 date、product、amount 三列。 2. 调用 scripts/build_report.py传入 CSV 路径和 resources/template.md。 3. 脚本按模板生成 Markdown写入工作区 report-{日期}.md。 4. 返回生成的文件路径和一行摘要。 ## 约束 - 数据缺失时不要编造直接报告缺哪一列。 - 输出语言跟随用户输入语言。 - 单次处理不超过 5000 行超出提示用户分批。正文里“执行步骤”是核心写成编号列表每步一个动作。模型对有序步骤的遵循度明显高于大段描述。“约束”部分用来兜底把你不希望它做的事写清楚比如禁止编造数据、限制处理规模这些能显著减少跑偏。3.4 纯提示词技能的简化骨架不是所有技能都需要脚本。如果只是把一套固定的提示词工作流固化下来SKILL.md可以更轻--- name: code-review description: 对用户提供的代码片段做审查输出问题清单和改进建议 version: 1.0.0 triggers: - 审查代码 - code review - 帮我看看这段代码 tools: [] ---正文直接写审查维度和输出格式即可。tools留空数组表示不调用外部工具。这种技能加载快、依赖少适合把团队统一的评审标准沉淀下来。4. 验证技能加载与提示词生效文件写完不等于生效。下面这套验证动作按顺序走一遍能定位绝大多数问题。4.1 确认技能被扫描到重启 WorkBuddy让它重新扫描技能目录。然后在对话里输入一个查看技能列表的指令不同版本指令略有差异常见的是/skills或直接问“你有哪些技能”。如果列表里没有你的技能问题在加载阶段跟提示词无关。检查三件事settings.json里skills.directories路径对不对、SKILL.md文件名和位置对不对、frontmatter 的---有没有闭合。4.2 显式触发测试用 显式召唤排除自动匹配的干扰weekly-report 用这份数据生成周报/workspace/sales.csv如果技能被触发你会看到它开始读文件、跑脚本。如果没反应说明name字段和 的名称对不上或者 frontmatter 解析失败。frontmatter 解析失败时很多客户端会静默跳过不报错所以这一步要仔细。4.3 隐式触发测试显式通过后测自动匹配。直接说一句包含触发词的话不带 帮我把本周销售数据汇总成周报观察模型是否自动选中了weekly-report。如果选错或没选回去改description和triggers——把描述写得更具体触发词加得更贴近真实说法。隐式匹配本质是语义相似度描述越准越稳。4.4 验证提示词真正生效技能被触发不代表正文里的步骤被遵循。验证方法是看输出是否符合你在“约束”里定的规则。比如你写了“数据缺失时不要编造”就故意传一个缺列的 CSV看它是报告缺失还是硬编。再比如你限制了 5000 行就传个大文件看它是否提示分批。这些边界用例跑通才算提示词真正生效。提示验证阶段建议把autoMatch临时关掉只用 触发把“匹配问题”和“执行问题”分开排查效率高很多。5. 本篇常见错误排查把踩过的坑集中列一下对照着查。技能不出现九成是SKILL.md位置或文件名问题。确认它在技能文件夹根目录文件名全大写SKILL.md。另外 frontmatter 顶部不能有空行---必须成对。frontmatter 解析失败YAML 对缩进敏感用空格不用 Tab。triggers列表项前的短横线后要有一个空格。中文冒号不能当 YAML 分隔符必须用英文:。 召唤没反应name字段和文件夹名不一致或者含了大写字母和空格。统一用小写英文加短横线。自动匹配总选错description太泛。把“生成周报”改成“根据销售 CSV 生成含图表和摘要的 Markdown 周报”匹配精度会明显提升。多个技能触发词重叠时把各自的description写得更互斥。脚本调用报权限错误tools里没声明对应工具。用到run_script就加上用到read_file就加上声明和实际调用要一致。模型调用报 401 或超时回到第 2 步的 curl 测试。baseUrl带没带末尾斜杠、Key 有没有多余空格、timeoutMs是不是太短逐个排。技能执行阶段模型调用超时多半是timeoutMs设太小调到 60000 以上试试。改了 SKILL.md 不生效WorkBuddy 一般在启动时扫描技能改完要重启。部分版本支持热重载但别赌重启最稳。6. 下一步把技能接进你的工作流SKILL.md写通之后你会发现真正的价值不在单个技能而在技能之间的组合。一个“读数据”的技能输出可以喂给“生成图表”的技能再交给“写摘要”的技能串成一条自动流水线。这时候统一 Key 的优势就出来了——整条链路共用一个 TaoToken 通道不用为每个环节单独配模型凭证。如果你准备长期维护一批技能建议把模型调用统一走 Coding Plan配额和模型切换都在一个地方管技能文件里只留环境变量引用迁移和共享都省事模型对话体验https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite下一篇会讲技能的安装与管理包括从市场一键装、启用停用、更新卸载以及“装不上”时的排查路径。在那之前先把这篇的骨架复制一份改成一个你自己高频重复的任务跑通“写 SKILL.md → 加载 → 显式触发 → 隐式触发 → 边界验证”这条完整链路。同一件事你打算做第三次以上就值得把它变成技能——现在就可以开始。
