最近我一直在用 Claude Code 处理日常开发里的测试编写任务但真正改变工作方式的是理解了 SKILL.md 的作用。最开始 Claude Code 的表现不差但我很快就发现一个很尴尬的问题每换个项目、每换一个需求我都要把“测试文件放哪”“用什么框架”“Mock 怎么打”“边界条件覆盖到什么程度”这些规则从头到尾交代一遍。如果是当天上下文比较长的情况它甚至会忘记开头约定的风格生成的测试前后不一致。后来我去研究 Claude Code 的 skill 机制发现 SKILL.md 才是解决这类问题的关键。它不是一个普通的提示词文件更像一份可以随身携带的操作手册。把测试生成规范写进 SKILL.md 之后Claude Code 会在正确时机自动加载这些规则不用你每次重复描述。这也是我建议真正想长期使用 Claude Code 的人不要只是停留在“让它写一段代码”这个层级而是尽快把重复性工作固化成 skill。这个判断背后是一个朴素的事实和 AI 编程工具协作时最值钱的东西不是某一次问答结果而是你沉淀下来的流程和规范。本文会从安装 Claude Code 开始讲然后重点带你手写一个针对“测试生成”场景的 SKILL.md并给出验证、调试和长期维护的具体方法。1. 先搞清楚 SKILL.md 到底解决什么问题很多人有一个误区觉得 Claude Code 就是一个“能听懂人话的终端助手”。它确实能完成不少任务但如果你深入了解会发现 Claude Code 提供 Skills 这类机制让工具提前拥有一批“专业能力”。一个 skill 通常就是一个目录下的 SKILL.md 文件里面写清楚这个技能的名字、描述、适用场景和执行步骤。Claude Code 会在需要的时候根据描述自动匹配并加载它。1.1 没有 SKILL.md 时测试生成为什么总不稳定没有 SKILL.md 的情况下你等于在靠“临场指令”驱动 Claude Code 写测试。每个项目都有一套习惯要求比如测试文件放同目录还是集中放到测试目录用 pytest、Jest、Vitest 还是其他框架对第三方接口是打桩、Mock 还是走真实调用命名风格是 snake_case 还是 camelCase覆盖率标准、核心分支要求、异常分支覆盖到什么程度。这些约束如果只在对话里提到就会持续消耗上下文如果没提到Claude Code 只能按默认方式猜。结果就是同一个团队里两个人让 Claude Code 生成同样的测试风格可能完全不同。它的能力上限不低但稳定性不足。问题往往不在模型本身而在你没有给它一个稳定的执行框架。1.2 SKILL.md 改变的是执行框架不是单次回答SKILL.md 改变的不是某一次回答的内容而是把“你希望它怎么做一件事”固化成可复用的说明文档。这有点像带新同事你不是每次都说一遍流程而是先写好新人手册让他遇到具体任务时翻对应章节。一旦规则被固化你会明显感觉到几件事上下文占用下降因为规则不需要在每次对话里重述行为更稳定因为同一条 skill 每次加载的内容是一致的可以跨项目复用只要项目结构相近一份 SKILL.md 能随身携带可以纳入版本管理规则变更通过 Git 记录而不是“聊天记录丢了就没了”。1.3 与普通提示词模板的差别在哪有人会问这不就是一个 prompt 模板吗有相似之处但不完全一样。普通提示词模板是你手动复制粘贴到对话里的“一次性说明”。SKILL.md 则是被 Claude Code 识别的程序化技能描述它通过 frontmatter 声明技能名称和描述在正文中写详细步骤。当任务匹配时工具会主动加载它。你不需要每次手动告诉 Claude Code“请参考某个文件执行”。这个“主动加载”是核心差异。如果 description 写得好Claude Code 拿到任务后自己就能判断该用哪个 skill。你只需要说“给 utils 里的函数补一组单测”它会自动按 skill 中的规范去生成。2. 安装 Claude Code 前先确认三层环境很多人卡在第一步是因为把安装理解成了一条命令的事。其实 Claude Code 能不能稳定用起来取决于三层环境Node.js 环境、CLI 工具本身、模型服务连接。任意一层有问题后面都会被卡住。根据常见使用场景最容易出问题的不是安装命令本身而是 Node 版本、模型服务配置和账号权限。下面给出一份通用安装流程。2.1 检查 Node.js 环境Claude Code 的 CLI 主要通过 npm 分发所以前提是机器上有一个可用的 Node.js 环境。一般建议 Node.js 版本不低于当前主流 LTS 版本具体以官方说明为准。可以先确认node -v npm -v如果提示命令不存在说明 Node.js 没有装好先去安装对应版本的 Node.js 再继续。Windows、macOS、Linux 的安装方式不一样但核心都是一样的让node和npm进入系统 PATH。2.2 安装 CLI 工具确认 Node.js 没问题后再安装 Claude Code CLI。通常是一个全局 npm 包包名以官方发布为准常见的安装命令类似npm install -g anthropic-ai/claude-code安装完成后检查是否成功claude --version如果你的系统没有把 npm 全局路径加入 PATH命令可能会找不到。这时候可以手动把 npm 全局 bin 目录加入 PATH或用which claude或where claude确认命令位置。2.3 连接可用的模型服务CLI 装好后关键一步是让 Claude Code 连上可用的模型服务。这里有两种常见路径官方账号登录运行claude后按提示完成登录适合已经具备 Anthropic 官方账号访问权限的用户第三方兼容接口通过环境变量或配置文件指定 API Base 与 API Key适合本地部署、兼容接口等场景。搜索热词里能看到大量“claude code 接入 deepseek”“openrouter 通过 cc-switch 接入 claude code”“配置大模型 api key”之类的查询说明不少人想用非官方默认服务。这个方向是做兼容适配不同模型能力和参数差异很大不一定每个模型都能完整支持 Claude Code 的全部功能。如果使用第三方兼容接口建议先确认接口协议兼容性再跑一个最小任务验证。配置模型接口时常见做法是设置环境变量比如export ANTHROPIC_BASE_URLhttps://your-api-endpoint export ANTHROPIC_AUTH_TOKENyour-api-key不同工具、不同兼容服务环境变量名称可能不同落地前要先去确认当前 Claude Code 版本支持哪些环境变量。如果配置错误通常会看到模型不识别、鉴权失败或请求超时之类报错。还有一个常见陷阱是模型名称配置错误如果当前版本不识别你填写的模型名通常会看到类似“模型名无法被当前版本识别”的报错。这时要先确认兼容服务提供的模型标识而不是怀疑 CLI 没装好。注意如果你同时准备使用多个模型或兼容接口建议先用一个最小任务验证当前模型对后续 skill 文件的执行质量再进入批量生成测试文件的场景。不同模型对同一份技能指令的理解和遵守程度差别可能不小。2.4 在 VS Code 里使用的正确姿势Claude Code 除了在终端直接用也支持 VS Code 插件或桌面版。从搜索热词看“vscode 配置 claude code”这个诉求非常普遍。在实际开发中我建议把终端版和 VS Code 插件定位分开终端版适合跑脚本、批量任务、快速验证VS Code 插件适合边看代码边让 Claude Code 修改代码、生成文件因为它能直接感知编辑器里的项目和文件结构桌面版通常是在图形界面上提供类似能力适合不太习惯终端操作的人。如果装完插件后发现命令不可用优先检查三件事插件是否成功安装且 VS Code 版本是否满足插件要求系统 PATH 中能否找到claude命令是否已经在终端或插件设置里完成登录或 API Key 配置。2.5 一条可复用的安装排查顺序如果你在安装时遇到问题别急着反复卸载重装。按下面这条链路排查先看安装阶段node -v、npm -v是否正常再看 CLI 阶段claude --version能否正常输出再看登录或鉴权阶段运行claude后能否看到有效会话或 API Key再看模型连接输入一句话任务观察是否真的返回结果最后看工具集成VS Code 或桌面版是否能正确调用同一个 CLI。每层有问题就只修那一层。比如出现 Node 相关的路径报错通常是 Node 版本或 PATH 问题如果出现模型相关报错要先确认模型名是否被当前版本识别如果提示账号没有访问权限可能需要确认账号是否具备 Claude Code 使用权限。层级主要检查项常见问题Node.js 环境node -v、npm -v版本过低、PATH 未配置CLI 工具claude --version安装失败、命令找不到模型服务登录状态或 API Key鉴权失败、模型名不识别编辑器集成插件能否调用 CLIPATH 不一致、插件配置未同步3. SKILL.md 的基本结构它不是提示词而是操作手册现在进入主题。SKILL.md 通常是一个 Markdown 文件里面有两大部分头部元信息frontmatter和正文指令。头部元信息负责告诉 Claude Code“这个技能叫什么、什么时候该用它”正文负责告诉 Claude Code“具体要怎么做”。我在整理 SKILL.md 的写法时经常用到一个类比它更像一份“操作手册”而不是一句“咒语”。操作手册会包含适用对象、操作步骤、验收标准SKILL.md 也应该这样设计。3.1 最小可用的 SKILL.md 长什么样一个最小可用的 SKILL.md常见结构如下--- name: generate-tests description: 为项目中的函数、模块或接口生成单元测试遵循项目测试规范。 --- # 测试生成技能 ## 适用场景 - 为单个函数生成测试 - 为整个模块补充测试覆盖 - 修复现有测试 ## 执行步骤 1. 查看项目的测试框架和目录约定 2. 分析待测代码的输入、输出、依赖与边界条件 3. 按项目规范生成测试文件 4. 运行测试并检查是否通过 ## 输出要求 - 测试文件与源文件保持合理的目录关系 - 命名符合项目已有风格 - 覆盖正常路径、异常路径、边界值 - 包含必要的断言避免只写“调用成功”级别的空测试这是一个示例结构具体字段和加载方式要以当前 Claude Code 版本的官方说明为准。重点是理解格式背后的逻辑name是技能唯一标识description是技能触发条件的核心描述Claude Code 主要根据这段文字判断什么时候加载这个 skill正文是实际执行指引越具体越好。3.2 为什么 description 决定技能能不能被触发很多第一次写 SKILL.md 的人会把大部分精力放在正文步骤上对 description 却草草写一句“用于生成测试”。这容易导致 Claude Code 在需要这个技能时没有加载它或者在不需要时错误加载。好的 description 应该写清楚这个技能处理什么任务什么场景下使用什么情况下不要使用有没有明确的关键词或适用范围。比如“当用户要求为 Python 函数生成 pytest 单元测试时使用”就比“生成测试”更容易触发。因为 Claude Code 是依据描述做匹配描述写得太宽技能容易被误用写得太窄可能永远不被触发。3.3 正文要把步骤写到什么程度一句话原则写到让 Claude Code 不必猜测的程度。你可以想象自己在给一个聪明但没有项目记忆的新同事写作业指导。好的执行步骤会包括先读取哪个文件、确认什么信息判断测试框架时看哪个配置文件测试文件写到哪个目录命名规则是什么哪些依赖需要 Mock边界条件要覆盖哪几类完成后如何自检。如果正文里写“写一个高质量测试”这不是操作手册只是愿望。正确写法是具体指标比如“测试需要包含参数校验、超时处理、异常输入三类场景”。4. 从零手写一个“测试生成” SKILL.md下面我们真正动手写一个能用的“测试生成外挂”。我以 Python pytest 为例但方法和结构可以平移到其他语言和测试框架。4.1 先定义技能的触发边界一个实用的测试生成 skill不能只负责“写测试”它还要处理“按什么标准写”“写到哪个目录”“跑完怎么确认”。项目里标准不统一才是测试生成最大的问题。所以这个 SKILL.md 至少要实现三个能力测试前先侦察代码结构和项目约定测试中严格按约定生成文件测试后自动验证并给出结果摘要。4.2 一次完整的 pytest 测试生成技能示例先看一份完整示例--- name: pytest-test-generator description: 当用户要求为 Python 函数或模块生成、补充、修复单元测试时使用。适用于 pytest 项目。不适用于 Cucumber 或接口 E2E 测试。 --- # Pytest 测试生成技能 ## 目标 根据项目已有测试规范为 Python 代码生成可运行、覆盖关键路径的单元测试。 ## 准备阶段 1. 查看项目根目录是否存在 pytest.ini、pyproject.toml、setup.cfg 或 tox.ini读取其中的 pytest 相关配置。 2. 查看现有测试文件分布在 tests/ 目录还是 src 同级目录统计已有命名风格。 3. 分析目标函数或类的源码列出 - 输入参数 - 返回结果 - 外部依赖数据库、HTTP、文件系统、环境变量 - 潜在的异常和边界场景 ## 执行阶段 1. 根据项目已有约定选择测试文件位置。如果 tests/ 目录已存在优先放入 tests/否则优先与被测模块同级创建 test_ 前缀文件。 2. 测试函数命名使用 test_ 前缀测试类名使用 Test 前缀。 3. 外部依赖通过 monkeypatch 或 pytest-mock 进行替换不允许测试代码访问真实网络或数据库。 4. 每个测试函数只验证一个行为避免把多个用例塞进一个大函数。 5. 边界场景必须覆盖空输入、None、超长输入、非法类型、超时、依赖异常等。 6. 断言要具体对返回结果、异常抛出、外部依赖调用次数或参数进行验证。 ## 自检阶段 1. 运行 pytest -q 或项目约定的测试命令。 2. 如果新增测试失败分析失败原因区分是被测代码缺陷还是测试代码问题。 3. 检查新增测试是否覆盖了目标模块的核心分支。 4. 输出测试结果摘要包括通过数量、失败数量、跳过数量和覆盖率变化。 ## 注意事项 - 不要修改被测代码来让测试通过。 - 不要生成只包含一个 pass 语句的空测试。 - 如果项目没有 pytest 配置默认跳过复杂依赖优先测试纯函数逻辑。这份示例的核心价值不是让你的 Claude Code 马上变成测试大师而是给出一个完整思考链路准备、执行、自检、边界。你可以根据自己的项目去增删。4.3 一份可直接复用的字段拆解表为了方便落地我把上述示例拆解成一张表部分作用写作建议name技能唯一标识使用简短 kebab-casedescription触发和过滤条件写清适用和不适用场景准备阶段输出前先侦察读取配置、观察现有测试约定执行阶段明确生成规则文件位置、命名、Mock 策略、断言要求自检阶段验证输出运行测试、分析失败、报告结果注意事项防止跑偏不修被测代码、不写空测试这张表基本就是手写 SKILL.md 的骨架。所有 skill 都可以套这个壳。5. 把 SKILL.md 装进 Claude Code 并验证写了文件不等于有了 skill。你还需要把它放到 Claude Code 会读取的位置并通过实际任务验证它是否真的被触发、真的按规则执行。5.1 按目录组织技能文件常见做法是给每个 skill 建一个独立目录.skills/ pytest-test-generator/ SKILL.md code-review/ SKILL.mdSKILL.md 和它所在的目录名建议保持一致方便管理和调试。如果你用了 VS Code 插件或桌面版还需要确认当前工作区是否能识别这个目录。Claude Code 对不同目录的加载方式可能不一样具体以官方文档为准。注意SKILL.md 的目录位置和识别规则可能随版本变化。写完文件后最好先在一个最小项目里验证确认能加载后再放进正式项目避免“写了半天根本没生效”。5.2 验证技能是否真正生效把 SKILL.md 放好后不要急着直接测一个复杂项目。先用一个最小项目验证三件事能否被识别在对话中明确提到“使用 pytest-test-generator 技能”看 Claude Code 是否回应了 skill 相关内容能否被自动触发不给技能名只提“给 utils.py 里的函数写单元测试”看它是否自动加载能否按规则执行观察生成文件的目录位置、命名、Mock 策略是否与 SKILL.md 中要求一致。如果前两步失败优先检查 description 和目录格式如果第三步失败说明正文还不够具体需要补充规则细节。这是一个从“写完”到“能用”的真实过程不要跳过。5.3 skill 没加载时的排查链路用一条排查链路来总结这类问题先确认 SKILL.md 的 frontmatter 格式完整name 和 description 没有缺漏再确认目录位置和命名符合当前 Claude Code 版本的识别规则再确认 description 是否容易被任务触发是不是写得太宽泛或太狭窄再确认项目上下文里有没有其他同名 skill 冲突最后确认版本兼容当前 Claude Code 版本是否支持 skill 功能。如果遇到“skill 根本没加载”的情况不要先归咎于文件内容。大概率是放错目录或格式问题。先用最小示例排除再逐步加内容。6. 进阶多 SKILL 管理、模板复用与长期维护一个 SKILL.md 跑通之后你会自然想多做几个技能代码审查、错误修复、接口文档生成、数据库迁移脚本生成等。这时候最大的坑不是写不出 SKILL.md而是“技能之间边界混乱、规则漂移、更新后无法验证”。6.1 多技能并存时如何设计边界当你准备同时使用多个 skill 时每个 skill 的 description 要尽量减少重叠。举例来说pytest-test-generator只负责生成和修复单元测试code-review只负责审查代码质量bugfix只负责分析问题并给出修复建议。如果描述写得太接近Claude Code 可能在“补测试”场景里错误加载了“code-review”技能。我的建议是每个技能只做一件事description 里明确写出适用和不适用边界。宁可多建一个 skill也不要写一个大而全的“万能技能”。6.2 抽出一份 SKILL.md 模板骨架手写第一个 SKILL.md 最费时间。写完之后可以把骨架抽成模板后续新技能直接套用--- name: your-skill-name description: 什么任务、什么场景下使用什么场景下不使用。 --- # 技能名称 ## 目标 一句话说明该技能要达成的结果。 ## 准备阶段 1. 第一步需要收集或确认哪些信息 2. 第二步读取哪个配置或源码 ## 执行阶段 1. 明确步骤 2. 明确规则和边界 3. 明确输出格式 ## 自检阶段 1. 如何验证结果 2. 失败时如何处理 3. 输出什么摘要 ## 注意事项 - 防止跑偏的约束 - 不允许做什么这个模板看起来简单但它能倒逼你思考完整流程。很多 SKILL.md 写不好不是因为格式不对而是准备阶段和自检阶段被省略了。6.3 像维护代码一样维护 SKILL.mdSKILL.md 不是一次性写完就完事。当项目框架从 pytest 换成其他测试框架、目录结构调整、团队约定变化时skill 也要跟着更新。建议做三件事把.skills目录纳入 Git 版本管理每次修改都有记录修改后跑一次最小验证任务确认行为符合预期定期清理不再使用的 skill避免目录里堆一堆僵尸技能。如果你把 skill 当作普通文档维护它很快会失效如果把它当作代码维护它才能真正成为长期资产。6.4 这类方案不是万能的最后必须说清楚边界。SKILL.md 能显著提升生成测试的稳定性和规范性但不等于它能解决所有问题高风险模块、加密逻辑、复杂金融合约等场景测试仍然需要人工审查skill 只能约束流程和规则不能保证生成测试一定发现问题不同模型对同一份 SKILL.md 的执行质量可能不同如果项目本身没有可测试性设计再好的 skill 也难写出高质量测试新增测试不通过时需要人判断是被测代码缺陷还是测试代码错误这一点 AI 无法完全替代。对我来说SKILL.md 的长期价值不是“让 Claude Code 自动写测试”而是“让你对测试生成的流程控制能力变强”。它把每个项目里那些隐性约定显式化把每一次临时对话变成可复用的方法论。这个能力比单个测试文件本身更有意义。回到我开头遇到的困扰。自从把测试生成规范写成 SKILL.md 之后我再也不用每次重新解释项目里的测试规则了Claude Code 生成的文件也稳定了很多。但真正让我觉得值得的是我开始用同一种方法沉淀代码审查、接口文档、错误排查这些流程。如果让我给一个最实际的建议不要一口气写十个 skill先挑一个你最近重复最多的任务写一个最小可用的 SKILL.md放到项目里跑通再逐步加规则。这个流程走通一次后面所有 skill 都是同一个套路。测试生成只是一个起点真正好玩的是你终于把 AI 编程工具从一个“随机应变但不够稳定”的聪明助手变成了一个“能遵守你团队规则”的执行者。 Claude Code SKILL.md实战：告别重复提示，固化测试生成流程
最近我一直在用 Claude Code 处理日常开发里的测试编写任务但真正改变工作方式的是理解了 SKILL.md 的作用。最开始 Claude Code 的表现不差但我很快就发现一个很尴尬的问题每换个项目、每换一个需求我都要把“测试文件放哪”“用什么框架”“Mock 怎么打”“边界条件覆盖到什么程度”这些规则从头到尾交代一遍。如果是当天上下文比较长的情况它甚至会忘记开头约定的风格生成的测试前后不一致。后来我去研究 Claude Code 的 skill 机制发现 SKILL.md 才是解决这类问题的关键。它不是一个普通的提示词文件更像一份可以随身携带的操作手册。把测试生成规范写进 SKILL.md 之后Claude Code 会在正确时机自动加载这些规则不用你每次重复描述。这也是我建议真正想长期使用 Claude Code 的人不要只是停留在“让它写一段代码”这个层级而是尽快把重复性工作固化成 skill。这个判断背后是一个朴素的事实和 AI 编程工具协作时最值钱的东西不是某一次问答结果而是你沉淀下来的流程和规范。本文会从安装 Claude Code 开始讲然后重点带你手写一个针对“测试生成”场景的 SKILL.md并给出验证、调试和长期维护的具体方法。1. 先搞清楚 SKILL.md 到底解决什么问题很多人有一个误区觉得 Claude Code 就是一个“能听懂人话的终端助手”。它确实能完成不少任务但如果你深入了解会发现 Claude Code 提供 Skills 这类机制让工具提前拥有一批“专业能力”。一个 skill 通常就是一个目录下的 SKILL.md 文件里面写清楚这个技能的名字、描述、适用场景和执行步骤。Claude Code 会在需要的时候根据描述自动匹配并加载它。1.1 没有 SKILL.md 时测试生成为什么总不稳定没有 SKILL.md 的情况下你等于在靠“临场指令”驱动 Claude Code 写测试。每个项目都有一套习惯要求比如测试文件放同目录还是集中放到测试目录用 pytest、Jest、Vitest 还是其他框架对第三方接口是打桩、Mock 还是走真实调用命名风格是 snake_case 还是 camelCase覆盖率标准、核心分支要求、异常分支覆盖到什么程度。这些约束如果只在对话里提到就会持续消耗上下文如果没提到Claude Code 只能按默认方式猜。结果就是同一个团队里两个人让 Claude Code 生成同样的测试风格可能完全不同。它的能力上限不低但稳定性不足。问题往往不在模型本身而在你没有给它一个稳定的执行框架。1.2 SKILL.md 改变的是执行框架不是单次回答SKILL.md 改变的不是某一次回答的内容而是把“你希望它怎么做一件事”固化成可复用的说明文档。这有点像带新同事你不是每次都说一遍流程而是先写好新人手册让他遇到具体任务时翻对应章节。一旦规则被固化你会明显感觉到几件事上下文占用下降因为规则不需要在每次对话里重述行为更稳定因为同一条 skill 每次加载的内容是一致的可以跨项目复用只要项目结构相近一份 SKILL.md 能随身携带可以纳入版本管理规则变更通过 Git 记录而不是“聊天记录丢了就没了”。1.3 与普通提示词模板的差别在哪有人会问这不就是一个 prompt 模板吗有相似之处但不完全一样。普通提示词模板是你手动复制粘贴到对话里的“一次性说明”。SKILL.md 则是被 Claude Code 识别的程序化技能描述它通过 frontmatter 声明技能名称和描述在正文中写详细步骤。当任务匹配时工具会主动加载它。你不需要每次手动告诉 Claude Code“请参考某个文件执行”。这个“主动加载”是核心差异。如果 description 写得好Claude Code 拿到任务后自己就能判断该用哪个 skill。你只需要说“给 utils 里的函数补一组单测”它会自动按 skill 中的规范去生成。2. 安装 Claude Code 前先确认三层环境很多人卡在第一步是因为把安装理解成了一条命令的事。其实 Claude Code 能不能稳定用起来取决于三层环境Node.js 环境、CLI 工具本身、模型服务连接。任意一层有问题后面都会被卡住。根据常见使用场景最容易出问题的不是安装命令本身而是 Node 版本、模型服务配置和账号权限。下面给出一份通用安装流程。2.1 检查 Node.js 环境Claude Code 的 CLI 主要通过 npm 分发所以前提是机器上有一个可用的 Node.js 环境。一般建议 Node.js 版本不低于当前主流 LTS 版本具体以官方说明为准。可以先确认node -v npm -v如果提示命令不存在说明 Node.js 没有装好先去安装对应版本的 Node.js 再继续。Windows、macOS、Linux 的安装方式不一样但核心都是一样的让node和npm进入系统 PATH。2.2 安装 CLI 工具确认 Node.js 没问题后再安装 Claude Code CLI。通常是一个全局 npm 包包名以官方发布为准常见的安装命令类似npm install -g anthropic-ai/claude-code安装完成后检查是否成功claude --version如果你的系统没有把 npm 全局路径加入 PATH命令可能会找不到。这时候可以手动把 npm 全局 bin 目录加入 PATH或用which claude或where claude确认命令位置。2.3 连接可用的模型服务CLI 装好后关键一步是让 Claude Code 连上可用的模型服务。这里有两种常见路径官方账号登录运行claude后按提示完成登录适合已经具备 Anthropic 官方账号访问权限的用户第三方兼容接口通过环境变量或配置文件指定 API Base 与 API Key适合本地部署、兼容接口等场景。搜索热词里能看到大量“claude code 接入 deepseek”“openrouter 通过 cc-switch 接入 claude code”“配置大模型 api key”之类的查询说明不少人想用非官方默认服务。这个方向是做兼容适配不同模型能力和参数差异很大不一定每个模型都能完整支持 Claude Code 的全部功能。如果使用第三方兼容接口建议先确认接口协议兼容性再跑一个最小任务验证。配置模型接口时常见做法是设置环境变量比如export ANTHROPIC_BASE_URLhttps://your-api-endpoint export ANTHROPIC_AUTH_TOKENyour-api-key不同工具、不同兼容服务环境变量名称可能不同落地前要先去确认当前 Claude Code 版本支持哪些环境变量。如果配置错误通常会看到模型不识别、鉴权失败或请求超时之类报错。还有一个常见陷阱是模型名称配置错误如果当前版本不识别你填写的模型名通常会看到类似“模型名无法被当前版本识别”的报错。这时要先确认兼容服务提供的模型标识而不是怀疑 CLI 没装好。注意如果你同时准备使用多个模型或兼容接口建议先用一个最小任务验证当前模型对后续 skill 文件的执行质量再进入批量生成测试文件的场景。不同模型对同一份技能指令的理解和遵守程度差别可能不小。2.4 在 VS Code 里使用的正确姿势Claude Code 除了在终端直接用也支持 VS Code 插件或桌面版。从搜索热词看“vscode 配置 claude code”这个诉求非常普遍。在实际开发中我建议把终端版和 VS Code 插件定位分开终端版适合跑脚本、批量任务、快速验证VS Code 插件适合边看代码边让 Claude Code 修改代码、生成文件因为它能直接感知编辑器里的项目和文件结构桌面版通常是在图形界面上提供类似能力适合不太习惯终端操作的人。如果装完插件后发现命令不可用优先检查三件事插件是否成功安装且 VS Code 版本是否满足插件要求系统 PATH 中能否找到claude命令是否已经在终端或插件设置里完成登录或 API Key 配置。2.5 一条可复用的安装排查顺序如果你在安装时遇到问题别急着反复卸载重装。按下面这条链路排查先看安装阶段node -v、npm -v是否正常再看 CLI 阶段claude --version能否正常输出再看登录或鉴权阶段运行claude后能否看到有效会话或 API Key再看模型连接输入一句话任务观察是否真的返回结果最后看工具集成VS Code 或桌面版是否能正确调用同一个 CLI。每层有问题就只修那一层。比如出现 Node 相关的路径报错通常是 Node 版本或 PATH 问题如果出现模型相关报错要先确认模型名是否被当前版本识别如果提示账号没有访问权限可能需要确认账号是否具备 Claude Code 使用权限。层级主要检查项常见问题Node.js 环境node -v、npm -v版本过低、PATH 未配置CLI 工具claude --version安装失败、命令找不到模型服务登录状态或 API Key鉴权失败、模型名不识别编辑器集成插件能否调用 CLIPATH 不一致、插件配置未同步3. SKILL.md 的基本结构它不是提示词而是操作手册现在进入主题。SKILL.md 通常是一个 Markdown 文件里面有两大部分头部元信息frontmatter和正文指令。头部元信息负责告诉 Claude Code“这个技能叫什么、什么时候该用它”正文负责告诉 Claude Code“具体要怎么做”。我在整理 SKILL.md 的写法时经常用到一个类比它更像一份“操作手册”而不是一句“咒语”。操作手册会包含适用对象、操作步骤、验收标准SKILL.md 也应该这样设计。3.1 最小可用的 SKILL.md 长什么样一个最小可用的 SKILL.md常见结构如下--- name: generate-tests description: 为项目中的函数、模块或接口生成单元测试遵循项目测试规范。 --- # 测试生成技能 ## 适用场景 - 为单个函数生成测试 - 为整个模块补充测试覆盖 - 修复现有测试 ## 执行步骤 1. 查看项目的测试框架和目录约定 2. 分析待测代码的输入、输出、依赖与边界条件 3. 按项目规范生成测试文件 4. 运行测试并检查是否通过 ## 输出要求 - 测试文件与源文件保持合理的目录关系 - 命名符合项目已有风格 - 覆盖正常路径、异常路径、边界值 - 包含必要的断言避免只写“调用成功”级别的空测试这是一个示例结构具体字段和加载方式要以当前 Claude Code 版本的官方说明为准。重点是理解格式背后的逻辑name是技能唯一标识description是技能触发条件的核心描述Claude Code 主要根据这段文字判断什么时候加载这个 skill正文是实际执行指引越具体越好。3.2 为什么 description 决定技能能不能被触发很多第一次写 SKILL.md 的人会把大部分精力放在正文步骤上对 description 却草草写一句“用于生成测试”。这容易导致 Claude Code 在需要这个技能时没有加载它或者在不需要时错误加载。好的 description 应该写清楚这个技能处理什么任务什么场景下使用什么情况下不要使用有没有明确的关键词或适用范围。比如“当用户要求为 Python 函数生成 pytest 单元测试时使用”就比“生成测试”更容易触发。因为 Claude Code 是依据描述做匹配描述写得太宽技能容易被误用写得太窄可能永远不被触发。3.3 正文要把步骤写到什么程度一句话原则写到让 Claude Code 不必猜测的程度。你可以想象自己在给一个聪明但没有项目记忆的新同事写作业指导。好的执行步骤会包括先读取哪个文件、确认什么信息判断测试框架时看哪个配置文件测试文件写到哪个目录命名规则是什么哪些依赖需要 Mock边界条件要覆盖哪几类完成后如何自检。如果正文里写“写一个高质量测试”这不是操作手册只是愿望。正确写法是具体指标比如“测试需要包含参数校验、超时处理、异常输入三类场景”。4. 从零手写一个“测试生成” SKILL.md下面我们真正动手写一个能用的“测试生成外挂”。我以 Python pytest 为例但方法和结构可以平移到其他语言和测试框架。4.1 先定义技能的触发边界一个实用的测试生成 skill不能只负责“写测试”它还要处理“按什么标准写”“写到哪个目录”“跑完怎么确认”。项目里标准不统一才是测试生成最大的问题。所以这个 SKILL.md 至少要实现三个能力测试前先侦察代码结构和项目约定测试中严格按约定生成文件测试后自动验证并给出结果摘要。4.2 一次完整的 pytest 测试生成技能示例先看一份完整示例--- name: pytest-test-generator description: 当用户要求为 Python 函数或模块生成、补充、修复单元测试时使用。适用于 pytest 项目。不适用于 Cucumber 或接口 E2E 测试。 --- # Pytest 测试生成技能 ## 目标 根据项目已有测试规范为 Python 代码生成可运行、覆盖关键路径的单元测试。 ## 准备阶段 1. 查看项目根目录是否存在 pytest.ini、pyproject.toml、setup.cfg 或 tox.ini读取其中的 pytest 相关配置。 2. 查看现有测试文件分布在 tests/ 目录还是 src 同级目录统计已有命名风格。 3. 分析目标函数或类的源码列出 - 输入参数 - 返回结果 - 外部依赖数据库、HTTP、文件系统、环境变量 - 潜在的异常和边界场景 ## 执行阶段 1. 根据项目已有约定选择测试文件位置。如果 tests/ 目录已存在优先放入 tests/否则优先与被测模块同级创建 test_ 前缀文件。 2. 测试函数命名使用 test_ 前缀测试类名使用 Test 前缀。 3. 外部依赖通过 monkeypatch 或 pytest-mock 进行替换不允许测试代码访问真实网络或数据库。 4. 每个测试函数只验证一个行为避免把多个用例塞进一个大函数。 5. 边界场景必须覆盖空输入、None、超长输入、非法类型、超时、依赖异常等。 6. 断言要具体对返回结果、异常抛出、外部依赖调用次数或参数进行验证。 ## 自检阶段 1. 运行 pytest -q 或项目约定的测试命令。 2. 如果新增测试失败分析失败原因区分是被测代码缺陷还是测试代码问题。 3. 检查新增测试是否覆盖了目标模块的核心分支。 4. 输出测试结果摘要包括通过数量、失败数量、跳过数量和覆盖率变化。 ## 注意事项 - 不要修改被测代码来让测试通过。 - 不要生成只包含一个 pass 语句的空测试。 - 如果项目没有 pytest 配置默认跳过复杂依赖优先测试纯函数逻辑。这份示例的核心价值不是让你的 Claude Code 马上变成测试大师而是给出一个完整思考链路准备、执行、自检、边界。你可以根据自己的项目去增删。4.3 一份可直接复用的字段拆解表为了方便落地我把上述示例拆解成一张表部分作用写作建议name技能唯一标识使用简短 kebab-casedescription触发和过滤条件写清适用和不适用场景准备阶段输出前先侦察读取配置、观察现有测试约定执行阶段明确生成规则文件位置、命名、Mock 策略、断言要求自检阶段验证输出运行测试、分析失败、报告结果注意事项防止跑偏不修被测代码、不写空测试这张表基本就是手写 SKILL.md 的骨架。所有 skill 都可以套这个壳。5. 把 SKILL.md 装进 Claude Code 并验证写了文件不等于有了 skill。你还需要把它放到 Claude Code 会读取的位置并通过实际任务验证它是否真的被触发、真的按规则执行。5.1 按目录组织技能文件常见做法是给每个 skill 建一个独立目录.skills/ pytest-test-generator/ SKILL.md code-review/ SKILL.mdSKILL.md 和它所在的目录名建议保持一致方便管理和调试。如果你用了 VS Code 插件或桌面版还需要确认当前工作区是否能识别这个目录。Claude Code 对不同目录的加载方式可能不一样具体以官方文档为准。注意SKILL.md 的目录位置和识别规则可能随版本变化。写完文件后最好先在一个最小项目里验证确认能加载后再放进正式项目避免“写了半天根本没生效”。5.2 验证技能是否真正生效把 SKILL.md 放好后不要急着直接测一个复杂项目。先用一个最小项目验证三件事能否被识别在对话中明确提到“使用 pytest-test-generator 技能”看 Claude Code 是否回应了 skill 相关内容能否被自动触发不给技能名只提“给 utils.py 里的函数写单元测试”看它是否自动加载能否按规则执行观察生成文件的目录位置、命名、Mock 策略是否与 SKILL.md 中要求一致。如果前两步失败优先检查 description 和目录格式如果第三步失败说明正文还不够具体需要补充规则细节。这是一个从“写完”到“能用”的真实过程不要跳过。5.3 skill 没加载时的排查链路用一条排查链路来总结这类问题先确认 SKILL.md 的 frontmatter 格式完整name 和 description 没有缺漏再确认目录位置和命名符合当前 Claude Code 版本的识别规则再确认 description 是否容易被任务触发是不是写得太宽泛或太狭窄再确认项目上下文里有没有其他同名 skill 冲突最后确认版本兼容当前 Claude Code 版本是否支持 skill 功能。如果遇到“skill 根本没加载”的情况不要先归咎于文件内容。大概率是放错目录或格式问题。先用最小示例排除再逐步加内容。6. 进阶多 SKILL 管理、模板复用与长期维护一个 SKILL.md 跑通之后你会自然想多做几个技能代码审查、错误修复、接口文档生成、数据库迁移脚本生成等。这时候最大的坑不是写不出 SKILL.md而是“技能之间边界混乱、规则漂移、更新后无法验证”。6.1 多技能并存时如何设计边界当你准备同时使用多个 skill 时每个 skill 的 description 要尽量减少重叠。举例来说pytest-test-generator只负责生成和修复单元测试code-review只负责审查代码质量bugfix只负责分析问题并给出修复建议。如果描述写得太接近Claude Code 可能在“补测试”场景里错误加载了“code-review”技能。我的建议是每个技能只做一件事description 里明确写出适用和不适用边界。宁可多建一个 skill也不要写一个大而全的“万能技能”。6.2 抽出一份 SKILL.md 模板骨架手写第一个 SKILL.md 最费时间。写完之后可以把骨架抽成模板后续新技能直接套用--- name: your-skill-name description: 什么任务、什么场景下使用什么场景下不使用。 --- # 技能名称 ## 目标 一句话说明该技能要达成的结果。 ## 准备阶段 1. 第一步需要收集或确认哪些信息 2. 第二步读取哪个配置或源码 ## 执行阶段 1. 明确步骤 2. 明确规则和边界 3. 明确输出格式 ## 自检阶段 1. 如何验证结果 2. 失败时如何处理 3. 输出什么摘要 ## 注意事项 - 防止跑偏的约束 - 不允许做什么这个模板看起来简单但它能倒逼你思考完整流程。很多 SKILL.md 写不好不是因为格式不对而是准备阶段和自检阶段被省略了。6.3 像维护代码一样维护 SKILL.mdSKILL.md 不是一次性写完就完事。当项目框架从 pytest 换成其他测试框架、目录结构调整、团队约定变化时skill 也要跟着更新。建议做三件事把.skills目录纳入 Git 版本管理每次修改都有记录修改后跑一次最小验证任务确认行为符合预期定期清理不再使用的 skill避免目录里堆一堆僵尸技能。如果你把 skill 当作普通文档维护它很快会失效如果把它当作代码维护它才能真正成为长期资产。6.4 这类方案不是万能的最后必须说清楚边界。SKILL.md 能显著提升生成测试的稳定性和规范性但不等于它能解决所有问题高风险模块、加密逻辑、复杂金融合约等场景测试仍然需要人工审查skill 只能约束流程和规则不能保证生成测试一定发现问题不同模型对同一份 SKILL.md 的执行质量可能不同如果项目本身没有可测试性设计再好的 skill 也难写出高质量测试新增测试不通过时需要人判断是被测代码缺陷还是测试代码错误这一点 AI 无法完全替代。对我来说SKILL.md 的长期价值不是“让 Claude Code 自动写测试”而是“让你对测试生成的流程控制能力变强”。它把每个项目里那些隐性约定显式化把每一次临时对话变成可复用的方法论。这个能力比单个测试文件本身更有意义。回到我开头遇到的困扰。自从把测试生成规范写成 SKILL.md 之后我再也不用每次重新解释项目里的测试规则了Claude Code 生成的文件也稳定了很多。但真正让我觉得值得的是我开始用同一种方法沉淀代码审查、接口文档、错误排查这些流程。如果让我给一个最实际的建议不要一口气写十个 skill先挑一个你最近重复最多的任务写一个最小可用的 SKILL.md放到项目里跑通再逐步加规则。这个流程走通一次后面所有 skill 都是同一个套路。测试生成只是一个起点真正好玩的是你终于把 AI 编程工具从一个“随机应变但不够稳定”的聪明助手变成了一个“能遵守你团队规则”的执行者。