1. 先搞清楚 skill-creator 和 SKILL.md 到底什么关系很多人第一次接触 Claude 技能创建器skill-creator时会以为它是一个需要安装的软件或者一个在线服务。其实不是。skill-creator 本身就是一个技能只不过它的特殊之处在于它是用来创建其他技能的技能。你可以把它理解成一个“元技能”——它的 SKILL.md 里写的不是“怎么帮用户做某件事”而是“怎么帮用户创建一个能做某件事的技能”。那 SKILL.md 又是什么它是每个技能的核心文件放在技能文件夹的根目录下文件名固定为 SKILL.md。这个文件分两部分头部是 YAML 格式的元数据必须包含 name 和 description 两个字段下面是 Markdown 格式的正文写清楚这个技能的工作流程、输出格式、注意事项。Claude 在运行时会先读取所有可用技能的 name 和 description判断当前任务该不该调用某个技能。如果判断要调用才会把那个技能的 SKILL.md 正文加载进上下文。所以 skill-creator 和 SKILL.md 的关系可以这样理解skill-creator 是一个“教你怎么写 SKILL.md”的技能而 SKILL.md 是你最终要产出的东西。你不需要把 skill-creator 的完整目录结构agents/、eval-viewer/、scripts/ 那一大堆全部搬到自己项目里那些是 Anthropic 官方用来做质量保证的工业级工具链。对于本地简要版落地你只需要关心两件事SKILL.md 的字段怎么写以及技能目录结构怎么摆。我试过把官方 skill-creator 的完整仓库 clone 下来光是 SKILL.md 就有 33KB、接近 500 行指令viewer.html 有 44KB整个评估系统跑一轮要启动多个子代理、生成 benchmark.json、开浏览器查看器。对于只是想快速理解 skill-creator 与 SKILL.md 关系的开发者来说这套流程太重了。本地简要版的目标是用最少的文件把 SKILL.md 的骨架搭起来然后用 TaoToken 统一 Key 跑通一次技能加载验证确认你的技能能被正确识别和触发。适合谁看这篇如果你已经知道 Claude 技能是什么但还没动手写过 SKILL.md或者你写了一个 SKILL.md 但不确定格式对不对、能不能被加载又或者你想在本地快速验证一个技能想法不想折腾完整的评估流水线——那这篇就是给你写的。接下来我会从零开始给出可复制的 config.toml 和 settings.json 骨架然后用 TaoToken 的 API 通道完成一次真实的技能加载验证。2. TaoToken 前置统一 Key 与 API 通道准备在本地跑通技能加载验证你需要一个能调用 Claude 模型的通道。TaoToken 在这里的角色是提供一个统一的 API 入口让你不用分别管理多个模型的 Key 和端点。它的 API 地址是 https://taotoken.net/api你可以在控制台里创建一个 Key然后所有请求都走这个 Key。为什么本地简要版要用 TaoToken 而不是直接调官方原因很简单统一 Key 意味着你只需要维护一份凭证切换模型或者做多模型对比时不用改代码里的 endpoint 和 key。对于技能加载验证这种需要反复试错的场景少一个变量就少一类报错。具体操作步骤先打开 https://taotoken.net/api-keys 创建 API Key复制出来保存好。然后确认你要用的模型 ID比如 claude-sonnet-4-20250514 或者你账号下可用的其他 Claude 模型。这两个信息后面会写进 config.toml 和 settings.json。这里要提醒一点TaoToken 是 API 通道不是编辑器替代品。你的 SKILL.md 还是在本地用 VS Code 或者任何文本编辑器写TaoToken 只负责在验证阶段把请求发出去、把模型响应收回来。不要把这两件事混在一起。另外如果你打算长期做技能开发和迭代可以考虑 Coding Plan它适合需要反复调用模型做编码和 Agent 任务的场景。如果只是偶尔验证一下技能加载用 API Keys 按量调用就够了。接入文档在 https://taotoken.net/doc里面有完整的请求格式和参数说明遇到不确定的字段可以先查那里。准备好 Key 和模型 ID 之后下一步就是搭本地目录结构和配置文件。我会给出两个配置文件的完整内容config.toml 用来存 TaoToken 的通道信息settings.json 用来存技能加载相关的设置。这两个文件放在项目根目录下和你的技能文件夹平级。3. 可复制配置SKILL.md 骨架 config.toml settings.json这一节是整篇的核心我会把三个文件的内容全部给出来你可以直接复制到本地对应路径下。先看目录结构这是本地简要版的最小布局my-skill-project/ ├── config.toml ├── settings.json └── skills/ └── meeting-notes/ └── SKILL.mdskills/ 目录下每个子文件夹就是一个技能文件夹名建议和 SKILL.md 里的 name 字段保持一致。SKILL.md 的骨架如下注意 YAML 头部必须用---包裹name 用小写加连字符description 要写得具体且稍微“强势”一些因为 Claude 有欠触发倾向--- name: meeting-notes description: 会议纪要生成技能。当用户提到“会议纪要”、“会议记录”、“会议总结”、“整理会议内容”、上传了会议录音转写文本、或描述了一场会议希望整理时务必使用此技能即使用户没有明确说“生成纪要”。 --- # 会议纪要生成 ## 概述 将会议内容对话描述或上传的转写文本整理为结构化的会议纪要。 ## 工作流程 ### 步骤 1获取会议信息 如果用户上传了文件读取文件内容。 如果用户口头描述提取关键信息会议主题、参与人、时间、讨论要点。 信息不足时追问但每次不超过 2 个问题。 ### 步骤 2生成纪要 按以下模板生成 Markdown 文件 # 会议纪要 - **会议主题** - **时间** - **参与人** ## 讨论要点 1. ... ## 决议事项 | 事项 | 负责人 | 截止日期 | |------|--------|----------| ## 待跟进 - ... ### 步骤 3输出 保存为 会议纪要_[主题]_[日期].md交付给用户。 ## 注意事项 - 保持客观不添加会议中没有的内容 - 如果信息模糊用“待确认”标注接下来是 config.toml放在项目根目录用来存 TaoToken 的通道配置# config.toml [provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model claude-sonnet-4-20250514 [skill] root ./skills auto_load true validate_on_start true然后是 settings.json同样放在项目根目录用来控制技能加载行为{ skill: { root: ./skills, autoLoad: true, validateOnStart: true, maxSkillBodyLines: 500, requireDescription: true }, provider: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: claude-sonnet-4-20250514 }, logging: { level: info, captureTiming: true } }三个文件都放好之后你的本地简要版骨架就搭完了。这里的关键点是config.toml 和 settings.json 里的 base_url 和 apiKey 必须一致model 字段也要和你在 TaoToken 控制台看到的模型 ID 完全匹配。如果后面验证时报 401第一个要检查的就是这两个文件里的 Key 有没有写错或者过期。另外SKILL.md 的正文建议控制在 500 行以内。如果你发现某个技能的正文快接近这个数了就把细节拆到 references/ 子目录里在 SKILL.md 里用清晰的引用告诉模型什么时候去读那个文件。这是渐进式加载的核心思路元数据始终在上下文里正文触发时才加载捆绑资源按需加载。4. 验证请求用 TaoToken 跑通一次技能加载配置文件写好了现在要验证技能能不能被正确加载。这一步我会用一个最小的 Python 脚本来发请求走 TaoToken 的 API 通道把 skills/ 目录下的 SKILL.md 元数据读出来拼进系统提示里然后发一个测试查询看模型会不会触发这个技能。先写验证脚本 verify_skill.py放在项目根目录import json import tomllib import requests from pathlib import Path # 读取配置 with open(config.toml, rb) as f: config tomllib.load(f) base_url config[provider][base_url] api_key config[provider][api_key] model config[provider][model] skill_root Path(config[skill][root]) # 收集所有技能的元数据 skills_meta [] for skill_dir in skill_root.iterdir(): if not skill_dir.is_dir(): continue skill_file skill_dir / SKILL.md if not skill_file.exists(): continue text skill_file.read_text(encodingutf-8) # 解析 YAML 头部 if text.startswith(---): parts text.split(---, 2) if len(parts) 3: header parts[1] name description for line in header.strip().splitlines(): if line.startswith(name:): name line.split(:, 1)[1].strip() elif line.startswith(description:): description line.split(:, 1)[1].strip() skills_meta.append({name: name, description: description}) print(已加载技能元数据) for s in skills_meta: print(f - {s[name]}: {s[description][:60]}...) # 构造系统提示把技能列表放进去 skill_list_text \n.join( f- {s[name]}: {s[description]} for s in skills_meta ) system_prompt f你可以使用以下技能。当用户请求匹配某个技能的描述时调用该技能。 可用技能 {skill_list_text} # 发一个应该触发 meeting-notes 的测试查询 user_query 帮我把今天的产品评审会整理成会议纪要参与人有张三、李四、王五讨论了三个议题。 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: model, max_tokens: 1024, system: system_prompt, messages: [{role: user, content: user_query}], }, timeout60, ) print(\nHTTP 状态码, resp.status_code) data resp.json() if content in data: for block in data[content]: if block.get(type) text: print(\n模型响应) print(block[text][:800]) else: print(\n完整响应, json.dumps(data, ensure_asciiFalse, indent2))运行这个脚本之前确认你已经装了 requests 和 tomllibPython 3.11 自带 tomllib。然后执行python verify_skill.py如果一切正常你会看到类似这样的输出已加载技能元数据 - meeting-notes: 会议纪要生成技能。当用户提到“会议纪要”... HTTP 状态码 200 模型响应 好的我来帮你整理这份会议纪要。 # 会议纪要 - **会议主题**产品评审会 - **时间**待确认 - **参与人**张三、李四、王五 ## 讨论要点 1. ...看到模型按照 SKILL.md 里定义的模板输出就说明技能加载验证通过了。模型识别到了 meeting-notes 这个技能的 description 和用户查询匹配于是按照技能正文里的工作流程来响应。这就是本地简要版要跑通的最小闭环。如果你想让验证更严格一点可以再加一个不应该触发的查询比如“帮我写一个斐波那契函数”看模型会不会错误地调用 meeting-notes。正常情况下它不应该触发因为 description 里没有和编程相关的关键词。这个正反测试能帮你确认 description 的边界是否清晰。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth验证过程中最容易遇到的几类报错我按实际碰到的频率排一下每个都给出排查路径。401 Unauthorized这是最常见的。原因通常是 config.toml 或 settings.json 里的 api_key 写错了、过期了、或者前后有空格。排查步骤先确认你从 https://taotoken.net/api-keys 复制出来的 Key 是完整的没有漏字符然后检查两个配置文件里的 Key 是否一致最后确认请求头里用的是x-api-key而不是Authorization: Bearer。TaoToken 的 Claude 通道用的是x-api-key加anthropic-version这两个头写错了就会 401。local proxy failed这个报错通常出现在你本地配了某个代理工具但代理没有正常启动或者端口不对。排查步骤先确认你的请求是直接发到 https://taotoken.net/api 的没有经过额外的本地转发然后检查环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个不存在的端口如果有临时 unset 掉再试。另外如果你在 settings.json 里配了 baseUrl 但末尾多了斜杠也可能导致路径拼接错误确认 baseUrl 是https://taotoken.net/api不带尾部斜杠。reading choices 相关报错这个通常出现在你用的某个客户端或 SDK 在解析响应时期望的字段和实际返回的不一致。比如你用的库期望 OpenAI 格式的choices数组但 TaoToken 的 Claude 通道返回的是 Anthropic 格式的content数组。排查步骤确认你用的 SDK 或客户端支持 Anthropic 消息格式如果不支持要么换用支持 Anthropic 格式的库要么在中间加一层格式转换。我在验证脚本里直接用的 requests 发原始请求就是为了避开这类格式适配问题。OAuth 相关报错如果你在配置里看到了 OAuth 字样说明你可能误用了某个需要 OAuth 流程的客户端配置。TaoToken 的 API Key 方式是直接在请求头里带 Key不需要走 OAuth 授权码流程。排查步骤检查你的配置文件里有没有oauth、authorization_url、token_url这类字段有的话删掉改成api_key直接配置。如果你用的是 Claude Code 或某个 IDE 插件确认它的认证方式选的是 API Key 而不是 OAuth。还有一个容易忽略的点如果你同时装了多个版本的 Python 或者多个虚拟环境tomllib可能导入失败。确认你的 Python 版本是 3.11 或以上或者用tomli作为替代。另外SKILL.md 的 YAML 头部如果---没有顶格写或者 description 里包含了未转义的特殊字符解析也会出问题。写完之后用quick_validate.py那种思路手动检查一遍有没有---包裹、name 和 description 是否都有值、正文有没有未替换的{{...}}占位符。6. 语义一致 CTA下一步该去哪里技能加载验证跑通之后你可能会想继续深入。根据你接下来的目标有几个方向可以走。如果你是想继续调试接入细节、排查请求格式或者看完整的 API 参数说明去接入文档和 API Keys 页面接入文档在 https://taotoken.net/docAPI Keys 管理在 https://taotoken.net/api-keys。这两个页面能解决大部分“请求发不出去”或者“返回格式不对”的问题。如果你是想快速验证某个模型对特定技能描述的理解能力不想写代码可以直接用模型对话页面https://taotoken.net/model-chat。把你的 SKILL.md 描述贴进去问模型“这个描述在什么情况下会触发”看它的理解和你预期的是否一致。这是一个很轻量的验证方式适合在正式写代码之前先探一下方向。如果你打算长期做技能开发需要反复调用模型做评估、迭代 description、跑多轮测试那 Coding Plan 会更合适https://taotoken.net/coding-plan。它针对编码和 Agent 类任务做了优化适合需要持续消耗 token 做迭代的场景。最后说一个我踩过的坑SKILL.md 的 description 不要写得太短也不要写得太泛。太短会导致触发率低太泛会导致误触发。一个好的 description 应该同时包含“做什么”和“什么时候用”并且覆盖用户可能的各种说法。你可以在本地用几个不同的查询反复测试看触发边界是否清晰。这个打磨过程比搭骨架更花时间但值得。