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 成本 |
|---|---|---|---|
| L1 | Frontmatter 的 name + description | 始终在上下文 | 约 100 词 |
| L2 | Body 操作指令正文 | 触发后加载 | 小于 5k 词 |
| L3 | scripts / 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_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的TaoToken密钥" export ANTHROPIC_MODEL="claude-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-report，name 写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 specification"，AI 会在需要时主动读取。
三层资源的分工也要说清楚。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", data=payload, headers={ "x-api-key": token, "anthropic-version": "2023-06-01", "content-type": "application/json", }, ) with urllib.request.urlopen(req, timeout=60) as resp: data = json.loads(resp.read()) return data["content"][0]["text"] if __name__ == "__main__": text = sys.stdin.read() print(call_model(f"Extract 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/messages（Anthropic 格式）还是/v1/chat/completions（OpenAI 格式），两者不能混；响应解析时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 都不用再折腾凭证。
