1. Claude Skills 到底是什么为什么值得你花时间Claude Skills 是 Anthropic 在 2025 年 10 月正式推出的一套 Agent 扩展机制核心思路可以用一句话概括把「怎么做一件事」写成一份可复用的说明书让 Claude Code 在需要的时候自己去读、自己去执行。这份说明书的核心文件就是 SKILL.md它用 YAML 元数据加 Markdown 正文的形式描述一个技能的触发条件、执行流程、参数说明和边界处理。它能做什么举几个我实际用过的场景。你写一个pdf-extract技能Claude Code 就能从复杂 PDF 表单里抽字段填进数据库你写一个code-review技能团队新成员 clone 下来就自动获得统一的代码审查规范你写一个hot-topic技能自媒体运营者一句话就能跑完热点采集到初稿生成的流程。适合谁适合所有已经在用 Claude Code 做开发、做内容、做数据处理但每次都要重复贴一大段提示词的人。为什么说它解决了真问题以前你要让模型按固定流程干活只能把规则全塞进系统提示词Token 烧得快不说规则一多模型还容易「忘」。Skills 用的是渐进式披露启动时只加载 name 和 description 大约 100 Token真正触发时才加载 SKILL.md 主体1k~5k Token引用到脚本或参考文档时才动态加载第三级资源。这个设计让上下文窗口的利用率提升了一个量级。还有一个容易被忽略的点Skills 让知识变成了可分发的资产。以前你的提示词模板存在自己的笔记里同事要用得复制粘贴现在一个 skill 文件夹丢进.claude/skills/目录或者用npx skills add一条命令安装团队里所有人立刻拥有同样的能力。这才是它跟普通提示词工程的根本区别。但这里有个现实问题Claude Code 默认走的是 Anthropic 官方通道国内开发者在实际接入时经常遇到网络和计费上的麻烦。所以这篇教程在讲完 SKILL.md 怎么写之后会重点演示怎么把模型调用端点统一改到 TaoToken 的 API 通道用一个 Key 管住所有 Agent 的模型调用。这样你既享受 Skills 的复用能力又不用为每个项目单独配一套凭证。2. 前置准备目录结构、SKILL.md 元数据与 TaoToken 统一 Key在动手写第一个技能之前你需要先把两件事准备好一是 Claude Code 的技能目录结构二是模型调用的统一入口。先说目录。Claude Code 识别两个位置的 skills全局目录~/.claude/skills/和项目目录.claude/skills/。全局目录里的技能对你所有项目生效项目目录里的只对当前仓库生效。一个标准的 skill 文件夹长这样my-skill/ ├── SKILL.md # 核心描述文件必须 ├── scripts/ # 可执行脚本可选 │ └── fetch.py ├── references/ # 按需加载的参考文档可选 │ └── api-spec.md ├── template.md # Claude 要填写的模板可选 └── examples/ # 示例输出可选 └── sample-output.mdSKILL.md 的头部是 YAML 前置元数据两个必填字段是name和description。name只能用小写字母、数字和连字符不能用空格或特殊字符description是最关键的字段模型靠它判断什么时候该触发这个技能所以写法要「明确功能 包含触发关键词」。--- name: kua-kua-skill description: 当用户说夸夸或夸我一下时使用 echo 工具夸奖用户。适用于需要正向反馈的对话场景。 version: 1.0.0 ---正文部分建议包含这几块执行流程、质量约束、前置条件、使用示例、参数说明表、注意事项、错误与边界处理。我试过把正文控制在 500 行以内超过这个长度就该把子任务拆到references/目录里按需加载。再说模型调用入口。Claude Code 支持通过环境变量指定 API 端点。TaoToken 提供统一的 API 通道你只需要在环境变量里配置 Base URL 和 Key就能让 Claude Code 以及所有基于它的 Agent 走同一个入口。这样做的好处是你不需要为每个项目单独申请凭证也不用在多个配置文件之间来回切换。配置方式是在 shell 的 profile 文件里加两行export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Claude Code 的 settings 文件也可以写在~/.claude/settings.json里{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }Key 的获取路径是登录 TaoToken 控制台在 API Keys 页面创建一个新 Key。创建时建议按用途命名比如claude-code-dev方便后续排查问题时定位。模型 ID 方面Claude Code 默认会请求claude-sonnet-4-20250514这类标识TaoToken 通道兼容这个命名你不需要额外改模型名。这里有个细节要注意如果你同时用 Cline、CC Switch 或 Codex它们的配置字段名不一样但三件套是一样的——Base URL、Key、Model ID。Cline 在设置里填 API Provider 为 Anthropic CompatibleBase URL 填https://taotoken.net/apiCC Switch 在 provider 配置里填同样的地址Codex 的auth.json里则是base_url和api_key两个字段。统一到同一个 Key 之后你只需要在一个地方轮换凭证。3. 可复制配置从 SKILL.md 模板到 Agent 挂载这一节给你可以直接复制粘贴的配置片段。先看一个完整的 SKILL.md 模板这个模板实现的功能是「当用户要求生成周报时读取指定目录下的日志文件并汇总成 Markdown 周报」。--- name: weekly-report description: 当用户说生成周报、写周报或汇总本周工作时读取 ./logs 目录下的日志文件按项目分类汇总为 Markdown 格式周报。触发关键词周报、weekly report、本周总结。 version: 1.0.0 --- # 周报生成 Skill ## 执行流程 1. 读取 ./logs/ 目录下所有 .md 和 .txt 文件 2. 按文件修改时间过滤出本周周一到周日的内容 3. 按项目名称分组每个项目下列出完成事项、进行中事项、阻塞事项 4. 输出为 Markdown 格式保存到 ./reports/weekly-YYYY-MM-DD.md ## 质量约束 - 每条事项不超过 50 字 - 阻塞事项必须标注原因 - 没有内容的分类写无 ## 前置条件 - ./logs/ 目录必须存在 - 日志文件命名格式为 YYYY-MM-DD-项目名.md ## 参数说明 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | 起始日期 | string | 否 | 默认本周一 | | 结束日期 | string | 否 | 默认今天 | | 输出路径 | string | 否 | 默认 ./reports/ | ## 错误处理 - 如果 ./logs/ 不存在提示用户创建目录并终止 - 如果本周没有日志文件输出本周无日志记录 - 如果文件解析失败跳过该文件并在报告末尾列出把这个文件保存到~/.claude/skills/weekly-report/SKILL.mdClaude Code 下次启动时就会自动加载它的元数据。当你在对话里说「帮我生成周报」模型匹配到 description 里的触发关键词就会加载完整正文并执行。接下来是 Agent 挂载部分。如果你用的是 Claude Code 的 coding-plan 模式技能会自动被 Agent 调用。如果你用的是 Cline 这类编辑器插件需要在 MCP 配置里声明技能目录。以下是一个 Cline MCP 配置片段{ mcpServers: { claude-skills: { command: npx, args: [-y, anthropic-ai/claude-code-mcp], env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, SKILLS_DIR: /Users/yourname/.claude/skills } } } }如果你用的是 CC Switch 管理多个 provider配置里同样要写全三件套[[providers]] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514Codex 的~/.codex/auth.json写法{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }注意这三个配置文件里的 Base URL 都不带 UTM 参数保持https://taotoken.net/api干净路径即可。Key 建议用环境变量引用而不是明文写死尤其是在团队共享的仓库里。4. 验证请求确认技能触发与调用链路走通配置写完不代表能用你需要做三步验证技能是否被加载、触发是否命中、模型调用是否走了 TaoToken 通道。第一步验证技能加载。在 Claude Code 里输入/skills命令如果你的版本支持或者直接问「你有哪些可用的 skill」。如果 weekly-report 出现在列表里说明元数据加载成功。如果没有出现检查文件路径是否正确——必须是~/.claude/skills/weekly-report/SKILL.md少一层目录都不行。第二步验证触发。在对话里输入「帮我生成这周的周报」。观察模型的反应如果它开始读取./logs/目录说明 description 匹配成功如果它反问你「什么是周报」说明触发关键词没写到位回去改 description 字段。第三步验证调用链路。这一步最关键。打开一个新的终端窗口用 curl 直接测试 TaoToken 通道是否通curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }如果返回的 JSON 里有content字段且内容是「OK」说明通道正常。如果返回 401说明 Key 无效或没带上如果返回local proxy failed说明 Base URL 写错了或者网络层有问题。第四步验证端到端。在 Claude Code 里触发一次完整的技能执行然后去 TaoToken 控制台的用量页面看请求记录。如果能看到刚才那次调用的 Token 消耗说明 Claude Code 确实走了 TaoToken 通道而不是官方通道。这一步能帮你确认环境变量有没有被正确读取——有时候你在 shell 里 export 了但 Claude Code 是从 GUI 启动的读不到那个环境变量。实测下来最容易出问题的是环境变量的作用域。如果你在.zshrc里 export但用 VSCode 的集成终端启动 Claude Code有时候需要重启 VSCode 才能生效。另一个坑是 settings.json 和 shell 环境变量同时存在时优先级不确定建议只保留一处配置。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给你排查路径。以下四个是我在配置过程中实际遇到过的。报错一401 Unauthorized{type:error,error:{type:authentication_error,message:invalid x-api-key}}原因通常是 Key 没配对或者没带上。检查三处ANTHROPIC_API_KEY环境变量是否 export 成功用echo $ANTHROPIC_API_KEY验证settings.json 里的 Key 字段名是不是ANTHROPIC_API_KEYcurl 测试时 header 用的是x-api-key而不是Authorization: Bearer。TaoToken 的 Anthropic 兼容接口用x-api-key这点跟 OpenAI 格式不同。报错二local proxy failedError: local proxy failed to connect to upstream这个报错说明 Claude Code 尝试连接 Base URL 但失败了。检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api注意结尾不要多加/v1Claude Code 会自己拼路径。如果你在 settings.json 里写的是https://taotoken.net/api/v1就会变成/api/v1/v1/messages直接 404。报错三reading choicesTypeError: Cannot read properties of undefined (reading choices)这个报错通常出现在你用 OpenAI 格式的客户端去请求 Anthropic 格式的接口时。TaoToken 同时提供两种格式的端点Claude Code 要用 Anthropic 格式/api/v1/messages如果你在 Cline 里选了 OpenAI Compatible 但填了 Anthropic 的路径就会解析失败。解决办法是在 Cline 里把 Provider 改成 Anthropic Compatible或者把路径改成/api/v1/chat/completions。报错四OAuth token expiredOAuth token has expired, please re-authenticate这个报错说明 Claude Code 还在尝试用官方 OAuth 登录态而不是用你配置的 API Key。原因是环境变量没生效Claude Code 回退到了默认认证方式。解决办法是彻底退出 Claude Code确认ANTHROPIC_API_KEY在启动它的 shell 里可见然后重新启动。如果还不行删掉~/.claude/下的 OAuth 缓存文件再试。排查完这些之后建议你做一个「最小复现」用一个最简单的 SKILL.md比如只有 name 和 description正文就一句「回复 OK」确认整条链路通了再往上加复杂度。这样出问题时你能快速定位是技能本身的问题还是配置的问题。6. 把 Skills 用起来从统一 Key 到长期 Agent 工作流走到这一步你已经有了一个能跑的 SKILL.md、一套统一的 TaoToken Key 配置、一份排错清单。接下来是怎么把它变成日常习惯。我的做法是把重复超过三次的任务写成 skill。比如每周的代码审查、每月的账单汇总、每次新项目初始化时的目录结构生成。这些任务的特点是流程固定、输入输出明确、不需要创造性判断正好适合 Skills 的渐进式披露机制。对于长期跑 Agent 工作流的场景比如让 Claude Code 在后台持续处理任务队列建议用 Coding Plan 模式配合 TaoToken 通道。这样你不需要每次手动触发Agent 会按你定义的技能自动执行。配置入口在 TaoToken 控制台的 coding-plan 页面选好模型和额度之后把生成的配置片段贴到 Claude Code 的 settings 里就行。如果你只是想先验证模型对话效果可以先用模型对话页面测试一下 SKILL.md 的触发逻辑确认 description 写得够不够明确。等触发稳定了再挂到 Claude Code 里跑完整流程。最后提醒一句Skills 的权限控制很重要。不要给一个只读日志的技能写入权限也不要在 SKILL.md 里明文写 API Key。用环境变量引用用最小权限原则。你可以在 Claude Code 的权限配置里精确控制每个技能能调用哪些工具这个配置在~/.claude/settings.json的permissions字段里。整套流程跑通之后你会发现最大的变化不是「AI 更聪明了」而是「你不用每次重复交代背景了」。技能文件本身就是文档新人入职 clone 下来就能用团队规范自动落地。这才是 Skills 真正值钱的地方。