1. 为什么你的 Claude Code 需要自定义 Skill如果你每天都在 Claude Code 里重复敲同一串指令——先git status、再git diff、想半天 commit message、git add .、git commit、git push——那你其实是在用 AI 干体力活。自定义 Skill 就是把这些固定动作打包成一个斜杠命令输入/git-save就自动跑完全流程。Skill 本质上是 Claude Code 的扩展机制它把「你每次都要口头告诉 AI 的操作流程」变成「AI 记住并自动执行的流程」。你只需要触发一次剩下的步骤由 AI 按预定义顺序完成。它适合三类人每天高频提交代码的开发者、需要固定启动多服务环境的全栈工程师、以及希望把团队工作流沉淀成可共享资产的 Tech Lead。这一章我会从skill.md的定义写到settings.json的注册给出可直接复制的模板并演示通过 TaoToken 统一 Key 通道接入 Claude Code 后如何验证斜杠命令真的能调起来。全程按「能跟做」的标准来每一步都有命令和预期结果。先明确一个概念区分Claude Code 的技能分内置和自定义两类。内置技能如/compact、/init、/code-review是自带的通用但不可改自定义技能是你针对项目或个人习惯定制的比如/git-save、/start-dev、/lint-fix。两者配合使用覆盖通用需求和个性化需求。调用方式统一走斜杠命令。输入/后 Claude Code 会弹出自动补全列表你选一个回车即可。真正要花心思的是「怎么创建」和「放哪一级」这两点决定了 Skill 能不能被正确扫描、能不能团队共享。下面先解决接入通道问题再进入创建细节。2. TaoToken 统一 Key 通道接入 Claude Code 的前置准备在写 Skill 之前得先保证 Claude Code 能正常调用模型。我用的是 TaoToken 的统一 Key 通道好处是一个 Key 走通对话、编码、Agent 多类模型不用为每个模型单独配一套凭证。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。前置准备分三步拿 Key、配环境变量、确认 Claude Code 能读到配置。第一步登录后在控制台创建 API Key。控制台地址带归因参数 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后复制那串sk-开头的 Key只显示一次务必存好。第二步把 Key 写进环境变量。Claude Code 读取的是ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这两个变量。在 macOS/Linux 的~/.zshrc或~/.bashrc里追加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的KeyWindows 用户在 PowerShell 里用setxsetx ANTHROPIC_BASE_URL https://taotoken.net/api setx ANTHROPIC_API_KEY sk-你的Key改完记得source ~/.zshrc或重开终端让变量生效。验证一下echo $ANTHROPIC_BASE_URL # 预期输出https://taotoken.net/api第三步确认 Claude Code 已安装并能启动。如果你还没装用 npm 全局装npm install -g anthropic-ai/claude-code claude --version这里有个容易踩的坑环境变量配好了但 Claude Code 启动时读的是它自己进程的环境。如果你在 IDE 里用插件形式启动IDE 可能没继承 shell 的环境变量。稳妥做法是在项目根目录建一个.env文件或者直接在启动 Claude Code 的终端里 export 一次再启动。Key 通道打通后模型调用就走 TaoToken 了。这一步是后面所有 Skill 能跑起来的基础——Skill 只是封装了「让 AI 做什么」真正执行推理的还是模型通道。通道不通斜杠命令敲了也没反应。3. 可复制配置skill.md 模板与 settings.json 注册片段这一节是核心给出两种创建方式的完整可复制片段。你按复杂度选一种即可。3.1 方式一settings.json 注册简单技能适合一两句话能说清的操作。在settings.json的skills字段里配置键值对键是命令名值是给 AI 的指令描述。项目级配置放在project/.claude/settings.json用户级放在~/.claude/settings.json。完整片段{ skills: { test: Run the project tests. Use: pnpm test, git-save: Save current changes: 1) git status 2) git diff 3) Generate Conventional Commits message 4) git add . 5) git commit 6) git push, deploy-staging: Deploy to staging. Steps: 1) pnpm run build 2) pnpm run deploy:staging 3) Verify at https://staging.example.com } }注意 JSON 语法键值对之间逗号分隔最后一个不能有逗号否则整个文件解析失败所有技能都不生效。改完用python -m json.tool settings.json校验一下。3.2 方式二插件目录创建完整技能复杂多步骤工作流用独立skill.md文件。目录结构~/.claude/plugins/ └── git-save/ └── skill.md项目级放project/.claude/plugins/用户级放~/.claude/plugins/。skill.md由 frontmatter 和正文组成完整模板--- name: git-save description: 一键完成代码提交和推送包含变更预览和 Conventional Commits 格式的提交信息 --- # git-save ## 触发条件 用户输入 /git-save或说提交代码、保存并推送时触发。 ## 执行步骤 1. 运行 git status查看变更文件列表 2. 运行 git diff预览变更内容 3. 根据变更内容生成符合 Conventional Commits 规范的提交信息 - 格式type(scope): description - type 可选feat / fix / refactor / docs / style / test / chore - 向用户确认提交信息是否合适 4. 运行 git add . 5. 运行 git commit -m {提交信息} 6. 运行 git push 7. 确认推送成功告知用户提交完成 ## 注意事项 - 如果 git status 显示没有变更告知用户并终止 - 如果 git push 失败告知原因不要自动重试超过 2 次 - 提交信息用英文遵循 Conventional Commits 规范frontmatter 里name必填对应斜杠命令名description必填显示在自动补全列表里。正文推荐四段式触发条件、执行步骤、注意事项、输出格式可选。3.3 三件套对照Base URL Key Model ID无论用哪种方式创建 Skill模型通道的配置都要写全三件套。如果你用 CC Switch 或 Cline MCP 这类工具管理配置对照填配置项值Base URLhttps://taotoken.net/apiAPI Keysk-你的KeyModel ID按控制台可用列表填如 claude-sonnet-4-5Codex 用户如果走auth.json对应字段是OPENAI_BASE_URL和OPENAI_API_KEYBase URL 同样填 TaoToken 的 API 地址。三件套缺一不可缺 Key 会 401缺 Base URL 会走默认端点导致连不上。4. 验证请求确认斜杠命令真的能调起来配置写完得验证。分两层先验证模型通道通再验证 Skill 被扫描到。4.1 验证模型通道在终端直接发一个最小请求确认 Key 和 Base URL 生效curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: reply with ok}] }预期返回一段 JSONcontent数组里有模型回复。如果返回 401说明 Key 不对或没读到环境变量如果返回连接错误检查 Base URL 是否拼错。4.2 验证 Skill 被扫描启动 Claude Code输入/看自动补全列表里有没有你创建的技能名。如果没有先试/reload-skills/reload-skills这个命令会重新扫描所有技能目录。还不显示就重启 Claude Code。重启后仍不显示按下面顺序排查文件是否放在.claude/plugins/skill-name/skill.md注意是skill.md不是SKILL.md大小写敏感frontmatter 的name和description是否都在settings.json 是否 JSON 语法错误。4.3 实测调用补全列表里出现/git-save后直接输入并回车。预期行为AI 依次执行git status、git diff生成一条 commit message 让你确认确认后完成 add、commit、push最后告诉你提交完成。整个过程你只参与一次确认。如果调用后 AI 没有按步骤走多半是skill.md里的执行步骤写得太模糊。把「运行 git 命令」改成「运行git status查看变更文件列表」这种具体描述AI 的遵循度会明显提升。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞的几类报错逐个对照。401 UnauthorizedKey 无效或没被读到。先echo $ANTHROPIC_API_KEY确认变量有值再确认 Claude Code 启动的终端继承了该变量。IDE 插件启动的场景环境变量常常没继承改成在项目.env里配或直接在终端启动。local proxy failed / connection refusedBase URL 写错或网络不通。确认填的是https://taotoken.net/api不要多写或少写/v1。有些工具要求 Base URL 带/v1有些不要按你所用工具的文档来。Claude Code 原生读ANTHROPIC_BASE_URL填到/api即可。reading choices / unexpected response shape模型返回结构不符合预期通常是 Model ID 填错或请求打到了不兼容的端点。对照控制台可用模型列表把 Model ID 改成实际存在的值。三件套里 Model ID 最容易随手填错。OAuth 相关报错Claude Code 某些版本会尝试走 OAuth 登录流程如果你用 API Key 通道需要在配置里显式禁用 OAuth 或选择 API Key 模式。检查settings.json里有没有残留的 OAuth 配置项清掉后重启。技能不生效但无报错斜杠命令不显示或显示了但执行不对。前者是扫描问题用/reload-skills或重启后者是指令描述问题优化skill.md的执行步骤。项目级和用户级有同名技能时会冲突重命名其中一个。排查顺序建议先 curl 验证通道再/reload-skills验证扫描最后实测调用验证执行。三层都过Skill 就算真正落地了。6. 把 Skill 用起来从单机到团队的统一通道Skill 设计有三条原则值得记住。单一职责一个 Skill 只做一件事/start-dev就只管启动环境别把提交和部署也塞进去。粒度适中3 到 10 步比较合适太少不值得封装太多难维护。错误处理每一步都要考虑失败后怎么办比如 push 失败不要自动重试超过 2 次commit 成功但 push 失败要明确告知用户当前状态别留下半完成的不一致。项目级和用户级的选择问自己两个问题这个 Skill 只对当前项目有意义吗团队其他人需要用吗项目特有的部署流程放项目级并纳入 Git通用的 Git 提交放用户级。判断口诀是「项目特有、团队共用 → 项目级个人通用、所有项目复用 → 全局」。把 Skill 和 TaoToken 统一 Key 通道结合价值在于团队共享 Skill 时每个人只需要配一次 Key 通道Skill 本身不含任何凭证安全且可版本控制。新成员克隆项目后配好三件套所有项目级 Skill 立刻可用。如果你还在单机阶段建议先把/git-save和/lint-fix这两个高频技能建起来跑顺了再往团队推。长期做编码和 Agent 工作流的可以看 Coding Plan 把通道和额度统一管理 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要查模型可用列表和接入细节的文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。想先验证模型对话效果的直接进 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 试一轮再决定。最后留一个实操建议把你每天重复三次以上的操作列出来挑步骤最固定的那个按本章模板写成skill.md跑通一次。Skill 的价值不在多在于你真的会去按那个斜杠。