1. 为什么你的 Claude Code 需要一个 SKILL.md如果你已经在用 Claude Code 写代码大概率遇到过这种场景团队里有一套固定的代码规范、一套固定的接口文档格式、一套固定的发布流程每次开新会话都要重新贴一遍提示词贴完还担心模型记不全。Anthropic 推出的 Skills 机制本质就是给 Claude Code 装一个「可复用的入职手册」——把这类重复性知识封装成文件夹模型在需要时自动加载不需要你每次手动喂。SKILL.md 就是这个文件夹的入口文件。它不是一个普通的说明文档而是 Claude Code 判断「要不要启用这个技能」的唯一依据。你写得好模型在该触发的时候精准触发你写得含糊模型要么不加载要么在不该加载的时候乱加载白白吃掉上下文。这篇面向的是需要为团队封装可复用技能包的开发者。我会从目录结构讲到加载机制给出可以直接抄的 SKILL.md 骨架、目录布局以及用 TaoToken 统一 Key 的 settings.json 配置片段最后演示新增技能后怎么通过一次对话验证加载是否生效。全程按「能跟着做」的标准来写不堆概念。2. 前置准备用 TaoToken 统一管理 Claude Code 的 Key在动手写 SKILL.md 之前先把调用链路理顺。Claude Code 本身是一个命令行工具它需要访问 Claude 模型。团队协作时最头疼的是每个人各自配 Key、各自记不同的地址出了问题不好排查。我的做法是用 TaoToken 做统一入口一个 Key 覆盖模型对话、编码计划、控制台管理这些场景。TaoToken 的定位是给开发者提供统一的模型接入层官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要在控制台创建一个 API Key然后把它写进 Claude Code 的配置文件里。具体操作路径先打开控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成一个 Key。生成后复制出来下一步会用到。如果你还没决定用哪个模型可以先在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 试一下调用是否通确认 Key 有效再往下走。这一步的意义在于后面所有 SKILL.md 的加载验证都依赖 Claude Code 能正常发起请求。Key 不通技能写得再好也验证不了。3. SKILL.md 的目录结构与加载机制3.1 一个技能包的完整目录布局Claude Code 加载技能时扫描的是技能根目录下的 SKILL.md。一个规范的技能包长这样my-team-skill/ ├── SKILL.md # 必选入口文件 ├── scripts/ # 可选可执行脚本 │ └── check_style.py ├── references/ # 可选按需加载的参考文档 │ ├── api-spec.md │ └── release-flow.md └── assets/ # 可选输出用资源 └── template.mdSKILL.md 是唯一强制要求的文件。scripts/ 放可执行脚本Claude Code 可以直接运行而不需要把脚本全文读进上下文references/ 放详细文档只在需要时加载assets/ 放模板、图标这类输出资源。这里有个容易踩的坑references/ 不要做深层嵌套。所有参考文件直接从 SKILL.md 链接过去保持一级目录。嵌套深了模型在按需加载时容易找不到路径。3.2 加载机制三级渐进式披露Claude Code 加载技能不是一次性把整个文件夹读进来而是分三级第一级是元数据也就是 SKILL.md 顶部 YAML 里的 name 和 description这部分始终在上下文里大约 100 词。模型靠它判断当前任务要不要启用这个技能。第二级是 SKILL.md 的 Markdown 主体只有技能被触发后才加载控制在 5k 词以内。这里放核心流程不放细节。第三级是捆绑资源也就是 scripts/、references/、assets/ 里的内容模型按需加载。脚本可以直接执行不需要加载全文。这个设计的好处是上下文占用最小化。你团队里可以放几十个技能平时只有元数据占着上下文真正用到哪个才加载哪个。3.3 SKILL.md 骨架可以直接抄的模板下面是一个面向团队代码规范的 SKILL.md 骨架YAML 元数据加 Markdown 主体--- name: team-code-style description: 该技能用于检查团队 Python 代码是否符合内部规范包括命名、注释、异常处理。当用户要求审查代码风格或提交前自检时启用。 --- # 团队代码规范检查 ## 核心流程 1. 读取目标 Python 文件识别函数、类、模块级结构。 2. 按规范逐项检查命名用 snake_case类名用 PascalCase公共函数必须有 docstring。 3. 异常处理必须指定具体异常类型禁止裸 except。 4. 输出问题清单标注行号和修改建议。 ## 参考资源 - 完整规范条目见 [references/api-spec.md](references/api-spec.md) - 自动检查脚本见 [scripts/check_style.py](scripts/check_style.py)description 的写法是关键。要用第三人称描述「该技能用于什么场景」而不是「你可以用这个技能做某事」。模型是基于这段描述做触发判断的写得越具体误触发越少。4. 可复制配置settings.json 接入 TaoTokenClaude Code 的配置写在 settings.json 里。下面这段是接入 TaoToken 的完整配置把 API 地址指向 TaoToken 的端点Key 用你上一步生成的那个{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 }, skills: { enabled: true, paths: [ ./skills/my-team-skill, ./skills/another-skill ] } }几个参数说明一下。ANTHROPIC_BASE_URL 指向 https://taotoken.net/api 注意这里不加任何查询参数。ANTHROPIC_API_KEY 填你在控制台生成的 Key。skills.paths 是技能目录列表Claude Code 会扫描这些路径下的 SKILL.md。如果你团队用的是长期编码或 Agent 场景可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它在持续调用场景下更省心。配置方式一样只是 Key 的额度策略不同。配置写完后重启 Claude Code 让 settings.json 生效。这一步别偷懒很多人改了配置没重启然后怀疑技能没加载其实是配置根本没读进去。5. 验证请求新增技能后如何确认加载生效技能写好了配置也改了怎么确认它真的被加载了最直接的办法是通过一次对话触发。5.1 用一次对话触发技能在 Claude Code 里输入一句会命中 description 的话比如帮我检查一下 utils.py 的代码风格是否符合团队规范如果技能加载成功Claude Code 会先加载 team-code-style 的 SKILL.md 主体然后按里面的核心流程执行。你会看到它读取文件、逐项检查、输出问题清单。如果技能没加载它只会用通用能力泛泛回答不会提到你规范里的具体条目。5.2 用脚本验证加载路径更严谨的做法是写一个检查脚本确认技能目录被正确扫描。在 scripts/ 下放一个 check_style.pyimport sys def check_naming(name: str) - bool: return name.islower() and _ in name or name.islower() if __name__ __main__: target sys.argv[1] if len(sys.argv) 1 else example_func print(f检查 {target}: {通过 if check_naming(target) else 不通过})然后在对话里说「运行 scripts/check_style.py 检查 example_func」。如果技能加载正常Claude Code 会定位到脚本并执行输出检查结果。这一步能同时验证 SKILL.md 的路径引用和脚本执行链路。5.3 成功结果长什么样加载生效时你会观察到三个信号一是模型明确提到它正在使用团队代码规范二是输出里出现了你 SKILL.md 中定义的具体检查项而不是通用建议三是如果引用了 references/ 里的文档模型会按需读取对应文件。三个信号都出现说明三级加载机制都在正常工作。6. 本篇常见错排查技能不生效九成出在下面几个地方。description 写得太泛。比如写成「该技能用于处理代码」模型无法判断什么时候该触发。改成「该技能用于检查团队 Python 代码是否符合内部命名和注释规范当用户要求审查代码风格时启用」触发就准了。skills.paths 路径写错。相对路径是相对于 settings.json 所在目录不是相对于当前工作目录。路径错了Claude Code 扫描不到 SKILL.md技能等于不存在。建议用绝对路径或者确认相对基准。YAML 元数据格式错误。name 和 description 必须在文件最顶部用三个短横线包裹。中间多了空行、缩进不对、冒号后没空格都会导致解析失败。解析失败时技能会被静默跳过不报错所以特别难查。references/ 嵌套太深。前面提过参考文件保持一级目录。如果写成 references/aws/deploy/step1.md模型按需加载时容易找不到。改了配置没重启。settings.json 是启动时读取的改完必须重启 Claude Code。这个坑我踩过排查了半天以为是技能写错了。Key 或地址不通。如果 Claude Code 连请求都发不出去技能加载验证根本无从谈起。先在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 确认 Key 有效再回来查技能。7. 把技能包用起来接入文档与后续动作技能包封装好之后团队协作的关键是让每个人都能快速接入。接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有完整的配置说明可以直接转给团队成员照着做。如果你用的是 Claude Code 的 Anthropic 兼容模式参考 ClaudeCodeAnthropic 接入页 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 里面有针对性的配置示例。我的建议是先把一个技能跑通确认加载和触发都正常再批量封装其他技能。一次上十几个技能出了问题很难定位是哪个环节。另外SKILL.md 的 description 建议团队内部统一评审一次这是触发准确率的命门比主体内容还重要。最后提醒一句技能包要跟着团队规范一起迭代。规范改了SKILL.md 和 references/ 里的内容要同步更新否则模型会按旧规范执行反而帮倒忙。