1. 为什么你的 WorkBuddy Skill 总是触发不了从 SKILL.md 结构说起WorkBuddy Skill 本质上是一个带SKILL.md的文件夹它是写给 AI 实例看的操作指令集不是给人看的说明文档。这个定位一旦搞反后面所有写法都会跑偏。很多人第一次写 Skill习惯性地把 SKILL.md 当成 README 来写结果就是技能装进去了、列表里也能看到但真正对话时模型压根不调用它。问题不在模型在于你把触发条件写错了地方。一个完整的 Skill 目录长这样weekly-report-generator/ ├── SKILL.md # 唯一必需文件YAML frontmatter 操作指令 ├── scripts/ # 可执行脚本确定性操作放这里 ├── references/ # AI 工作时查阅的参考文档 └── assets/ # 直接复制到产出物的资源只有SKILL.md是必须的其余三个目录按需创建。AI 加载 Skill 是分层的这个机制直接决定你该把什么写在哪一层层级内容何时加载Token 成本L1Frontmatter 的 name description始终在上下文约 100 词L2Body 操作指令正文触发后加载小于 5k 词L3scripts / references / assets按需调用无上限看明白这张表第一个大坑就清楚了触发条件必须写在description里而不是正文。等正文被加载时AI 早就做完要不要用这个 Skill的决策了。你把当用户要求写周报时使用写在正文第一行等于没写。SkillHub 技能市场目前已有 7 万多个社区技能、累计下载超 3000 万次但真正贴合自己业务的场景还是得自己动手。这篇就按从零开发到发布前自检的完整链路走一遍把七个高频坑点、一个可运行示例、以及通过 TaoToken 统一 Key 做联调验证的动作全部交付出来。适合谁想把重复对话任务封装成可复用工具的开发者以及准备往 SkillHub 提交技能的人。2. TaoToken 前置准备统一 Key 与 API 通道配置写 Skill 的过程中只要涉及调用模型做联调验证就会遇到一个现实问题不同模型、不同工具各配一套 Key管理成本高切换还容易出错。TaoToken 的思路是用一个统一 Key 打通模型对话、编码 Agent、API 调用几条通道联调阶段只维护一份凭证。先把账号和 Key 准备好。打开官网注册后进入控制台在 API Keys 页面创建一个新 Key。这个 Key 就是后面所有配置里ANTHROPIC_AUTH_TOKEN或OPENAI_API_KEY要填的值。控制台地址是 https://taotoken.net/console 创建 Key 的页面是 https://taotoken.net/api-keys 。Base URL 统一用https://taotoken.net/api注意这个地址不带任何查询参数。模型 ID 按你实际要联调的模型填比如claude-sonnet-4-5这类。三件套凑齐Base URL Key Model ID缺一个都跑不通。如果你用的是 Claude Code 这类编码工具做 Skill 脚本的调试配置走环境变量最省事export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-5配完之后可以用一条最小请求验证通道是否通curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: reply with ok}] }返回里能看到content数组和正常的stop_reason说明 Key 和通道都没问题。这一步别跳过后面 Skill 联调报错时你能快速判断是 Skill 本身的问题还是通道的问题。需要说明的是TaoToken 在这里扮演的是统一 API 通道的角色帮你把多模型调用的凭证收敛到一处方便 Skill 开发阶段的反复调试。它不替代你的编辑器也不替代 WorkBuddy 本身只是把调用模型这件事的配置成本降下来。长期做编码和 Agent 类任务的话Coding Plan 会比按量调用更划算具体可以看 https://taotoken.net/coding-plan 。3. 可复制配置SKILL.md 模板与 YAML 字段规范这一节直接给能复制粘贴的东西。先看 frontmatter 的最小标准--- name: weekly-report-generator description: Generates weekly work reports from task logs. Use when asked to write, create, or summarize weekly/work reports. allowed-tools: Read,Write,Bash ---Frontmatter 只允许五个字段name、description、license、allowed-tools、metadata。任何其他字段都会被解析器忽略甚至直接报错这是第二个高频坑——有人习惯性加version、author、tags结果技能加载失败还找不到原因。name的规范要记牢小写字母 数字 连字符不超过 64 字符不以连字符开头或结尾推荐动词开头的短语。generate-report比report好因为前者说明了动作。最关键的一条目录名必须与 name 字段完全一致。目录叫weekly-reportname 写weekly-report-generator技能列表里就是看不到它。description是触发器写法决定触发率。对比一下# 错误写法等于没写 description: 周报生成技能 # 正确写法做什么 何时触发 description: Generates weekly work reports from task logs. Use when asked to write, create, or summarize weekly/work reports.allowed-tools是白名单显式列出该 Skill 能用的工具常用值有Read、Write、Bash、WebFetch。不列出的工具不会被调用这既是安全边界也是 SkillHub 安全审查的核心检查项。安全等级 MEDIUM 以上需要人工审查EXTREME 等级不建议安装。正文部分用祈使语气写给 AI 看不是写给人看## Workflow 1. Read task log file from ./logs/week-{YYYYWW}.md 2. Extract completed tasks, blockers, and planned next steps 3. Format output using template in assets/report-template.md 4. Write final report to ./output/weekly-report-{DATE}.md ## Constraints - Title length must not exceed 60 characters - Refer to references/schema.md for field definitions不要写 You should read the task log直接写 Read task log。正文长度控制在 500 行 / 5000 Token 以内超出就拆到references/目录在正文里加一行 Refer to references/detail.md for complete specificationAI 会在需要时主动读取。三层资源的分工也要说清楚。scripts/锁死脆弱操作——任何有格式约束、长度限制、命名规则的操作都封装成脚本因为文字描述的字段不超过 60 字符每次输出可能不合规而validate_length.py保证每次结果一致。脚本执行时不会被读入上下文Token 成本为零。references/放按需知识库比如数据库 schema、API 文档但不要让 references 文件互相嵌套引用全部从 SKILL.md 直接链接。assets/放零修改直接用的内容比如 Markdown 模板、样板代码。4. 验证请求与成功结果本地联调跑通全流程配置写完得验证。先初始化目录mkdir -p ~/.workbuddy/skills/weekly-report-generator cd ~/.workbuddy/skills/weekly-report-generator touch SKILL.md mkdir scripts references assets或者直接告诉 WorkBuddy帮我创建一个叫 weekly-report-generator 的 Skill功能是……它会自动调用 skill-creator 工具初始化目录并生成 SKILL.md 草稿。顺序上有个经验先写资源再写 SKILL.md。优先把scripts/、references/、assets/里的文件做好SKILL.md 正文只负责引用它们。很多人做反了先写 SKILL.md 再写脚本导致指令和实现频繁不一致改一处忘一处。保存后在 WorkBuddy 里发送/reload-skills或重启客户端检查技能列表是否出现新条目。看不到新条目的首要原因就两个frontmatter 格式错误或目录名与 name 字段不一致。接下来做真实任务测试。用一个真实的输入触发它比如帮我生成本周的工作周报。如果 Skill 被正确调用你会看到它按 Workflow 里的步骤执行读取日志、提取内容、套模板、写输出文件。联调阶段如果 Skill 内部要调用模型就用第 2 节配好的 TaoToken 通道。把调用逻辑写进scripts/里的脚本Key 从环境变量读不要硬编码进脚本文件——硬编码的 Key 提交到 SkillHub 会被安全审查拦下。一个可运行的脚本示例# scripts/format_action_items.py import os import sys import json import urllib.request def call_model(prompt: str) - str: base_url os.environ.get(ANTHROPIC_BASE_URL, https://taotoken.net/api) token os.environ[ANTHROPIC_AUTH_TOKEN] model os.environ.get(ANTHROPIC_MODEL, claude-sonnet-4-5) payload json.dumps({ model: model, max_tokens: 512, messages: [{role: user, content: prompt}] }).encode() req urllib.request.Request( f{base_url}/v1/messages, datapayload, headers{ x-api-key: token, anthropic-version: 2023-06-01, content-type: application/json, }, ) with urllib.request.urlopen(req, timeout60) as resp: data json.loads(resp.read()) return data[content][0][text] if __name__ __main__: text sys.stdin.read() print(call_model(fExtract action items with owner and deadline:\n{text}))跑通之后你会拿到结构化的 action items 输出。这一步成功说明 Skill 的脚本层、模型通道、输出格式三件事都对齐了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth联调阶段报错集中在几类逐个对照。401 Unauthorized。九成是 Key 的问题。检查ANTHROPIC_AUTH_TOKEN有没有正确导出echo $ANTHROPIC_AUTH_TOKEN看是不是空值。如果 Key 是从控制台复制的注意别把前后空格带进去。还有一种情况是 Key 被删了或过期了去 https://taotoken.net/api-keys 重新生成一个。local proxy failed。这个报错通常出现在你本地配了额外的转发层但转发层没起来或者端口对不上。排查顺序先确认 Base URL 是不是https://taotoken.net/api有没有手滑写成别的地址再确认本地没有残留的代理环境变量干扰env | grep -i proxy看一眼有的话临时 unset 掉再试。reading choices 相关报错。这类错误一般出现在你按 OpenAI 兼容格式发请求、但响应结构对不上的时候。检查两点请求路径是不是/v1/messagesAnthropic 格式还是/v1/chat/completionsOpenAI 格式两者不能混响应解析时choices字段只在 OpenAI 格式里存在Anthropic 格式取的是content数组。脚本里解析逻辑写错就会报 reading choices 找不到。OAuth 相关报错。如果你用的是 Claude Code 这类带 OAuth 流程的工具报 OAuth 错误通常是认证方式冲突——既配了 OAuth 又配了 API Key。解决办法是明确走 Key 认证把 OAuth 相关的缓存清掉环境变量里只保留ANTHROPIC_AUTH_TOKEN这一套。技能列表看不到新条目。回到第 3 节目录名与 name 字段是否完全一致frontmatter 有没有非法字段YAML 缩进是不是用了 Tab必须用空格。触发率低。description 里没有 Use when… 的具体场景描述或者触发词和你实际说的话对不上。把三到五个真实输入例子写下来反推 description 该包含哪些触发词。排查时有个通用手法先用第 2 节的 curl 命令确认通道本身是通的再去看 Skill 脚本。通道通、脚本报错问题就在脚本通道都不通先解决 Key 和 Base URL。这样能把问题范围快速砍一半。6. 发布到 SkillHub 与持续迭代CTA 与下一步Skill 开发完成、本地验证通过后可以提交到 SkillHub 供社区使用。提交前需要通过 skill-vetter 安全审查审查核心检查项是allowed-tools的权限范围和外部网络请求声明。这也是为什么前面反复强调 Key 不要硬编码——审查会看你的脚本有没有把凭证写死在文件里。提交审查通过后技能会在市场按下载量、更新频率、用户评价排序展示。如果你的 Skill 依赖模型调用记得在文档里说明需要配置的 Base URL 和 Key 来源方便使用者快速接入。想先找现成 Skill 参考或直接复用的话LinSkills 收录了一批精选 Skills格式与 WorkBuddy Agent Skills 标准兼容下载 ZIP 解压放入~/.workbuddy/skills/目录即可激活。发布不是终点。真实使用会暴露边界情况输入为空时怎么处理、文件路径带空格时怎么处理、脚本执行失败时返回什么。每次发现问题直接改重新/reload-skills成本极低。迭代几轮之后你的 Skill 触发率和稳定性都会明显上一个台阶。如果你在联调阶段需要反复验证模型调用模型对话入口在 https://taotoken.net/models 可以直接在页面上试 prompt 效果确认没问题再写进脚本。接入文档在 https://taotoken.net/doc 里面有各语言 SDK 的配置示例。长期做编码和 Agent 类任务Coding Plan 的额度模型更适合高频调用场景地址是 https://taotoken.net/coding-plan 。把 Key 和通道一次性配好后面写多少个 Skill 都不用再折腾凭证。