1. 为什么你的 Claude Code 需要一个自定义 Skill

Claude Code 本身已经能读写文件、跑命令、查代码，但每次让它按团队规范做事，你都得重复一遍要求。比如“写接口文档要包含请求参数、返回值、错误码、调用示例”，这句话你可能一周要说十几次。Claude Code Skills 就是解决这个问题的：它把你的重复指令和最佳实践封装成一个可复用的能力包，Claude 在合适的时机自动加载并严格执行。

一个 Skill 本质上就是一个文件夹，里面必须有一个全大写的SKILL.md。这个文件分两部分：顶部 YAML 元数据负责“什么时候触发”，下面的 Markdown 正文负责“触发后怎么做”。触发靠的是description字段和用户自然语言的语义匹配，执行靠的是正文里的步骤指令。适合谁用？三类人最值得投入：一是团队 Tech Lead，想把代码规范固化下来；二是经常写重复文档、做重复检查的开发者；三是想让 Claude Code 在特定领域更“懂行”的进阶用户。

我试过把公司 Java 规范做成 Skill 之后，新同事只要在项目里问一句“帮我检查下这段代码风格”，Claude 就会自动按规范逐条比对并给出修复建议，不用再翻文档。下面从零开始，把 SKILL.md 结构设计、allowed-tools 权限配置、skill-creator 辅助生成、本地加载验证整条链路走一遍，每一步都给可复制的配置。

2. TaoToken 前置准备：让 Claude Code 稳定跑起来

在开发 Skill 之前，得先保证 Claude Code 能正常调用模型。如果你直接用官方端点遇到网络波动或额度问题，可以换成 TaoToken 的兼容接入方式。TaoToken 提供与 Anthropic 兼容的 API 端点，Claude Code 只需要改ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN两个环境变量就能接上。

先到官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册账号，然后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建好之后复制那串以sk-开头的 Key，后面配置要用。

这里要区分两个地址：官网带 UTM 参数用于注册引流，API 端点固定为https://taotoken.net/api，不要加 UTM。Claude Code 走的是 Anthropic 协议，所以 Base URL 填https://taotoken.net/api，Claude Code 会自动拼接/v1/messages路径。

配置方式有两种。第一种是临时环境变量，适合快速测试：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的Key"

第二种是写进 Claude Code 的配置文件，持久生效。Claude Code 读取~/.claude/settings.json，你可以直接编辑：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" } }

如果你用的是 Claude Code 的 OAuth 登录流程，注意 OAuth 和 API Key 是两套认证，切换时要把旧的登录态清掉，否则会出现OAuth token conflict报错。清掉之后用上面的环境变量方式重新启动即可。

模型 ID 方面，Claude Code 默认会请求claude-sonnet-4-5这类模型名，TaoToken 侧做了映射，你不需要额外指定。如果要在配置里显式写模型，可以在settings.json里加"model": "claude-sonnet-4-5"。三件套记牢：Base URL 是https://taotoken.net/api，Key 是sk-开头那串，Model ID 是claude-sonnet-4-5。

配好之后启动 Claude Code，随便问一句“你好”，能正常回复就说明接入成功。这一步没过，后面 Skill 开发都是空谈。

3. 手写 SKILL.md：目录结构与 allowed-tools 配置

Skill 的目录结构有约定，核心文件必须叫SKILL.md，全大写，放在一个 kebab-case 命名的文件夹里。以java-code-checker为例：

java-code-checker/ ├── SKILL.md # 核心指令文件，必须全大写 ├── scripts/ # 可选，辅助脚本 │ └── format.sh ├── assets/ # 可选，模板、图片等资源 └── reference/ # 可选，参考文档 └── style-guide.md

SKILL.md分两段：YAML frontmatter 和 Markdown 正文。frontmatter 里三个字段最关键：name、description、allowed-tools。name是 Skill 标识，用 kebab-case；description决定触发时机，要写具体，把用户可能说的关键词都塞进去；allowed-tools控制这个 Skill 能调用哪些工具，这是权限边界，写多了有安全风险，写少了功能跑不起来。

下面是一个可直接复制的完整模板：

--- name: java-code-checker description: 检查 Java 代码格式问题，包括命名规范、缩进、大括号位置、import 顺序。当用户提到"检查代码风格""代码审查""格式化""规范检查"时自动触发。 allowed-tools: Read, Bash, Edit --- # Java 代码格式审查专家 你是一个严格的 Java 代码审查员，负责确保代码符合《阿里巴巴Java开发手册》规范。 ## 核心规则 1. 命名规范： - 类名必须使用 PascalCase - 方法名和变量名必须使用 camelCase - 常量必须使用 UPPER_SNAKE_CASE 2. 格式规范： - 缩进必须为 4 个空格 - 大括号必须独占一行 - import 语句按字母顺序排列 ## 工作流程 当用户请求检查代码时： 1. 使用 Read 工具读取目标文件。 2. 逐行分析代码，对照上述规则进行检查。 3. 生成检查报告，分为严重问题和建议优化两类。 4. 如果发现问题，提供修复后的代码片段。 ## 输出格式 发现 N 个问题： 1. [严重] 第 X 行：问题描述，建议改为 Y。 2. [建议] 第 Z 行：问题描述。

allowed-tools的取值是 Claude Code 内置工具名，常见的有Read、Write、Edit、Bash、Glob、Grep。写多个用逗号分隔。这里有个坑：如果你只写Read，Skill 就只能读文件，想让它自动改代码就得加Edit；如果 Skill 要跑格式化脚本，必须加Bash。但Bash权限很大，能执行任意命令，所以只在你确实需要跑脚本时才加。

权限最小化原则：一个只做代码审查的 Skill，Read加Bash就够了，不需要Write和Edit，因为审查报告是输出给用户看的，不是直接改文件。如果确实要自动修复，再加Edit。团队共享的 Skill 尤其要注意，别把Bash和Write一起放开，否则一个恶意 Skill 就能改你整个项目。

description的写法直接决定触发率。太模糊比如“检查代码”，Claude 可能匹配不到；要写成“检查 Java 代码格式问题，包括命名规范、缩进、大括号位置，当用户提到检查代码风格、代码审查、格式化时触发”。把用户可能说的同义词都列进去，触发率会明显提升。

4. 用 skill-creator 辅助生成与本地加载验证

如果你不想手写 YAML 和 Markdown，可以用官方的skill-creator工具对话生成。安装命令：

npx skills-installer install @anthropics/claude-code/skill-creator --client claude-code

装好之后在 Claude Code 里输入需求，比如“创建一个 Skill，按照公司规范写技术文档，要求包含 API 描述、请求参数、返回值、错误码和调用示例”。Claude 会引导你确认细节，然后自动生成SKILL.md并安装到~/.claude/skills/目录。生成后建议打开文件检查一遍，尤其是allowed-tools和description，自动生成的内容有时会偏泛。

手动开发的 Skill 要加载到 Claude Code，有两种安装级别。个人级全局可用，把文件夹移到~/.claude/skills/：

# Linux/Mac mv java-code-checker ~/.claude/skills/ # Windows PowerShell Move-Item java-code-checker ~\.claude\skills\

项目级团队共享，放到项目根目录的.claude/skills/下并提交 Git：

mkdir -p .claude/skills mv java-code-checker .claude/skills/ git add .claude/skills git commit -m "feat: add java code checker skill"

团队成员git pull后自动拥有该 Skill，不需要各自安装。

验证安装是否成功，用 skills 命令行工具列出已安装的 Skill：

npx skills ls -a claude-code -l

如果列表里能看到java-code-checker，说明加载成功。接下来测试触发，在 Claude Code 里输入自然语言：“帮我看看 UserService.java 的代码风格有没有问题？”配置正确的话，Claude 会回复“我将使用 java-code-checker 技能来分析代码”，然后按你定义的步骤执行。

如果自动触发失败，可以用斜杠命令强制调用：

/java-code-checker 检查 src/main/java/App.java

强制触发能跑通但自动触发不行，问题基本都出在description上，回去把关键词补全。

5. 常见报错排查：401、local proxy failed 与 reading choices

开发 Skill 过程中遇到的报错，大部分不在 Skill 本身，而在接入层。下面按真实报错逐个排查。

401 Unauthorized：最常见。原因通常是ANTHROPIC_AUTH_TOKEN没设、设错，或者 Key 过期。先检查环境变量：

echo $ANTHROPIC_AUTH_TOKEN

如果输出为空，说明没设上。如果输出的是sk-开头的串，去 TaoToken 控制台确认这个 Key 还有效。另外注意ANTHROPIC_BASE_URL末尾不要多加/v1，Claude Code 会自己拼，写成https://taotoken.net/api/v1反而会 404 或 401。

local proxy failed：这个报错说明 Claude Code 尝试走本地代理但连不上。检查你的settings.json里有没有残留的HTTP_PROXY或HTTPS_PROXY配置，有的话删掉。TaoToken 的接入不需要任何本地代理，直接走https://taotoken.net/api即可。如果你之前配过其他工具的代理环境变量，也会干扰 Claude Code，用env | grep -i proxy查一遍，有就 unset。

reading choices 报错：这个通常出现在响应格式不符合预期时，比如返回体里没有choices字段。Claude Code 走的是 Anthropic 协议，返回的是content数组，不是 OpenAI 的choices。如果你在配置里误把 Base URL 指向了 OpenAI 兼容端点，就会报这个错。确认ANTHROPIC_BASE_URL是https://taotoken.net/api，不要指向其他路径。

OAuth token conflict：前面提过，OAuth 登录态和 API Key 认证冲突。解决方法是清掉 Claude Code 的登录缓存，通常在~/.claude/下，找到credentials.json或类似文件删掉，然后只用环境变量方式启动。

Skill 不触发：不是报错但很常见。检查三点：SKILL.md文件名是否全大写；文件夹是否在~/.claude/skills/或项目.claude/skills/下；description是否包含用户实际会说的词。用npx skills ls -a claude-code -l确认 Skill 被识别到。

权限不足：Skill 执行到一半报工具不可用，说明allowed-tools没放开对应工具。比如工作流程里写了“使用 Edit 工具修复代码”，但allowed-tools只有Read, Bash，就会失败。回去补上Edit。

排查顺序建议：先确认模型接入通（问一句你好），再确认 Skill 被加载（ls 能看到），最后确认触发词匹配（强制触发能跑）。三层都过，基本不会有大问题。

6. 把 Skill 接入你的日常编码流

Skill 开发完之后，真正发挥价值是在日常编码里。我的做法是把项目级 Skill 和 TaoToken 的 Coding Plan 配合用：项目里放.claude/skills/固化团队规范，模型侧用 Coding Plan 保证长时间编码的额度稳定。Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合需要连续跑 Agent 任务的场景。

如果你更想先验证模型对话效果，可以到 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 直接试。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各客户端的完整配置示例。Claude Code 专项接入说明在 https://taotoken.net/doc/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite ，照着配就行。

最后给一个实用技巧：Skill 的description不要一次写死，先写一版，用一周，把实际触发失败时你说的原话补进去，迭代两三轮触发率就上来了。另外allowed-tools从最小集开始，缺什么加什么，别一上来就全开。团队共享的 Skill 建议在SKILL.md顶部加一行版本号和负责人，方便追溯。