1. 先搞清楚 Claude Code 的 skill 到底解决什么问题如果你刚开始用 Claude Code大概率经历过这样的循环每次让它写测试都要把「用 pytest、断言要写清楚、mock 外部依赖、文件放 tests/ 目录」这套话重复一遍每次让它生成接口文档又要把团队的标题规范、参数表格式再贴一次。提示词越攒越长对话越开越多但真正沉淀下来的东西几乎为零。Claude Code 里的 skill 就是冲着这个痛点来的。你可以把它理解成「写给 Claude 看的项目说明书 工作流剧本」它是一份 Markdown 文件通常叫 SKILL.md里面写清楚某个任务该怎么做、按什么步骤做、输出成什么格式。当你在对话里触发它时Claude 会把这份文件加载进上下文然后按里面的指令自主规划、调用工具、甚至派生子代理去干活。它和普通的斜杠命令不是一回事。像/clear、/compact这种是硬编码的固定操作点一下执行一个动作不涉及推理。而 skill 是「提示词 推理」的组合你输入/generate-docs src/authClaude 会读 SKILL.md理解要做什么再去搜索目录、读文件、提取函数签名最后按你规定的格式吐出一份文档。整个过程是模型在驱动不是脚本在跑。适合谁三类人最该上手一是天天给 Claude 重复贴同一段提示词的开发者二是团队里有固定代码规范、想让 AI 也遵守的 tech lead三是想把「代码审查」「批量重构」这类多步任务固化下来的工程团队。这篇就从 SKILL.md 的目录结构讲起一路写到 subagent 的配置骨架最后用一次真实调用验证 skill 有没有被正确加载。2. 前置准备把 TaoToken 的 Key 和 API 通道配好在写 skill 之前得先保证 Claude Code 能正常发请求。我这边习惯用 TaoToken 做统一的 Key 和 API 通道管理好处是多个工具、多个项目共用一套凭证不用每个地方都去改环境变量。先去控制台拿一个 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制出来先放一边。注意这个 Key 只在创建时完整显示一次丢了就得重建。拿到 Key 之后配置 Claude Code 的接入通道。Claude Code 支持通过环境变量指定 API 基址和密钥你可以在 shell 的配置文件里写也可以在每个项目的.claude/settings.json里写。我推荐后者因为项目级配置能跟着 Git 走团队其他人拉下来就能用。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }这里有个坑要提醒ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要在后面加/v1之类的路径Claude Code 会自己拼接。填错了会报 404排查起来很费时间。如果你不想把 Key 明文写进 settings.json毕竟要提交到仓库可以只写基址Key 走系统环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥配好之后先跑一个最简单的验证确认通道是通的claude -p 回复 ok 两个字如果终端里正常返回了内容说明 Key 和通道都没问题可以进入下一步写 skill 了。要是报鉴权错误回头检查 Key 有没有复制全、有没有多余空格。3. 可复制配置SKILL.md 骨架与 subagent 目录结构现在进入正题。Claude Code 的 skill 分两个存放层级全局 skill 放在~/.claude/skills/技能名/SKILL.md所有项目都能用项目级 skill 放在项目根目录的.claude/skills/技能名/SKILL.md只对当前项目生效而且能通过 Git 和团队共享。团队协作场景我强烈建议用项目级规范跟着代码走新人 clone 下来就自带。一个完整的 skill 目录长这样.claude/ ├── settings.json └── skills/ └── generate-docs/ ├── SKILL.md └── scripts/ └── extract_symbols.pySKILL.md 是必须的scripts 目录是可选的用来放 skill 需要调用的辅助脚本。下面是一份可以直接抄的 SKILL.md 骨架我以「生成接口文档」为例--- name: generate-docs description: 当用户要求为某个模块、API 或代码目录生成技术文档时自动触发。 disable-model-invocation: false user-invocable: true context: fork --- # 生成接口文档 请为 $1用户传入的路径或模块名生成一份 Markdown 格式的技术文档。 ## 执行步骤 1. 搜索并读取 $1 目录下的所有核心源文件。 2. 提取其中的类、函数、参数列表和代码注释。 3. 按照团队规范组织文档结构。 ## 输出格式规范 - 必须包含概述、参数表、返回值说明、至少一个调用示例。 - 标题统一用 ## 前缀不要用下划线样式。 - 参数表用 Markdown 表格列固定为参数名、类型、必填、说明。顶部的 YAML Frontmatter 是控制 skill 行为的关键几个字段值得单独说字段作用建议值nameskill 的唯一标识也是/触发时的命令名小写加连字符description模型自动触发时读取的匹配依据写清楚「什么时候用」一句话说清触发场景disable-model-invocation设为 true 则只能手动/触发部署、提交类 skill 设 trueuser-invocable设为 false 则只能模型后台调用隐式规范类 skill 设 falsecontext设为 fork 则在隔离子代理中运行重检索任务设 forkcontext: fork这个配置特别值得展开。当你的 skill 需要大量搜索代码、反复试错时中间过程会产生很多日志。如果不隔离这些日志会全部塞进当前对话的上下文窗口把真正有用的信息挤出去。设成 fork 之后skill 在一个独立的 subagent 里跑只有最终结果回到主对话上下文干净很多。subagent 和 skill 的关系可以这样理解skill 是「做什么」的说明书subagent 是「在哪做」的执行环境。一个 skill 可以选择在主对话里跑也可以 fork 出一个 subagent 去跑。需要并行处理多个模块时你甚至可以在 skill 里描述「为每个子目录派生一个 subagent」让它们同时干活。4. 验证请求确认 skill 被正确加载写完 SKILL.md 不代表就生效了得实际调一次确认。验证分两步先确认 skill 被识别再确认执行结果符合预期。第一步列出当前可用的 skill。在 Claude Code 里输入/skills如果配置正确你应该能在列表里看到generate-docs。看不到的话八成是目录层级写错了——注意是.claude/skills/generate-docs/SKILL.md不是.claude/skills/generate-docs.md多一层目录少一层目录都不行。第二步手动触发一次带上参数/generate-docs src/auth这里的src/auth会替换掉 SKILL.md 里的$1。正常情况下Claude 会开始搜索src/auth目录、读取文件、提取符号最后按你规定的格式输出文档。如果它只是回了一句「好的我来生成」然后什么都没做说明 SKILL.md 的指令区写得太模糊模型没抓到具体步骤。第三步验证自动触发。新开一个对话直接说帮我把 src/auth 目录的接口文档写一下如果description写得准确Claude 会自己匹配到这个 skill 并加载执行不需要你手动敲/generate-docs。这一步能过说明 skill 的自动触发链路是通的。验证时我习惯加一个「探针」——在 SKILL.md 的输出规范里写一条很显眼的规则比如「文档开头必须有一行 本文档由 generate-docs skill 生成」。调用后如果这行出现了就证明 skill 确实被加载了而不是模型凭自己的理解在瞎写。这个技巧在排查「skill 到底有没有生效」时特别好用。5. 本篇常见错排查skill 列表里看不到自定义 skill。先检查路径。全局是~/.claude/skills/项目级是项目根/.claude/skills/。常见错误是把 SKILL.md 直接放在 skills 目录下正确做法是每个 skill 一个子目录。另外文件名必须是大写的SKILL.md小写的skill.md在部分系统上识别不到。手动触发报「未知命令」。检查 Frontmatter 里的name字段/后面跟的就是这个名字。如果 name 里带了大写或空格触发时会出问题统一用小写加连字符最稳。自动触发不生效。九成是description写得太泛。像「用于生成文档」这种描述模型很难判断什么时候该用。改成「当用户要求为某个模块、API 或代码目录生成技术文档时自动触发」把触发场景写具体匹配率会高很多。另外确认disable-model-invocation没有设成 true。skill 执行到一半卡住或超时。如果 skill 涉及大量文件搜索建议加上context: fork让它在子代理里跑。主对话里跑重检索任务很容易因为上下文膨胀导致响应变慢甚至中断。settings.json 改了但没生效。Claude Code 读取配置的优先级是项目级.claude/settings.json 用户级~/.claude/settings.json 系统环境变量。如果你在项目里改了基址但没生效检查一下是不是被用户级配置覆盖了。改完配置记得重启 Claude Code 会话热加载不一定可靠。请求报 401 或 403。大概率是 Key 的问题。去 https://taotoken.net/api-keys 确认 Key 还在、没被删。另外检查ANTHROPIC_BASE_URL有没有多写路径正确值是https://taotoken.net/api。6. 把 skill 沉淀成团队资产写到这里skill 的骨架、配置、验证、排障都过了一遍。最后说点实操心得。skill 的价值不在于写得多而在于写得准。我见过有人一口气建了二十个 skill结果每个都写得含糊模型触发时经常匹配错。与其铺量不如先把团队里最高频的两三个重复提示词固化下来——比如「按规范写单测」「生成接口文档」「代码审查清单」这三个场景几乎每个项目都用得上。另外skill 是可以迭代的。第一次写完跑一遍看输出哪里不对回头改 SKILL.md 的指令区再跑一遍。这个过程本身就是在做上下文工程你把「什么样的输出才算好」这件事从脑子里、从聊天记录里搬进了一个可版本管理的文件。时间长了.claude/skills/目录就成了团队最佳实践的活文档。如果你还想把 skill 用在更长期的编码任务上比如让 subagent 持续跑批量重构可以看看 Coding Plan 的用法https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。想先验证模型对 skill 指令的理解能力可以直接在模型对话里试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置细节都在里面。