
1. 从一次重复劳动说起Claude Code Skill 到底解决什么问题如果你已经在用 Claude Code 写代码大概率经历过这样的场景每次让 Claude 审查代码都要重新描述一遍帮我看看有没有安全问题、命名是否规范、有没有重复逻辑每次整理文档都要把格式要求从头讲一遍。提示词越写越长结果却每次都不太一样。Claude Code Skill自定义技能就是冲着这个痛点来的。简单说它是一份写在SKILL.md里的标准作业流程把一段固定的提示词、一套固定的执行步骤固化下来之后你只需要输入一个斜杠命令比如/reviewClaude 就会按照预设流程走一遍。它适合谁适合那些有重复性工作流、又希望团队里每个人跑出来的结果都一致的开发者。我把它理解成手机里的快捷指令平时你和 Claude 聊天是自由对话而 Skill 是提前编排好的动作序列。区别在于Skill 不只是省打字更重要的是结果可预期——同一套流程今天跑和下周跑输出结构基本一致。Claude Code 的 Skill 有三个来源内置 Skill开箱即用比如/review、/security-review、/init、自定义 Skill你自己写在~/.claude/skills/或项目里的.claude/skills/、插件 Skill通过/plugin install安装别人分享的。三者调用方式完全一样都是斜杠命令。本文重点讲自定义 Skill 的落地路径从SKILL.md结构、目录配置到创建、调用、验证生效的完整动作最后说明怎么通过 TaoToken 统一 Key 和 API 通道来接入模型调用。2. 前置准备TaoToken 统一 Key 与 API 通道接入 Claude Code在写 Skill 之前得先保证 Claude Code 能正常调用模型。很多团队的做法是每个人各自申请 Key、各自配环境变量结果 Key 散落各处换人就得重新配。更省事的做法是用 TaoToken 做统一入口一个 Key、一个 Base URL团队里所有人共用同一套通道模型切换也在这一层完成。TaoToken 在这里扮演的是统一 API 网关的角色——它对外暴露兼容 Anthropic 的接口Claude Code 只要把 Base URL 指向它就能正常发请求。你不需要改动 Claude Code 本身的任何逻辑只改环境变量。先拿到 Key。打开控制台创建 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建后复制那串以sk-开头的 Key只显示一次记得存好。接着配置 Claude Code 的环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量指向 TaoToken 的 API 地址# 写入 shell 配置macOS/Linux 用 ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 # 让配置立即生效 source ~/.zshrcWindows 用户在 PowerShell 里这样设$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN sk-你的TaoToken密钥注意 Base URL 结尾不要多加/v1Claude Code 会自己拼接路径多写反而会 404。配好之后启动claude随便问一句你好能正常回复就说明通道通了。这一步是整个 Skill 体系的地基——Skill 再优雅模型调不通都是空谈。如果你更习惯用配置文件而不是环境变量Claude Code 也支持在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 } }这种写法的好处是配置跟着用户目录走换终端、换 IDE 插件都生效。团队协作时把这段配置写进内部文档新人 clone 项目后照着填 Key 就行不用再解释这个 Key 从哪来、填到哪。3. 可复制配置SKILL.md 结构、目录布局与 settings 片段这一节是全文的核心给你能直接抄的模板。先看目录布局。自定义 Skill 有两个存放位置级别目录生效范围全局~/.claude/skills/所有项目都能用项目级项目根目录.claude/skills/只有当前项目能用名称冲突时项目级优先。团队专属的工作流建议放项目级跟着 Git 走同事 clone 下来就有个人常用的小工具放全局。每个 Skill 是一个独立文件夹文件夹名用小写字母加连字符里面放一个SKILL.md.claude/skills/ └── api-review/ └── SKILL.mdSKILL.md由两部分组成YAML frontmatter元信息和 Markdown body执行步骤。下面是一个可以直接复制的模板功能是审查当前分支的 API 接口改动--- name: api-review description: This skill should be used when the user asks to 审查接口改动 or 检查 API 兼容性. 用于检查当前分支相对主分支的接口变更是否破坏兼容性。 version: 1.0.0 allowed-tools: Read, Grep, Bash(git:*) argument-hint: [base-branch] --- # API 兼容性审查 ## 执行步骤 1. 运行 git diff --name-only main...HEAD 获取本次改动的文件列表 2. 筛选出涉及接口定义的文件如 *.proto、*controller*、*router* 3. 对每个文件用 git diff main...HEAD -- file 查看具体改动 4. 逐条判断以下破坏性变更 - 删除或重命名已有字段 - 修改字段类型 - 将可选字段改为必填 - 修改接口路径或 HTTP 方法 5. 输出一份 Markdown 报告包含变更文件、破坏性变更清单、建议的兼容方案 ## 输出格式 | 文件 | 变更类型 | 是否破坏兼容 | 建议 | |------|----------|--------------|------|frontmatter 里几个字段值得说清楚。name是调用名必须小写加连字符description最关键它同时承担两个职责——斜杠菜单里展示给用户看以及 Claude 判断什么时候该自动触发这个 Skill。所以 description 要用第三人称写触发条件比如 This skill should be used when the user asks to...而不是干巴巴地写接口审查工具。allowed-tools限定这个 Skill 能用哪些工具写Bash(git:*)表示只允许执行 git 相关命令这是一种安全约束。argument-hint是参数提示调用时会显示。除了SKILL.md你还可以在 Skill 文件夹里放脚本、模板等辅助文件Claude 执行时会按需读取。比如放一个scripts/check.py在 body 里写运行python scripts/check.py路径是相对 Skill 目录的。如果你想让 Skill 只在特定场景自动触发、不出现在斜杠菜单里把user-invocable设为false--- name: auto-format description: This skill should be used when the user asks to 格式化文档 or 统一格式. user-invocable: false ---这样它只能靠 Claude 的意图匹配触发适合那种不需要用户主动想起、但该用时会自动生效的流程。4. 验证请求与成功结果创建、调用、确认 Skill 生效配置写完得验证它真的生效。整个过程分三步创建、调用、确认。第一步创建。在项目根目录建目录和文件mkdir -p .claude/skills/api-review # 然后把上面的 SKILL.md 内容写进去保存即生效Claude Code 会自动扫描这两个 skills 目录支持热重载不需要重启。这是很多人踩过的坑——以为要重启其实不用。第二步确认被识别。启动 Claude Code输入/skills查看完整列表应该能看到api-review。或者输入/触发斜杠菜单往下翻也能找到。如果没出现先检查文件夹名和name字段是否一致、是否都是小写连字符。第三步调用。手动触发直接输入命令/api-review main这里main是传给argument-hint的参数表示以 main 分支为基准。Claude 会按 body 里的步骤执行先跑git diff再筛选文件再逐条判断最后输出报告。你会看到它一步步调用工具、读取 diff、生成表格。自动触发则用自然语言帮我审查一下这次接口改动有没有破坏兼容性Claude 会把这句话和api-review的 description 做匹配匹配上就自动启动流程。注意这是基于语言理解的判断不是关键词精确匹配所以偶尔会匹配不上或误触发。如果你确定要用某个 Skill手动输入斜杠命令更可靠。验证成功的标志输出里出现了你定义的表格结构、步骤顺序和报告格式。如果 Claude 只是泛泛地聊了几句、没按步骤走说明 Skill 没被正确加载回到第二步排查。再演示一个更贴近日常的例子——文档格式化 Skill。假设你经常要整理 Markdown 文档的标题层级和列表缩进可以写一个doc-format--- name: doc-format description: This skill should be used when the user asks to 整理文档格式 or 统一标题层级. allowed-tools: Read, Write, Edit --- # 文档格式整理 1. 读取用户指定的 Markdown 文件 2. 检查标题层级是否跳级如从 ## 直接到 #### 3. 检查列表缩进是否统一为 2 空格 4. 检查代码块是否都标注了语言 5. 输出问题清单询问用户是否自动修复调用/doc-format README.mdClaude 就会按这套流程检查并给出清单。这类检查 报告 可选修复的模式是自定义 Skill 最常见的形态。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuthSkill 本身不复杂但接入环节的报错经常让人卡住。下面按真实遇到的错误逐条排查。401 Unauthorized。最常见。原因通常是 Key 没配对或没生效。先确认ANTHROPIC_AUTH_TOKEN的值是不是完整的sk-开头字符串有没有多余空格或换行。再确认这个变量在当前终端里真的存在echo $ANTHROPIC_AUTH_TOKEN如果输出为空说明 shell 配置没 source或者你改的是~/.zshrc但当前用的是 bash。还有一种情况是 Key 被复制时带了引号比如sk-xxx连引号一起粘进去了去掉引号即可。local proxy failed / connection refused。这个报错说明 Claude Code 尝试连的地址不对。检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/结尾多了斜杠或者https://taotoken.net/api/v1多了版本号。正确写法就是https://taotoken.net/api不带尾斜杠、不带/v1。另外确认本机网络能正常访问该域名公司内网如果有出口限制需要让网络管理员放行。reading choices / 响应解析失败。这类报错通常出现在返回体格式不符合预期时。可能是 Base URL 指错了端点把 Anthropic 格式的请求发到了 OpenAI 格式的接口上。确认你用的是 TaoToken 的 Anthropic 兼容端点而不是其他协议的地址。如果最近改过配置回退到上一版能用的配置对比一下。OAuth 相关报错。如果你之前用官方账号登录过 Claude Code本地可能残留了 OAuth 凭证和现在的 Token 认证冲突。清理掉旧的登录状态确保走的是ANTHROPIC_AUTH_TOKEN这条路径。检查~/.claude/下有没有遗留的凭证文件必要时备份后移除。Skill 不生效但模型正常。如果对话正常、就是斜杠命令没反应问题在 Skill 本身。检查三点文件夹名和name字段是否一致SKILL.md的 frontmatter 是否用---正确包裹文件是否放在了.claude/skills/或~/.claude/skills/下而不是项目根目录随便一个地方。用/skills命令确认列表里有没有它。Codex / Cline 场景的三件套。如果你同时在用 Codex 或 Cline 这类工具配置逻辑是一样的都要写全三件套Base URLhttps://taotoken.net/api、Keysk-开头、Model ID比如claude-sonnet-4-5之类按你实际要用的模型填。少任何一件都会报错。Codex 的auth.json里对应字段是OPENAI_BASE_URL和OPENAI_API_KEYCline 的 MCP 配置则在mcpServers里填baseUrl和apiKey。三件套对齐了通道就通了。排查时有个通用思路先确认模型通道通不通随便问一句再确认 Skill 加载没加载/skills最后确认触发方式对不对手动 vs 自动。三层分开查比一股脑改配置高效得多。6. 把 Skill 沉淀成团队能力从个人技巧到可复用工作流写到这里你已经能独立创建、调用、验证一个自定义 Skill 了。但真正让 Skill 产生价值的是把它变成团队资产。我的建议是凡是每次都要重新解释一遍的流程都值得写成 Skill。比如代码提交前的检查清单、接口变更的兼容性审查、文档格式的统一、发布前的配置核对。这些流程的共同点是步骤固定、判断标准明确、结果需要一致。把它们写进.claude/skills/并提交到 Git同事 clone 下来就能用新人不用再问我们团队的审查标准是什么。一个实用的组织方式是按职责分文件夹.claude/skills/review/、.claude/skills/docs/、.claude/skills/release/每个下面一个SKILL.md。description 写清楚触发条件让自动触发也能命中。团队里谁发现了一个好用的流程就提个 PR 加一个 Skill慢慢就攒出一套专属的技能库。如果你想把模型调用也统一管理避免每个人的 Key 散落各处用 TaoToken 做统一入口是个省心的选择。一个 Key、一个 Base URL团队共用模型切换在这一层完成Skill 只管流程、不管通道。需要长期跑编码任务或 Agent 工作流的可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite想先验证模型对话效果的直接进模型对话页试https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档在这里配置细节都能查到https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后留一个实操建议先别急着写复杂的 Skill。挑一个你本周重复了三次以上的操作用最简单的SKILL.md把它固化下来跑通一次再逐步加参数、加脚本、加约束。Skill 的价值不在写得多漂亮而在于它真的替你省下了重复解释的时间。