1. 为什么你的 Claude Code 需要一个自定义 SkillClaude 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建好之后复制那串以sk-开头的 Key后面配置要用。这里要区分两个地址官网带 UTM 参数用于注册引流API 端点固定为https://taotoken.net/api不要加 UTM。Claude Code 走的是 Anthropic 协议所以 Base URL 填https://taotoken.net/apiClaude Code 会自动拼接/v1/messages路径。配置方式有两种。第一种是临时环境变量适合快速测试export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的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/apiKey 是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.mdSKILL.md分两段YAML frontmatter 和 Markdown 正文。frontmatter 里三个字段最关键name、description、allowed-tools。name是 Skill 标识用 kebab-casedescription决定触发时机要写具体把用户可能说的关键词都塞进去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。写多个用逗号分隔。这里有个坑如果你只写ReadSkill 就只能读文件想让它自动改代码就得加Edit如果 Skill 要跑格式化脚本必须加Bash。但Bash权限很大能执行任意命令所以只在你确实需要跑脚本时才加。权限最小化原则一个只做代码审查的 SkillRead加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/下并提交 Gitmkdir -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 命令行工具列出已安装的 Skillnpx 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末尾不要多加/v1Claude 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_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合需要连续跑 Agent 任务的场景。如果你更想先验证模型对话效果可以到 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 直接试。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的完整配置示例。Claude Code 专项接入说明在 https://taotoken.net/doc/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 照着配就行。最后给一个实用技巧Skill 的description不要一次写死先写一版用一周把实际触发失败时你说的原话补进去迭代两三轮触发率就上来了。另外allowed-tools从最小集开始缺什么加什么别一上来就全开。团队共享的 Skill 建议在SKILL.md顶部加一行版本号和负责人方便追溯。