1. 为什么你的 SKILL.md 总是“激活失败”从 Anthropic Agent Skills 说起Anthropic 开源的 Agent Skills 体系核心思路其实很朴素把一段可复用的工作流写成一个带 YAML 元数据的SKILL.md放进一个独立文件夹Claude 在需要时动态加载它。它解决的是“每次都要重新粘贴一大段提示词”的问题——你写一次之后所有对话都能复用。适合谁适合那些有固定流程的开发者代码审查规范、文档生成模板、内部报告格式、数据清洗步骤这些都能沉淀成技能。但真正落地时很多人卡在同一个地方技能文件写好了Claude Code 里却调不起来或者调起来了但模型请求走的是默认通道团队里每个人还要各自配一遍 Key。我试过把技能目录、Claude Code 配置、API 通道三件事拆开看问题往往不在SKILL.md本身而在“技能加载”和“模型请求”这两条链路没有统一入口。这篇就按可复现的顺序走一遍先给出SKILL.md的目录结构模板再把它接到 Claude Code最后用统一 Key/API 通道TaoToken把凭据管理收口并做一次真实调用验证。核心检索词先摆出来Anthropic Agent Skills 是什么、SKILL.md 怎么写、Claude Code 怎么加载技能、如何用统一 API 通道管理凭据。你如果是第一次接触把它理解成“给 Claude 装插件”就行插件本体是一个文件夹插件说明书是SKILL.md。需要提前说明一点Agent Skills 的加载依赖 Claude Code 的插件机制而模型请求本身仍然要落到一个 API 端点上。很多人只改了技能目录没改请求通道结果技能能识别、请求却报 401这就是后面排障章节要重点拆的。2. TaoToken 前置把技能请求的 Base URL 和 Key 统一收口在写配置之前先把“请求往哪发、用哪个 Key”这件事定下来。Claude Code 默认会读环境变量里的 Anthropic 相关配置如果你在多台机器、多个项目里各配一份技能一多就会乱。统一通道的价值就在这里Base URL 指向https://taotoken.net/apiKey 在控制台统一生成模型 ID 显式写死三件套固定后技能加载和模型请求就不会互相打架。先拿到凭据。打开控制台页面生成 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite生成后你会得到一串以sk-开头的 Key。注意这个 Key 只显示一次复制后先存到本地密码管理器。接着确认你要用的模型 IDClaude Code 场景下通常用 Anthropic 兼容的模型名具体以文档里的模型列表为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你只是想先验证模型能不能通不想动 Claude Code可以直接在模型对话页发一条消息试水https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite这一步的意义是在把技能接进 Claude Code 之前先确认“Key Base URL Model ID”这组三件套是通的。很多人跳过这步直接改 Claude Code 配置结果报错时分不清是技能问题还是凭据问题。先通模型再通技能排障成本会低很多。关于凭据管理我的建议是不要把 Key 硬编码进SKILL.md或任何会进 Git 的文件。SKILL.md是给模型看的指令不是放密钥的地方。Key 应该放在环境变量或 Claude Code 的本地配置文件里技能文件只负责描述“怎么做”不负责“用什么身份做”。这个边界划清楚后面团队共享技能目录时才不会泄露凭据。如果你后续要做长期编码或 Agent 类任务可以考虑用 Coding Plan 把额度集中管理避免每个项目单独申请https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite前置准备到这里就够了一个 Key、一个 Base URL、一个 Model ID。接下来进入可复制配置环节。3. 可复制配置SKILL.md 目录结构 Claude Code settings 片段这一节是全文最需要你动手的部分。先给目录结构再给SKILL.md模板最后给 Claude Code 侧的配置片段。三块拼起来技能才能被加载并走统一通道。3.1 SKILL.md 目录结构模板Agent Skills 的约定是一个技能一个文件夹文件夹名建议用连字符小写和SKILL.md里的name保持一致。推荐结构如下my-skills/ ├── code-review/ │ ├── SKILL.md │ ├── examples/ │ │ └── sample-diff.md │ └── scripts/ │ └── lint_check.sh ├── doc-writer/ │ ├── SKILL.md │ └── templates/ │ └── report.md └── README.mdSKILL.md是必须的examples/、scripts/、templates/都是可选资源。Claude 在技能激活时会读取SKILL.md正文需要时再引用同目录下的资源文件。注意路径要写相对路径不要写绝对路径否则换机器就失效。3.2 SKILL.md 最小可用模板下面这个模板可以直接复制改掉name、description和正文即可--- name: code-review description: 对提交的代码 diff 做结构化审查输出问题分级、修复建议和风险提示。适用于 Pull Request 审查、提交前自检。 --- # 代码审查技能 当用户提供代码 diff 或文件路径时按以下流程执行。 ## 执行步骤 1. 读取 diff 内容识别改动范围。 2. 按严重程度分级阻断、警告、建议。 3. 每条问题给出位置、原因、修复示例。 4. 最后输出一段总体风险评估。 ## 输出格式 - 阻断问题必须修复否则不建议合并 - 警告问题建议修复可能影响可维护性 - 建议问题可选优化 ## 示例 输入一段包含未处理异常的 Python 函数 输出阻断问题 1 条未捕获异常警告问题 1 条缺少类型注解 ## 准则 - 不臆测未提供的上下文 - 修复示例必须可直接运行 - 风险提示要具体到行号YAML 前置元数据只强制两个字段name和description。description要写清楚“做什么 什么时候用”因为 Claude 是靠这段描述判断是否激活技能的。写得太模糊技能就不会被触发。3.3 Claude Code settings 配置片段Claude Code 侧需要把请求通道指向统一 Base URL。配置文件通常放在用户目录下的.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: 你的ModelID } }如果你用的是项目级配置可以放在项目根目录的.claude/settings.json但注意不要把带 Key 的文件提交到 Git建议加进.gitignore。更稳妥的做法是用环境变量注入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODEL你的ModelID三件套必须齐全Base URL、Key、Model ID。少任何一个Claude Code 启动时就会报错。配置完成后技能目录通过插件市场方式注册/plugin marketplace add /path/to/my-skills /plugin install code-reviewmy-skills这里的/path/to/my-skills换成你本地技能仓库的实际路径。注册成功后在对话里直接提技能名即可触发。4. 验证请求一次可复现的调用与成功结果配置写完不算完必须跑一次真实调用。验证分两步先验证模型通道再验证技能加载。4.1 验证模型通道用 curl 直接打一次请求确认 Base URL 和 Key 是通的curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -d { model: 你的ModelID, max_tokens: 128, messages: [ {role: user, content: 只回复两个字通了} ] }成功时你会看到类似这样的返回结构{ id: msg_xxx, type: message, role: assistant, content: [ {type: text, text: 通了} ], stop_reason: end_turn }如果返回里content数组有文本说明通道没问题。这一步过了再进 Claude Code。4.2 验证技能加载在 Claude Code 里输入/plugin list确认code-review出现在已安装列表里。然后发一条触发消息Use the code-review skill to review this diff: def divide(a, b): return a / b预期结果是 Claude 按SKILL.md里定义的分级格式输出而不是自由发挥。如果它直接给了一段泛泛的代码建议说明技能没被激活回到第 5 节排查。4.3 验证结果对照检查项期望结果失败表现模型通道返回 content 文本401 或连接失败技能注册/plugin list 可见列表为空技能激活按模板格式输出自由文本回答请求通道走统一 Base URL报 local proxy failed这张表建议你验证时逐行对照哪一行不对就定位到对应章节。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来拆。你大概率会碰到下面四类逐个说清楚原因和解法。5.1 401 Unauthorized报错长这样{type:error,error:{type:authentication_error,message:invalid x-api-key}}原因通常是三种Key 复制时带了空格、Key 已失效、请求头字段写错。Claude Code 用的是x-api-key不是Authorization: Bearer。检查你的settings.json里ANTHROPIC_API_KEY是否完整环境变量是否被其他 shell 配置覆盖。用echo $ANTHROPIC_API_KEY确认实际值。5.2 local proxy failed报错长这样API Error: local proxy failed to connect这个多半是 Base URL 写错或本地网络策略拦截。确认ANTHROPIC_BASE_URL是https://taotoken.net/api结尾不要多加/v1因为 SDK 会自己拼路径。如果你在settings.json和 shell 环境变量里都配了以 Claude Code 读取的那份为准建议只保留一处。5.3 reading choices 相关报错报错长这样TypeError: Cannot read properties of undefined (reading choices)这是典型的响应结构不匹配。choices是 OpenAI 风格的字段Anthropic 风格返回的是content。出现这个报错说明你的客户端按 OpenAI 格式解析但请求打到了 Anthropic 兼容端点。检查你用的 SDK 是不是 Anthropic SDK或者模型 ID 是否写成了 OpenAI 系列的名字。三件套里的 Model ID 必须和端点协议匹配。5.4 OAuth 相关报错报错长这样OAuth token expired or invalidClaude Code 某些版本会走 OAuth 流程如果你同时配了 API Key 和 OAuth可能冲突。解法是明确用 API Key 模式清掉本地缓存的 OAuth token重新用ANTHROPIC_API_KEY启动。如果你用的是 Claude Code 的 Anthropic 接入方式参考文档里的配置说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite5.5 技能不激活没有报错但技能就是不触发。检查description是否写得太泛比如只写“代码相关”。Claude 靠描述匹配意图描述要具体到场景。另外确认SKILL.md的 YAML 前置元数据没有语法错误name和文件夹名一致。6. 把技能目录纳入版本管理凭据留在本地技能写完之后真正让它产生复利的是版本管理。SKILL.md、examples/、scripts/这些都可以进 Git团队共享、追踪变更、回滚都方便。但 Key 和settings.json里的敏感字段必须排除在外。我的做法是技能仓库单独一个 repo.gitignore里加上.claude/settings.json和.env新成员克隆后自己填 Key。如果你要长期跑编码类 Agent 任务把额度集中到 Coding Plan 会比每个项目单独配更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite需要新 Key 或管理已有 Key走 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite最后留一个实用技巧每次改完SKILL.md先在模型对话页用一段最小输入测一次触发确认格式符合预期再提交到技能仓库。这样能避免“改了描述导致技能不激活”这类问题被带到团队里。技能系统的价值不在于写得多复杂而在于每次调用都稳定复现同一套流程。