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_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的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 Compatible，Base URL 填https://taotoken.net/api；CC 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.md，Claude 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-20250514"Codex 的~/.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_KEY；curl 测试时 header 用的是x-api-key而不是Authorization: Bearer。TaoToken 的 Anthropic 兼容接口用x-api-key，这点跟 OpenAI 格式不同。
报错二：local proxy failed
Error: local proxy failed to connect to upstream这个报错说明 Claude Code 尝试连接 Base URL 但失败了。检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api，注意结尾不要多加/v1，Claude Code 会自己拼路径。如果你在 settings.json 里写的是https://taotoken.net/api/v1，就会变成/api/v1/v1/messages，直接 404。
报错三：reading choices
TypeError: 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 expired
OAuth 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 真正值钱的地方。
