03-Skills技能系统详解：用Markdown与Prompt构建Claude Code可复用技能

1. 为什么你的 Claude Code 总是“记不住”项目规范用 Claude Code 写代码最让人抓狂的不是它不会写而是它每次都“重新做人”。你昨天刚跟它强调过提交信息要用feat:前缀、接口文档必须带错误码表、Markdown 二级标题要编号今天开个新会话它又按自己的心情输出了。你只能把同样的要求再贴一遍贴到怀疑人生。这个问题的根子在于Claude Code 的默认行为是“无状态”的它不会自动继承你脑子里的团队规范。而 Skills 技能系统就是来解决这件事的——它把“你反复交代的要求”变成一份 Markdown 文件放在项目里需要时一键触发或自动匹配让 Claude 按你写好的规则干活。Skills 适合谁三类人最该用一是团队里负责定规范的人把代码审查、文档格式、提交信息这些标准固化成文件二是经常用 Claude Code 做重复性任务的开发者比如每周都要生成接口文档、写测试方案三是想让 AI 输出“像自己写的”那种人把个人偏好写进技能文件省去每次调教。这篇不聊虚的直接给你一份能复制的 Skill 目录骨架、settings.json 配置片段以及加载验证和排错动作。你跟着做十分钟内就能跑通第一个自定义技能。2. 前置准备TaoToken 接入与 Claude Code 环境确认Skills 本身是 Claude Code 的扩展机制不依赖特定网关。但如果你是通过 API 方式接入 Claude Code需要先确保模型调用链路是通的。我实测下来用 TaoToken 的 API 接入比较省事它兼容 Anthropic 的接口格式Claude Code 可以直接对接。先拿到 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制保存。注意这个 Key 只在创建时显示一次丢了就得重建。然后确认你的 Claude Code 能正常调用模型。如果你还没配好在项目根目录创建或编辑.claude/settings.json填入类似下面的配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key } }这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_API_KEY换成你刚创建的那串。保存后重启 Claude Code随便问一句“你好”能正常回复就说明链路通了。注意settings.json 里不要写多余字段Claude Code 对配置格式比较敏感多一个逗号都可能加载失败。建议用 JSON 校验工具过一遍。环境通了之后我们进入正题。Skills 的文件放在项目根目录的.claude/skills/下按类别分文件夹每个技能一个.md文件。下面先给骨架。3. 可复制的 Skill 目录骨架与 settings.json 配置3.1 目录结构在项目根目录执行mkdir -p .claude/skills/review mkdir -p .claude/skills/docs mkdir -p .claude/skills/tools最终结构长这样你的项目/ └── .claude/ ├── settings.json └── skills/ ├── review/ │ └── code-review.md ├── docs/ │ └── api-doc.md └── tools/ └── md-output.md每个.md文件就是一个技能。Claude Code 在触发时会用 Read 工具读取这个文件把内容注入当前对话上下文相当于临时给模型加了一段系统提示。3.2 一个最小可用的技能文件先写一个最简单的验证机制能跑通。创建.claude/skills/tools/md-output.md# Skill: Markdown Output ## 描述 统一 Markdown 文档的输出格式避免编号和标题层级混乱。 ## 触发条件 - 用户要求生成 Markdown 文档 - 用户提及 /md-output - 用户说“按规范输出” ## 执行规则 ### 1. 标题编号 - H2 统一使用 ## 1. 标题 格式数字后跟英文句点和空格 - H3 使用 ### 1.1 标题 格式 - 特殊章节修订记录、参考资料不编号 ### 2. 代码块 - 所有代码块必须标注语言 - 禁止出现无语言标识的裸代码块 ### 3. 表格 - 表格前后各留一个空行 - 表头与内容对齐 ## 输出模板 按上述规则直接输出不需要额外说明。这个文件就是一份结构化的 Prompt 模板。Claude 读到它之后会按里面的规则约束自己的输出。3.3 settings.json 补充配置如果你想让技能在特定条件下自动触发可以在.claude/settings.json里加一段权限配置允许 Claude 读取 skills 目录{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, permissions: { allow: [ Read(.claude/skills/**) ] } }Read(.claude/skills/**)这行是告诉 Claude Code读取技能目录下的文件不需要每次弹权限确认。不加也能用但每次触发技能都会问你“是否允许读取”比较烦。配置改完记得重启 Claude Code否则不生效。4. 验证技能加载与触发三个必做动作文件写好了怎么确认它真的被加载了别猜用下面三个动作验证。4.1 直接读取技能文件在 Claude Code 对话框输入读取 .claude/skills/tools/md-output.md如果 Claude 能把文件内容完整显示出来说明文件路径和权限都没问题。如果报“文件不存在”或“无权限”回去检查目录拼写和 settings.json 里的 allow 规则。4.2 询问触发逻辑输入我说“按规范输出”会触发什么技能Claude 应该能根据技能文件里的“触发条件”章节告诉你它会匹配到md-output技能。如果它答不上来说明技能文件里的触发条件写得不够明确或者文件没被正确索引。4.3 实际跑一次输入使用 /md-output 技能帮我生成一份项目说明文档的目录结构观察输出H2 是不是## 1.格式代码块有没有标语言。如果格式符合技能文件里的规则说明整条链路通了。我试过在同一个会话里连续触发两次第二次不用重新读文件Claude 会记住上下文里的技能规则。但新开会话就得重新触发这是正常行为。5. 本篇常见错误排查5.1 技能不生效Claude 还是按自己的格式输出最常见的原因是文件没放在正确位置。Claude Code 只认项目根目录下的.claude/skills/放到src/.claude/或者用户主目录都不行。用pwd确认你在项目根目录再ls -la .claude/skills/看文件在不在。另一个原因是技能文件里的“触发条件”写得太模糊。比如只写“用户需要时”Claude 无法判断什么时候算“需要”。改成具体的关键词或斜杠命令比如/md-output、按规范输出。5.2 报错 “Permission denied” 读取技能文件settings.json 里的 allow 规则没写对。检查两点路径是不是.claude/skills/**双星号表示递归匹配子目录JSON 格式有没有语法错误。可以用cat .claude/settings.json | python -m json.tool验证格式。5.3 技能文件里的规则互相冲突比如一个技能说“H2 要编号”另一个说“H2 不编号”同时触发时 Claude 会懵。解决办法是给技能分优先级或者在技能文件里写明“本技能优先级高于默认规则”。更稳妥的做法是避免规则重叠一个技能只管一件事。5.4 修改技能文件后不生效Claude Code 会缓存已读取的技能内容。改完文件后新开会话或者显式重新读取一次文件。如果还不行重启 Claude Code 进程。5.5 API 调用报 401 或连接超时这跟 Skills 无关是接入层的问题。检查ANTHROPIC_API_KEY是否复制完整ANTHROPIC_BASE_URL是否写成https://taotoken.net/api注意结尾没有斜杠。如果 Key 没问题还是 401去 https://taotoken.net/api-keys 确认 Key 状态是否正常。6. 把技能用起来从单文件到团队规范跑通一个技能之后你可以按同样的结构扩展。比如代码审查技能在.claude/skills/review/code-review.md里定义审查维度、严重程度分级、输出格式接口文档技能在.claude/skills/docs/api-doc.md里定义扫描步骤、字段表格、响应示例模板。关键是把“你每次都要重复交代的事”写进去。判断标准很简单如果一件事你已经在对话里说过三遍以上它就值得变成一个技能文件。团队协作时把.claude/skills/提交到 Git 仓库新成员拉下来就能用同一套规范。这比写一份没人看的 Wiki 管用得多因为 Claude 会强制执行这些规则。如果你还没拿到 API Key先去 https://taotoken.net/api-keys 创建一个。想直接体验模型对话效果可以打开 https://taotoken.net/model-chat 试几句。需要长期用 Claude Code 做编码和 Agent 任务的建议了解一下 Coding Plan地址是 https://taotoken.net/coding-plan 按需选择就行。技能系统的本质是把你的经验变成可执行的 Prompt 模板。写第一个的时候可能觉得麻烦写到第三个你就会发现省下来的重复沟通时间远超投入。