1. 从重复提示词到可复用 SkillClaude Code 里到底在解决什么问题如果你用 Claude Code 写过一段时间代码大概率经历过这种循环每次开新项目都要把同一套流程重新讲一遍——先读哪个配置文件、按什么顺序改目录、生成完还要跑哪条校验命令。提示词越写越长但 AI 还是偶尔漏步骤。Claude Code 的 skill 机制就是把这套「口头交代」变成一份放在磁盘上的操作文档让 AI 在需要时自动读取并执行。skill 本质上是一个目录核心是里面的SKILL.md文件用 Markdown 写清楚「什么时候用、按什么步骤做、有哪些资源可调用」。它和普通提示词最大的区别是提示词是临时的、跟着对话走的skill 是持久的、跟着项目或用户走的。你写一次之后每次触发相关任务Claude Code 会自动把这份文档加载进上下文按里面的指令干活。它适合谁三类人最值得上手一是经常做同类脚手架搭建或框架移植的开发者二是团队里想把代码规范、发布流程固化成 AI 可执行步骤的技术负责人三是像我这样反复让 AI 生成周报、解析固定格式数据、按模板产出文档的人。只要一件事你会做第二遍就值得考虑写成 skill。这篇会从零走一遍完整流程先讲清楚 skill 的目录结构和SKILL.md的写法再给出可复制的配置片段然后说明怎么通过统一的 Key/API 通道完成调用侧配置最后用一个真实任务跑通验收。中间会穿插我踩过的坑尤其是触发不生效、路径写错、模型 ID 填错这几类高频问题。需要先说明一点skill 的编写和调用最终都要落到模型请求上。Claude Code 本身支持配置自定义的 API 端点所以你可以把请求统一走一个兼容 Anthropic 协议的通道这样 Key 管理、模型切换、额度查看都在一处完成不用在多个平台之间来回倒腾。下面第二节先把这个前置配置讲清楚因为后面所有验证都依赖它。2. TaoToken 前置配置Claude Code 接入统一 Key/API 通道的完整步骤在写 skill 之前得先保证 Claude Code 能正常发出请求。很多人卡在第一步装好了 Claude Code但不知道怎么让它走自己的 API 通道。这里我用 TaoToken 作为统一入口来演示它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式Claude Code 可以直接对接。先解释一下为什么要在这一步花时间。Claude Code 默认会读环境变量里的ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN如果你不配置它会尝试走官方端点而官方端点在国内网络环境下经常连不上报错通常是local proxy failed或者连接超时。把 Base URL 指向一个可用的兼容端点是让后续 skill 验证能跑通的前提。具体操作分三步。第一步去控制台创建一个 API Key。打开https://taotoken.net/console登录后在 API Keys 页面新建一个 Key复制出来。这个 Key 就是后面配置里的ANTHROPIC_AUTH_TOKEN。注意 Key 只在创建时完整显示一次记得先存到安全的地方。第二步配置环境变量。macOS 或 Linux 下编辑~/.zshrc或~/.bashrc加入两行export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你刚才复制的KeyWindows 下用 PowerShell 的话可以写进用户环境变量[Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://taotoken.net/api, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_AUTH_TOKEN, sk-你刚才复制的Key, User)改完记得重开终端或者执行source ~/.zshrc让配置生效。验证环境变量是否读到可以跑echo $ANTHROPIC_BASE_URL应该输出https://taotoken.net/api。第三步指定模型 ID。Claude Code 需要一个模型标识通常填claude-sonnet-4-20250514这类。如果你用的是 Claude Code 的配置文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这三件套——Base URL、Key、Model ID——缺一不可。我见过最常见的错误是只配了 Key 没配 Base URL结果请求还是打到默认端点报 401 或者超时也有人把 Model ID 写成了 OpenAI 的格式Claude Code 不认直接报reading choices之类的解析错误。配置完成后可以先跑一个最简单的对话测试确认通道通了再进入 skill 编写环节。如果你更习惯用命令行工具管理多个 KeyTaoToken 的 API Keys 页面支持创建多个 Key 并分别命名方便区分项目。这一步做完调用侧就准备好了接下来写 skill 才有意义。3. 可复制的 Skill 目录结构与 SKILL.md 配置片段现在进入正题怎么写一个 skill。先看目录结构。Claude Code 会在两个位置查找 skill项目级的.claude/skills/和用户级的~/.claude/skills/。项目级只对当前项目生效用户级对所有项目生效。选择哪个取决于你的复用范围——如果是公司内部通用流程放用户级如果是某个项目专属的构建步骤放项目级。一个完整的 skill 目录长这样以「生成周报」为例weekly-report/ ├── SKILL.md # 主说明什么时候触发、按什么步骤生成 ├── scripts/ │ └── parse_data.py # 解析 Excel 数据的脚本 ├── references/ │ └── company-terms.md # 公司专用术语表 └── assets/ └── template.docx # 周报模板文件SKILL.md是唯一必需的文件其余都是可选资源。Claude Code 在触发 skill 时会先读SKILL.md如果里面引用了scripts/或references/里的文件它会按需读取。这种设计的好处是主文档保持精简大块的参考资料和脚本分开存放不会一次性塞满上下文。SKILL.md的写法有固定格式开头必须有一段 YAML frontmatter声明名称和描述。描述非常关键Claude Code 就是靠它判断「当前任务要不要触发这个 skill」。写得太泛会误触发写得太窄又触发不了。下面是一个可复制的模板--- name: weekly-report description: 当用户要求生成周报、整理本周工作、汇总项目进展时使用。适用于需要从 Excel 数据源提取内容并按公司模板输出 Word 文档的场景。 --- # 周报生成 Skill ## 触发条件 当用户提到「周报」「本周总结」「工作汇报」等关键词且提供了数据文件路径时执行以下步骤。 ## 执行步骤 1. 读取用户指定的 Excel 文件调用 scripts/parse_data.py 解析数据。 2. 参考 references/company-terms.md 中的术语表统一项目名称和指标口径。 3. 按 assets/template.docx 的结构组织内容生成 Markdown 草稿。 4. 将草稿转换为 Word 文档输出到用户指定目录。 ## 注意事项 - 如果 Excel 缺少「本周完成」列提示用户补充不要自行编造。 - 项目名称必须与术语表一致遇到未收录的名称先询问。frontmatter 里的name建议用英文短横线命名和目录名保持一致description用中文写清楚触发场景越具体越好。正文部分用 Markdown 分节把步骤写成人能看懂、AI 能执行的粒度。我试过把步骤写得太抽象比如「整理数据并生成报告」结果 AI 每次执行方式都不一样后来改成「先调 parse_data.py再对照术语表最后套模板」输出就稳定多了。还有一个技巧在SKILL.md里显式写出「不要做什么」。比如上面模板里的「不要自行编造」能有效减少 AI 在数据缺失时的自由发挥。skill 不是越短越好关键步骤和边界条件都要写清楚。写完SKILL.md后把它放到对应目录。项目级的话在项目根目录建.claude/skills/weekly-report/SKILL.md用户级的话在~/.claude/skills/weekly-report/SKILL.md。放好后不需要重启 Claude Code它会在下次任务时自动扫描。4. 触发验证用一次真实任务跑通 Skill 并检查成功结果配置和文件都就位后最关键的一步是验证 skill 到底会不会被触发。很多人写完就以为成了结果用的时候发现 AI 根本没读那份文档。验证方法很简单在 Claude Code 里发起一个明确匹配description的任务然后观察它有没有按SKILL.md里的步骤走。我拿周报 skill 做验收。先准备一个测试用的 Excel 文件放在~/test/weekly.xlsx里面有几行模拟数据。然后在 Claude Code 里输入帮我根据 ~/test/weekly.xlsx 生成本周周报如果 skill 配置正确Claude Code 应该会先识别到「周报」这个触发词加载weekly-report/SKILL.md然后按步骤调用parse_data.py。你可以在输出里看到它引用了术语表、套用了模板结构。如果它只是泛泛地回了一段文字没有调用脚本说明 skill 没被触发。判断触发成功的几个信号一是输出里出现了SKILL.md中定义的步骤顺序二是它读取了references/或scripts/里的文件三是最终产物符合模板结构。我实测下来最可靠的验证方式是故意在 Excel 里留一个缺失列看它会不会按SKILL.md里写的「提示用户补充」来处理。如果它照做了说明文档被真正读进去了。如果没触发先检查三件事。第一SKILL.md的 frontmatter 格式对不对name和description之间不能有语法错误YAML 对缩进敏感。第二目录层级对不对必须是skills/技能名/SKILL.md不能直接放skills/SKILL.md。第三description里的触发词和你的实际输入是否匹配如果描述写的是「周报」你输入的是「日报」那自然不会触发。验证通过后这个 skill 就可以复用了。下次任何项目里提到周报只要目录在用户级~/.claude/skills/下Claude Code 都会自动加载。项目级的则跟着项目走适合团队共享——把.claude/skills/提交到 Git 仓库同事拉下来就能用同一套流程。这里补充一个调用侧的检查点如果 skill 触发了但执行到一半报错比如脚本调用失败或者模型请求中断先确认 API 通道是否正常。可以在 Claude Code 里跑一个不依赖 skill 的简单请求比如「解释一下这段代码」如果这个也失败那就是 Key 或 Base URL 的问题回到第二节检查三件套。如果简单请求正常、只有 skill 任务失败那问题多半在脚本路径或文件权限上。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 问题这一节把我在配置和验证过程中遇到的高频报错集中列一下方便你对照排查。这些错误大多不是 skill 本身的问题而是调用侧配置或环境导致的。401 Unauthorized最常见。原因通常是 Key 没配、Key 过期、或者 Key 和 Base URL 不匹配。检查ANTHROPIC_AUTH_TOKEN是否和你在控制台创建的一致注意不要有多余空格或换行。如果你在settings.json和 shell 环境变量里都配了以settings.json为准两处冲突时容易出问题。解决方式是只保留一处配置推荐用settings.json因为它是 Claude Code 原生读取的。local proxy failed这个报错通常出现在网络层意思是 Claude Code 尝试连接端点时失败了。先确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api注意结尾不要多加斜杠也不要写成/v1之类的路径。然后确认本机网络能正常访问该地址可以用curl https://taotoken.net/api测试连通性。如果 curl 也失败说明是网络环境问题不是配置问题。reading choices 相关报错这类错误一般出现在响应解析阶段提示模型返回格式不符合预期。根本原因往往是 Model ID 填错了比如填了 OpenAI 的gpt-4而不是 Anthropic 的模型标识。Claude Code 期望的是 Anthropic 格式的响应Model ID 必须用claude-开头的标识。检查ANTHROPIC_MODEL的值改成claude-sonnet-4-20250514这类再试。OAuth 相关报错如果你之前登录过 Claude Code 的官方账号本地可能残留了 OAuth 凭证它会优先用那套凭证而不是你的环境变量。表现是配置明明对了但请求还是走官方端点然后失败。解决方式是清理本地凭证通常在~/.claude/目录下找到认证相关的缓存文件删掉或者执行 Claude Code 的登出命令让它重新读取环境变量。Skill 不触发这个不算报错但很常见。除了前面说的 frontmatter 和目录问题还有一种情况是description写得太宽泛导致 Claude Code 判断「这个任务不需要 skill」。比如描述写成「处理各种文档任务」它可能觉得普通对话就能处理不加载 skill。把描述收窄到具体场景比如「从 Excel 提取数据生成周报」触发率会明显提高。脚本执行失败如果SKILL.md里引用了scripts/parse_data.py但执行时报「文件不存在」或「权限不足」检查脚本路径是不是相对于 skill 目录写的。Claude Code 读取资源时路径基准是 skill 目录不是项目根目录。另外确认脚本有可执行权限必要时chmod x。排查顺序建议从外到内先确认 API 通道通不通跑简单请求再确认 skill 文件结构对不对检查目录和 frontmatter最后确认触发词匹配不匹配调整 description。大部分问题在前两步就能定位。6. 把 Skill 沉淀为团队能力统一通道与长期维护建议走到这里你已经完成了一个 skill 的完整闭环配置通道、编写文档、放置目录、触发验证、排查错误。接下来值得考虑的是怎么让它长期可用而不是写完就忘。第一件事是把调用侧配置固定下来。团队协作时每个人的 Key 不同但 Base URL 和 Model ID 应该统一。可以把settings.json里的env部分做成模板Key 用占位符让每个人填自己的。这样既保证通道一致又不会把 Key 提交到仓库。TaoToken 的 API Keys 页面支持按项目创建多个 Key团队可以给每个项目分配独立 Key方便追踪用量和随时吊销。第二件事是给 skill 加版本意识。SKILL.md里的步骤会随着流程变化而调整建议在 frontmatter 里加一个version字段或者在文件顶部写一行更新日志。这样当 AI 行为不符合预期时你能快速判断是不是 skill 内容过期了。我自己的习惯是每次改完 skill 都跑一遍验收任务确认输出稳定再提交。第三件事是控制 skill 的数量和粒度。不要把所有流程塞进一个 skill也不要为每个小步骤建一个。判断标准是如果两个任务总是同时出现合并如果触发场景完全不同拆开。一个 skill 对应一类可复用的能力描述清晰、步骤独立维护起来才不累。如果你想把 skill 用在更长期的编码任务或 Agent 场景里可以考虑配合 Coding Plan 来管理调用额度这样高频触发 skill 时不用担心额度问题。模型对话入口适合快速验证单个 skill 的触发效果接入文档则能帮你确认 Base URL 和参数格式是否写对。这几个入口配合起来从调试到长期使用都能覆盖。最后说一个实际经验skill 的价值不在于写得多复杂而在于它能不能稳定复现你想要的结果。一个只有五步、但每次都能跑通的 skill比一个二十步、偶尔漏步骤的 skill 有用得多。从最简单的任务开始写跑通一个再加下一个慢慢你就会有一套自己的可复用能力库。