1. 为什么你的 Claude Code 需要 Skills 而不是更多提示词Claude Code 用久了会遇到一个瓶颈每次开新会话你都要重新交代一遍项目规范、代码风格、审查标准。提示词写得再细换个会话就归零。Skills 解决的正是这个问题——它把「怎么做事」固化成文件让 Claude Code 在需要时自动加载而不是靠你每次口头重复。Skills 的本质是 SKILL.md 文件放在.claude/skills/目录下。Claude Code 启动时会扫描这个目录读取每个 Skill 的触发条件和执行流程。当你的请求匹配到某个 Skill 的描述时它就会按文件里定义的步骤工作。这跟 MCP 是两套机制MCP 负责「连接外部能力」数据库、API、工具Skills 负责「约束工作流程」先做什么、再做什么、检查什么。两者配合才能让 Claude Code 从「能聊天的编辑器」变成「按规范干活的工程助手」。这篇内容面向已经用过 Claude Code、想用 Skills 增强代码审查和自动化任务能力的开发者。我会给出可复制的 SKILL.md 骨架、MCP 配置片段以及每一项的验证动作。你不需要全部装完挑两三个高频场景先跑通比一次性堆 11 个更有效。2. 前置准备TaoToken 接入与 Skills 目录结构在写 SKILL.md 之前先把模型接入和目录结构理清楚。Claude Code 需要一个可用的 API 端点TaoToken 提供兼容 Anthropic 协议的接入方式配置好之后 Claude Code 的请求会走这个端点。2.1 获取 API Key 并配置环境变量先去控制台创建 API Key然后写入环境变量。不要硬编码在配置文件里避免提交到仓库。# 写入 shell 配置按你的实际 shell 选择文件 echo export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.bashrc echo export ANTHROPIC_API_KEYsk-你的key ~/.bashrc source ~/.bashrc # 验证变量已生效 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8如果你用的是 zsh把~/.bashrc换成~/.zshrc。Windows 用户在系统环境变量里添加这两项即可。2.2 建立 Skills 目录Claude Code 默认扫描项目根目录下的.claude/skills/。每个 Skill 一个子目录目录名就是 Skill 名。mkdir -p .claude/skills ls -la .claude/目录结构长这样项目根/ ├── .claude/ │ ├── skills/ │ │ ├── code-review/ │ │ │ └── SKILL.md │ │ ├── commit-helper/ │ │ │ └── SKILL.md │ │ └── planning-with-files/ │ │ └── SKILL.md │ └── settings.json注意Skills 目录可以放在项目级.claude/skills/也可以放在用户级~/.claude/skills/。项目级只对当前项目生效用户级对所有项目生效。团队协作建议用项目级方便提交到仓库共享。3. SKILL.md 编写规范与可复制骨架SKILL.md 的写法直接决定 Skill 能不能被正确触发。很多人写完发现 Claude Code 根本不加载问题通常出在 frontmatter 的 description 上。3.1 frontmatter 字段说明SKILL.md 开头必须有一段 YAML frontmatter用---包裹。核心字段只有两个字段作用写法要点nameSkill 标识名小写字母加连字符和目录名一致description触发条件描述写清楚「什么时候用」不是「这个 Skill 是什么」description 是最容易写错的地方。Claude Code 靠语义匹配来决定是否加载所以你要写的是触发场景而不是功能简介。比如「当用户要求审查代码改动时使用」比「一个代码审查工具」更容易被匹配到。3.2 完整 SKILL.md 骨架下面是一个代码审查 Skill 的骨架你可以直接复制修改--- name: code-review description: 当用户要求审查代码、检查改动、review diff 或提到代码质量时使用。按逻辑、安全、性能、边界、类型五个维度逐文件审查。 --- # 代码审查 Skill ## 执行流程 1. 先运行 git diff --staged 获取暂存区改动如果没有暂存内容则运行 git diff HEAD~1 2. 逐个文件分析不要跳过任何改动文件 3. 每个问题标注严重程度blocker / major / minor 4. 最后输出汇总表按严重程度排序 ## 审查维度 - 逻辑正确性条件分支是否覆盖完整循环边界是否正确 - 安全漏洞输入校验、SQL 注入、敏感信息硬编码 - 性能问题不必要的循环嵌套、重复计算、内存泄漏 - 边界情况空值、超长输入、并发访问 - 类型安全隐式类型转换、any 滥用、空指针 ## 输出格式 每个问题按以下格式输出 文件:行号 | 严重程度 | 问题描述 | 修复建议写完保存后在 Claude Code 里输入「帮我审查一下暂存的改动」观察它是否按你定义的五个维度输出。如果没有触发检查 description 里是否包含了「审查」这个关键词。3.3 用 skill-creator 生成骨架如果你不想手写可以用 Anthropic 官方的 skill-creator。它通过自然语言描述自动生成 SKILL.md还支持测试迭代。# 添加官方 marketplace /plugin marketplace add anthropics/skills # 安装 skill-creator /plugin install example-skillsanthropic-agent-skills安装后在 Claude Code 里描述你想要的 Skill它会生成文件并让你测试。注意这个包会附带 mcp-builder如果你暂时不构建 MCP 服务器可以忽略那部分。4. MCP 接入配置让 Skills 能调用外部能力Skills 管流程MCP 管能力。当你的 Skill 需要查数据库、调内部 API、读外部文档时就得配 MCP 服务器。Claude Code 的 MCP 配置写在.claude/settings.json或项目根目录的.mcp.json里。4.1 MCP 配置文件片段下面是一个接入本地 MCP 服务器的配置示例用 stdio 传输方式{ mcpServers: { internal-api: { command: node, args: [./mcp-servers/internal-api/index.js], env: { API_BASE: https://internal.example.com, API_TOKEN: ${INTERNAL_API_TOKEN} } }, postgres-readonly: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: ${READONLY_DATABASE_URL} } } } }几个关键点command是启动命令args是参数数组env里可以用${VAR}引用环境变量。不要把 token 明文写进 JSON用环境变量注入。4.2 在 SKILL.md 里引用 MCP 工具配好 MCP 后Skill 里可以直接指示 Claude Code 调用对应的工具。比如一个「查接口文档」的 Skill--- name: api-doc-lookup description: 当用户询问内部 API 的字段含义、请求格式或错误码时使用。通过 internal-api MCP 服务器查询接口文档。 --- # 接口文档查询 Skill ## 执行流程 1. 从用户问题中提取接口名或字段名 2. 调用 internal-api MCP 的 search_endpoint 工具查询 3. 如果返回多个结果列出让用户确认 4. 找到后输出请求示例和字段说明 ## 注意事项 - 只读查询不要调用任何写操作工具 - 如果 MCP 返回超时提示用户检查 internal-api 服务是否启动4.3 验证 MCP 连接配置完成后在 Claude Code 里运行/mcp这会列出当前已连接的 MCP 服务器和可用工具。如果某个服务器显示 failed检查 command 路径是否正确、环境变量是否设置。实测下来最常见的失败原因是npx首次运行需要下载包网络慢导致超时可以先在终端手动跑一次npx -y modelcontextprotocol/server-postgres让它完成下载。5. 逐项验证从 Commit Helper 到 Code Review 的实操装完不验证等于没装。下面按优先级给出几个高频 Skill 的验证动作你跟着做一遍就知道有没有生效。5.1 Commit Helper验证提交信息生成这是性价比最高的一个每天都会用到。它的作用是分析暂存区改动生成符合 Conventional Commits 规范的提交信息。# 先制造一个改动并暂存 echo // test src/utils.js git add src/utils.js然后在 Claude Code 里输入「帮我生成提交信息」。正常输出应该类似refactor(utils): 添加注释占位以便后续补充工具函数说明 - 在 utils.js 末尾添加注释行 - 为后续工具函数实现预留位置如果它只输出了「update utils.js」这种说明 Skill 没加载。检查.claude/skills/commit-helper/SKILL.md是否存在description 里是否包含「提交信息」「commit」等关键词。5.2 Code Review验证多维度审查用上面 3.2 的骨架建好 Skill 后故意写一段有问题的代码function getUser(id) { const query SELECT * FROM users WHERE id id; return db.query(query); }暂存后让 Claude Code 审查。合格的输出应该至少指出SQL 注入风险安全维度、没有输入校验边界维度、缺少错误处理逻辑维度。如果它只说「代码可以优化」说明审查维度没写进 SKILL.md或者 description 没匹配上。5.3 planning-with-files验证跨会话记忆这个 Skill 解决的是长任务跨会话丢失上下文的问题。它强制 Claude Code 维护三个文件task_plan.md、findings.md、progress.md。手动创建 Skill 目录和文件mkdir -p .claude/skills/planning-with-files cat .claude/skills/planning-with-files/SKILL.md EOF --- name: planning-with-files description: 当任务涉及多个步骤、需要跨会话继续、或用户提到计划、进度、继续上次工作时使用。强制维护 task_plan.md、findings.md、progress.md 三个文件。 --- # 文件规划 Skill ## 执行流程 1. 开始任务前先读取 task_plan.md 了解已有计划 2. 每完成一个阶段更新 task_plan.md 的进度 3. 调研结论写入 findings.md 4. 每次会话结束前把操作和错误写入 progress.md 5. 下次会话开始时先读这三个文件再继续 EOF然后给 Claude Code 一个多步骤任务比如「帮我重构 src 目录下的所有工具函数分三步走」。观察它是否创建了这三个文件。如果没创建在对话里明确说「请用 planning-with-files 的方式管理这个任务」。5.4 Batch内置技能直接验证Batch 是 Claude Code 内置的不需要安装。它的作用是把任务拆成独立子单元并行运行并自动创建 PR。适合批量改造场景比如统一接口格式。直接在 Claude Code 里输入/batch 把所有 API 路由的响应格式统一为 { code, data, message }它会先扫描所有路由文件列出改动计划然后并行处理。验证点是看它有没有创建多个分支和 PR。如果只在一个分支上改说明 Batch 没被正确调用检查你的 Claude Code 版本是否支持。6. 常见报错与排查清单Skills 和 MCP 的坑集中在加载失败和触发不匹配两类。下面是我踩过的几个典型问题。Skill 完全不加载先确认目录层级对不对。.claude/skills/code-review/SKILL.md是正确的.claude/skills/code-review.md是错的。frontmatter 的---必须顶格写前面不能有空行。description 匹配不上Claude Code 靠语义匹配不是关键词精确匹配。如果你写「代码审查工具」用户说「帮我看看这段代码有没有问题」可能触发不了。改成「当用户要求审查代码、检查改动、review diff 时使用」覆盖更多说法。MCP 服务器启动失败在终端手动跑一遍 command 和 args看报什么错。常见的是路径不对、依赖没装、环境变量缺失。/mcp命令能看到每个服务器的状态和错误信息。Skill 之间冲突两个 Skill 的 description 都匹配同一个请求时Claude Code 可能只加载一个。解决办法是在 description 里写清楚边界比如「仅当用户明确要求提交信息时使用不要用于代码审查」。修改 SKILL.md 后不生效Claude Code 在会话启动时加载 Skills改完文件需要重启会话。在 Claude Code 里输入/exit退出再重新进入。API 请求超时检查ANTHROPIC_BASE_URL是否设置为https://taotoken.net/api末尾不要带斜杠。如果公司网络有出口限制确认能访问该域名。7. 按场景选择你的 Skills 组合不用一次装 11 个。按你的实际工作流挑每天写代码提交的先装 Commit Helper养成规范提交习惯。需要审查 PR 的加 Code Review用 3.2 的骨架改成你团队的审查维度。做长周期重构的加 planning-with-files解决跨会话记忆问题。需要把内部 API 接进来的再研究 MCP Builder 和 MCP 配置。Superpowers 的流程约束很强适合多文件重构这种复杂任务但快速改一行代码也要走完整流程日常用会觉得繁琐。Ralph-Wiggum 能实现自主循环但必须设--max-iterations和明确停止条件否则可能跑飞产生高额费用建议只在有清晰验收标准的批量任务里用。配置过程中遇到接入问题可以对照接入文档检查环境变量和 MCP 配置想先验证模型对话是否正常用模型对话页面发一条测试请求如果打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 的额度模式比按次调用更划算。先把一个 Skill 跑通再逐步加比一次性堆满更稳。