1. 从一次“代码抢救”说起为什么你需要 Claude Skill如果你正在用 Claude 写代码、做测试、整理文档却总觉得每次都要重复交代项目背景、编码规范、历史踩坑那 Claude Skill 就是为你准备的。它本质上是一个能力封装包一个文件夹里面放一个SKILL.md文件就能把角色设定、规则约束、私有资料打包成一个可复用的“技能单元”让 Claude 在特定场景下自动加载并稳定输出。我上个月被临时拉去支援一个迭代了四年的支付模块文档几乎为零单元测试覆盖率不到 20%原班人马走得只剩一个刚转正的同事。leader 让我带他把核心接口的测试补齐。打开仓库的那一刻我头皮发麻状态机逻辑绕、表结构复杂、历史故障记录散落在聊天记录里。就在那几天我第一次被一个文件夹加一个 Markdown 文件救了命——我把代码规范、历史踩坑、边界条件全塞进去丢给 AI 助手它突然就“懂了”这个项目生成的测试用例质量吊打我手写了三天的版本。那个东西就叫 Skill。这篇教程面向想给 AI 助手扩展自定义能力的开发者尤其是测试、后端、运维方向的同学。你不需要写一行代码只要会建文件夹、会写 Markdown就能在 5 分钟内做出自己的第一个 Skill。下面我会交付可直接复制的SKILL.md骨架、文件夹命名规范、本地加载验证步骤并说明如何通过 TaoToken 统一 Key/API 通道接入 Claude 进行调用测试。2. 前置准备TaoToken 统一 Key 与 API 通道在动手写 Skill 之前先把调用通道准备好。Claude Skill 本身是本地文件夹结构但你要验证它是否生效需要一个能稳定调用 Claude 的入口。我实测下来用 TaoToken 统一管理 Key 和 API 通道比较省心一个 Key 可以覆盖模型对话、编码计划、控制台管理等多个场景不用在多个平台之间来回切换配置。你需要先拿到 API Key。打开控制台页面登录后进入 API Keys 管理页新建一个 Key 并复制保存。注意Key 只在创建时完整显示一次建议立刻存到密码管理器或本地环境变量里不要直接硬编码进代码提交到 Git。拿到 Key 之后你的调用基地址统一使用https://taotoken.net/api。这个地址不加任何查询参数保持干净。后续无论是用 curl 测试还是在 Claude Code、Coding Plan 里配置都填这个基地址。如果你更习惯在图形界面里先验证模型是否通可以直接打开模型对话页面选一个 Claude 模型发一条消息试试。确认通道正常后再回到本地做 Skill 的加载验证。这样排障时能快速区分是“通道问题”还是“Skill 文件问题”。提示Key 的权限和额度在控制台里可以随时查看和调整。建议给测试用的 Key 单独命名比如skill-test-key方便后续排查。3. 可复制配置文件夹结构与 SKILL.md 骨架3.1 文件夹命名规范先在你的电脑上找个目录比如~/projects/skills/然后新建一个文件夹。命名规则很简单全小写、用连字符分隔、不带中文和空格。比如code-review-assistant、payment-test-helper。这个名字只是给你自己看的Claude 调度时主要看SKILL.md里的 YAML 头。文件夹内部结构推荐这样组织code-review-assistant/ ├── SKILL.md └── docs/ ├── payment_flow.md ├── db_schema.sql └── known_issues.mdSKILL.md是必须存在的入口文件文件名大小写敏感必须叫SKILL.md。docs/是可选的知识库目录你可以把项目相关的私有资料放进去Claude 在加载 Skill 时会一并读取。3.2 SKILL.md 骨架可直接复制下面这段骨架你可以直接复制到自己的SKILL.md里改掉 name、description 和规则内容即可--- name: code-review-assistant description: 根据团队 Java 编码规范对提交的代码片段进行深度审查输出改进建议和风险点。 --- # 角色定义 你是一名资深 Java 后端工程师精通代码审查熟悉阿里巴巴 Java 开发手册对并发、性能、安全有极致敏感度。 # 审查规则 1. 逐条检查以下规范 - 命名是否符合驼峰规范避免拼音与英文混用 - 并发场景下是否正确使用锁或线程安全集合 - 数据库操作是否考虑事务边界和 SQL 性能 - 异常处理是否避免吞掉原始异常打印必要堆栈 - 集合操作是否考虑判空避免 NPE 2. 对每一个发现的问题给出严重等级高/中/低和修改建议示例。 3. 如果没有发现问题回复“未发现明显问题但建议补充相关单元测试”。 # 项目背景参考 请在分析本项目的任何代码前务必阅读 docs/ 目录下的所有文件作为上下文基础。YAML 头里的name和description不是给自己看的是给 AI 调度器看的。description 写得越精准Claude 越知道什么时候该自动调用这个技能。别写“帮我干活”这种泛词否则它可能在写诗的时候也尝试加载闹笑话。3.3 把私有资料扔进 docsSkill 真正厉害的地方在于它能把整个知识库带在身上。回到我那个支付项目我在docs/里塞了三样东西payment_flow.md是从代码里扒出来的支付状态流转图db_schema.sql是核心表结构known_issues.md是近半年线上故障复盘记录。然后在SKILL.md里加一句“请在分析本项目的任何代码前务必阅读 docs/ 目录下的所有文件”再次加载后我让它“根据退款接口代码和已知问题生成 P0 级的回归测试用例”它把半年前因为状态机并发导致重复退款的那个坑都覆盖进去了。你喂给它的私有资料越多它在这个狭窄领域里的表现就越接近一个贴着工牌的内部专家。4. 验证请求本地加载与 API 调用测试4.1 本地加载验证在 Claude 的聊天界面里点输入框左侧的回形针或加号选择“添加技能”或直接把文件夹拖进去。不同版本入口可能叫 “Upload Skill” 或 “Load folder as skill”找到就行。加载成功后直接发一段你最近写的代码过去看它怎么审。我上周随手喂了一段自己写的 Redis 分布式锁释放逻辑它立刻指出 finally 块里没有判断锁是否属于当前线程就直接释放还给了带 Redisson 的对比写法。4.2 用 curl 通过 TaoToken 验证通道如果你想在命令行里确认 API 通道和 Skill 内容是否配合正常可以用 curl 发一个请求。先把 Key 存到环境变量export TAOTOKEN_API_KEY你的Key然后发一个最小请求curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 512, messages: [ {role: user, content: 请用一句话说明代码审查中异常处理的核心原则。} ] }如果返回里包含正常的文本内容说明通道没问题。接下来把SKILL.md的内容作为 system 提示拼进去再发一次对比输出是否更贴合你的规则。这一步能帮你确认 Skill 的提示词是否真的在起作用。4.3 在 Coding Plan 里长期使用如果你打算把这个 Skill 用在日常编码或 Agent 工作流里建议走 Coding Plan 通道。它更适合长期、高频的编码场景Key 和额度管理也更集中。配置时基地址同样填https://taotoken.net/api把 Skill 文件夹放在项目根目录的.skills/下用 Git 管起来。团队新人入职拉一份仓库把技能文件夹一加载直接具备老员工的八成功力。5. 本篇常见错排查5.1 SKILL.md 文件名大小写错误最常见的问题就是文件名写成了skill.md或Skill.md。Claude 只认SKILL.md大小写必须完全一致。如果你加载后没反应先检查文件名。5.2 YAML 头格式错误YAML 头必须以---开头和结尾name和description的冒号后面要有一个空格。如果格式错了整个 Skill 可能被忽略。你可以用在线 YAML 校验工具先验一遍。5.3 description 写得太泛导致误触发有人把 description 写成“帮我干活”结果 Claude 在写诗、翻译、闲聊时都尝试加载这个 Skill输出变得很奇怪。description 要具体到场景比如“审查 Java 代码中的并发与异常处理问题”这样调度器才知道什么时候该用它。5.4 docs 目录路径写错在SKILL.md里引用docs/时路径是相对于SKILL.md所在文件夹的。如果你把SKILL.md放在子目录里路径就要相应调整。加载后如果 Claude 说找不到文件先检查相对路径。5.5 API 返回 401 或 403如果 curl 测试返回 401先确认x-api-key请求头里的 Key 是否正确、是否有多余空格。如果返回 403去控制台检查这个 Key 的权限和额度是否正常。排障时建议先用模型对话页面确认通道再回到命令行。5.6 Skill 加载后输出没变化有时候你改了SKILL.md但 Claude 还在用旧版本。这是因为部分客户端会缓存已加载的 Skill。解决办法是移除后重新加载或者重启客户端。我一般改完规则后会跑 10 个真实场景的输出把不符合预期的地方截图记下来回到SKILL.md里补规则、加禁止项改过三四轮之后才会进入“有点靠谱”的阶段。6. 把 Skill 用起来从 API Keys 到长期编码写到这里你已经有了一个可运行的 Skill 骨架和验证方法。接下来就是把它接入你的日常工作流。如果你只是偶尔测试用模型对话页面手动加载文件夹就够了如果你要长期在编码和 Agent 场景里用建议去 API Keys 页面建一个专用 Key再参考接入文档把基地址和鉴权配好走 Coding Plan 通道做长期调用。我现在所有项目都有一个.skills目录里面放几个不同的 Skill 文件夹用 Git 管起来。跨项目复用也简单把文件夹复制粘贴过去就行接口统一就是SKILL.md。调试 Skill 的唯一真理就是迭代先跑真实场景记录不符合预期的地方回到文件里补规则。一般改过三四轮之后这个 Skill 才会真正贴合你的项目。你不需要什么工程化平台不需要学 LangChain不需要申请服务器资源。你面前这台电脑建个文件夹写个 Markdown就拥有了你的第一个 AI 技能。从你最常跟 AI 抱怨的那句话开始——把那句“你每次都记不住我们用 Java 8 和 MyBatis”写进SKILL.md你会回来谢我的。