1. 为什么你的 Claude Code 需要一个自定义 Skill如果你已经在用 Claude Code 写代码大概率遇到过这种场景每次让它生成接口文档输出格式都不一样每次让它按团队规范提交代码它总要“自由发挥”一下每次让它跑一遍部署检查清单它总漏掉其中两步。你反复在对话里贴同一段规范贴到怀疑人生。Claude Code 的 Skill 系统就是来解决这个问题的。简单说Skill 是一个可以被语义触发的“能力包”它把领域知识、执行步骤、输出规范和约束条件封装成一个独立单元在需要的时候才渐进式加载进主 Agent 的上下文。它不是插件不是扩展更像是一份“按需调用的认知说明书”。这篇内容面向已经在用 Claude Code 的开发者带你从零创建一个可运行的 Skill写SKILL.md骨架、在settings.json里接入 TaoToken 统一 Key 和 API 通道、最后用一条命令验证 Skill 是否被正确加载和调用。全程可复制跟着做就能跑通第一个自定义 Skill。先明确一个概念Skill 在 Claude Code 里就是一个文件夹核心是里面的SKILL.md文件。这个文件用 Markdown 写头部带一段 YAML 前置元数据用来告诉 Claude “我是谁、我什么时候该被触发、我该做什么”。文件夹里还可以放scripts/、references/、assets/等可选目录分别放可执行代码、按需加载的文档和输出模板。你可以把主 Agent 想象成一部手机Skill 就是手机里的 App。平时 App 不运行只有你点开语义触发它才启动。这个比喻能帮你理解 Skill 的核心设计主 Agent 保持简洁能力通过 Skill 无限扩展。2. TaoToken 前置统一 Key 打通 API 通道在写 Skill 之前先把 API 通道理顺。Claude Code 需要访问模型服务如果你同时用多个模型或工具Key 管理会变得很乱。TaoToken 的作用就是提供一个统一的 API 入口你只需要维护一个 Key就能在 Claude Code 里稳定调用。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个基础地址。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key。这个 Key 就是后面写进settings.json的凭证。创建时建议给它起一个能识别的名字比如claude-code-skill-dev方便以后区分不同用途。拿到 Key 之后不要急着写 Skill先把 Claude Code 的基础接入配好。因为 Skill 的验证依赖模型能正常响应如果 API 通道本身不通后面排查会非常痛苦。我试过在通道没配好的情况下写 Skill结果 Skill 加载成功了但调用没反应白白浪费半小时。TaoToken 的接入文档在 https://taotoken.net/doc 里面有不同客户端的配置示例。Claude Code 的配置方式是在项目根目录或用户目录下创建settings.json把 API 端点和 Key 写进去。下一节给出可直接复制的配置。3. 可复制配置SKILL.md 骨架与 settings.json3.1 确定 Skill 的存放位置Skill 放哪里决定了谁能用它。Claude Code 支持几个级别级别路径使用范围版本控制Enterprise管理员配置组织内所有用户集中管理Personal~/.claude/skills/skill-name/SKILL.md你所有项目个人本地Project.claude/skills/skill-name/SKILL.md当前项目提交到 GitPluginplugin/skills/skill-name/SKILL.md启用插件的项目随插件分发同名 Skill 的优先级是 Enterprise Personal Project。Plugin Skill 用plugin-name:skill-name命名空间不会和其他级别冲突。我们这次创建一个项目级 Skill路径是.claude/skills/hello-taotoken/SKILL.md。这样它只对当前项目生效也方便提交到 Git 让团队共享。3.2 写 SKILL.md 骨架先建目录再写文件。在项目根目录执行mkdir -p .claude/skills/hello-taotoken然后创建.claude/skills/hello-taotoken/SKILL.md内容如下--- name: hello-taotoken description: 创建或更新 HELLO_TAOTOKEN.md用于验证 Skill 加载与调用闭环。当用户要求验证 Skill 是否生效、或提到 hello-taotoken 时触发。 trigger: manual --- ## Instructions 1. 在项目根目录创建或更新 HELLO_TAOTOKEN.md。 2. 文件内容必须包含以下三行 - # hello skill - 生成了 Hello_TaoToken - Time: 当前时间 3. 完成后用不超过 3 行告诉我你做了什么。这个 Skill 是典型的任务型 Skill。它有明确的执行步骤1、2、3有固定的输出模板trigger: manual表示必须用/hello-taotoken手动调用。这里最关键的是description字段。它不是给人看的文档而是给 Claude 看的触发器。Claude 决定是否激活一个 Skill完全依赖对description的语义理解不是简单匹配关键词。所以描述要写清楚“什么场景下用我”。虽然这里用了中文但英文描述在语义匹配上通常更稳建议正式项目用英文。3.3 配置 settings.json 接入 TaoToken在项目根目录创建或编辑settings.json{ apiKey: 你的_TaoToken_API_Key, apiBaseUrl: https://taotoken.net/api, model: claude-sonnet-4-20250514, skills: { enabled: true, directories: [.claude/skills] } }几个参数说明apiKey填你在 TaoToken 控制台创建的 Key。apiBaseUrl固定用https://taotoken.net/api不要加 UTM 参数。model按你实际可用的模型填这里只是示例。skills.enabled打开 Skill 功能skills.directories指向项目级 Skill 目录。如果你希望这个配置对所有项目生效可以把settings.json放到用户目录下同时把 Skill 放到~/.claude/skills/。但建议先用项目级跑通确认没问题再往上提。注意apiKey是敏感信息如果项目要提交到 Git记得把settings.json加入.gitignore或者用环境变量引用。不要把真实 Key 硬编码进版本库。4. 验证请求确认 Skill 被正确加载与调用配置写完了现在验证整条链路。分两步先确认 API 通道通再确认 Skill 被加载。4.1 验证 API 通道在项目根目录启动 Claude Code随便问一句claude进入交互后输入你好请回复当前使用的模型名称。如果模型正常回复说明 TaoToken 的 API 通道已经通了。如果报错先看错误信息里的状态码。401 通常是 Key 不对404 通常是apiBaseUrl写错超时则检查网络。4.2 验证 Skill 被加载在 Claude Code 交互界面里输入斜杠命令/hello-taotoken如果 Skill 被正确加载Claude 会开始执行SKILL.md里的步骤在项目根目录创建HELLO_TAOTOKEN.md写入三行内容然后告诉你它完成了什么。执行完后检查文件cat HELLO_TAOTOKEN.md预期输出类似# hello skill 生成了 Hello_TaoToken Time: 2025-06-01 14:32:10看到这个文件说明 Skill 从加载到调用的闭环跑通了。如果/hello-taotoken没有反应或者提示找不到命令说明 Skill 没被加载往下看排查部分。4.3 验证语义触发可选trigger: manual的 Skill 需要手动调用。如果你想测试语义触发可以把trigger改成auto然后在对话里说“帮我验证一下 Skill 是否生效”。Claude 会根据description的语义判断是否激活这个 Skill。不过自动触发不如手动稳定正式项目建议关键 Skill 都用 manual。5. 本篇常见错排查5.1 Skill 不加载路径和目录名对不上最常见的问题是路径写错。Claude Code 默认扫描.claude/skills/下的子目录每个子目录名就是 Skill 名。如果你把SKILL.md直接放在.claude/skills/根下它不会被识别。正确结构是.claude/skills/ └── hello-taotoken/ └── SKILL.md另外检查settings.json里的skills.directories是否指向了正确目录。如果你用的是用户级 Skill路径应该是~/.claude/skills。5.2 YAML 前置元数据格式错误SKILL.md头部的 YAML 必须用---包裹且---要单独占一行。常见错误是name或description缩进不对或者冒号后面没空格。正确写法--- name: hello-taotoken description: 描述内容 trigger: manual ---如果 YAML 解析失败Skill 会被静默跳过不会报错。所以写完先用一个 YAML 校验工具检查一下。5.3 API Key 无效或额度不足如果 Skill 加载了但调用没反应先看 API 通道。在 Claude Code 里直接问一个普通问题如果也失败说明是 Key 或额度问题。去 TaoToken 控制台检查 Key 是否被禁用、额度是否用完。API Keys 页面在 https://taotoken.net/api-keys 。5.4 description 写得太模糊导致语义触发失败如果你把trigger设成auto但 Claude 总是不激活 Skill多半是description太模糊。比如只写“处理文件”Claude 不知道什么时候该用。要写清楚触发场景比如“当用户要求生成 API 文档、或提到接口规范时触发”。描述里包含具体动作和场景词语义匹配才准。5.5 文件创建了但内容不对如果HELLO_TAOTOKEN.md创建了但内容缺行检查SKILL.md里的步骤描述是否足够明确。Claude 会按 Instructions 执行但如果你写的步骤有歧义它可能自由发挥。把每一步的输出要求写死比如“必须包含以下三行”能减少偏差。6. 跑通之后把 Skill 用起来第一个 Skill 跑通后你可以开始把它用到真实场景。参考型 Skill 适合放 API 规范、代码风格、领域知识影响 Claude“怎么做”任务型 Skill 适合放部署流程、提交规范、代码生成决定 Claude“做什么”。两者可以组合比如一个参考型 Skill 定义接口规范一个任务型 Skill 调用它生成文档。长期用 Claude Code 做编码和 Agent 开发的话可以考虑 TaoToken 的 Coding Plan地址是 https://taotoken.net/coding-plan 适合需要稳定通道和统一 Key 管理的场景。如果只是想先验证模型对话用模型对话入口 https://taotoken.net 就行。接入文档在 https://taotoken.net/doc API Keys 管理在 https://taotoken.net/api-keys 。最后给一个实用建议Skill 的description值得反复打磨。它不是文档是触发器。每次发现 Claude 该激活 Skill 却没激活或者不该激活却激活了就回来改description。改上三五轮触发准确率会明显提升。这比一次性写一个“完美”描述更有效。