ClaudeCode 是 Anthropic 推出的终端 AI 编程助手它把对话、文件编辑、命令执行和 agent 能力组合在一起。在用它完成真实项目时很多人很快会遇到一个瓶颈模型虽然很强但并不知道你们团队的命名规范、测试策略、提交信息格式和发布流程。Skills 就是为了解决这个问题而设计的技能包机制。本文以“自动化测试”为实战场景从零开发一个可运行的 Skills 技能包讲清楚 SKILL.md 如何编写、技能包如何安装加载、权限如何配置以及不触发时如何排查。最终你可以把团队里重复的“写测试、跑检查、生成提交信息”这类流程固化成 ClaudeCode 能自动执行的技能包。1. ClaudeCode Skills 到底是什么1.1 从终端助手到“带手册的终端助手”ClaudeCode 本质上是一个运行在终端里的 AI agent。它可以读取项目文件、编辑代码、执行命令并根据上下文持续完成任务。单独使用它时模型能力来自通用训练数据一旦进入具体项目它缺少的是“项目里约定俗成的东西”。例如一个 Python 业务项目可能有这些约定单元测试必须放在tests/目录并以test_开头命名。金额计算必须使用Decimal禁止使用float。提交信息必须遵循 Conventional Commits 格式。运行测试前先执行make lint。这些规则很难在每次对话开头都重新描述一遍。Skills 通过一个目录加一个SKILL.md文件把这类“操作手册”固化下来。当用户的请求命中技能描述时ClaudeCode 会把SKILL.md的内容注入到模型上下文中相当于给 agent 临时配了一本工作手册。通俗地理解Skills 不是一段会被直接执行的代码而是一份给 AI 看的说明书。说明书里可以写步骤、规则、检查清单、常见坑也可以指向同目录下的模板和脚本。1.2 Skills、MCP 和普通 Prompt 的边界很多人在接触 Skills 时会混淆它和 MCP、普通 Prompt 的关系。这里用一个表格做区分机制解决什么问题本质典型交付物普通 Prompt一次对话中的临时指示写在对话里的自然语言无固定载体Skills把可复用的工作流程固化给 AI目录 Markdown 说明书.claude/skills/skill-name/SKILL.mdMCP让 AI 接入外部工具和数据源JSON-RPC 协议服务MCP Server 配置简单来说Prompt 是一次性的Skills 是持久化的MCP 是扩展 AI 能“碰到的外部世界”的。实际项目中三者可以配合Skills 定义流程MCP 提供数据库、浏览器、内部 API 等能力。1.3 Skills 的运行机制ClaudeCode 会在启动时扫描技能目录。常见的位置有两个用户级目录~/.claude/skills/对当前用户的所有项目生效。项目级目录.claude/skills/只对当前项目生效。每个技能包是一个子目录目录名通常是技能名称。子目录下必须有SKILL.md文件。SKILL.md顶部包含 YAML frontmatter其中description字段非常关键。ClaudeCode 会根据用户请求和技能描述之间的语义匹配来判断是否加载这个技能。也就是说description写得越清楚技能被正确触发的概率越高。SKILL.md的正文部分则是真正的“工作手册”。模型不会按代码逻辑执行它而是把它作为指令来理解。因此正文里写的不是函数而是清晰的分步步骤、约束条件和验收标准。注意不要把 SKILL.md 写成一篇泛泛的技术文章也不要堆砌关键词。它需要像一个新同事入职时收到的“岗位操作手册”让模型读完就知道该按什么顺序做什么事。2. 环境准备安装 ClaudeCode 并验证2.1 安装与版本检查ClaudeCode 最常见的安装方式是通过 npm 全局安装。执行npm install -g anthropic-ai/claude-code安装完成后检查版本claude --version如果命令行提示找不到claude通常是 npm 全局 bin 目录没有加入PATH。在 Windows 上可以检查 npm 的全局路径npm prefix -g然后把输出的目录加入系统环境变量。在 macOS 或 Linux 上可以检查~/.npm-global/bin这类路径是否在PATH中。ClaudeCode 还提供桌面端和本地安装包具体安装入口以官方发布页为准。无论哪种方式只要能在终端里输入claude命令并打开交互界面就说明基础环境可用。2.2 创建技能目录建议在项目内创建技能目录把技能包和项目代码放在一起方便版本管理。以一个名为demo_project的 Python 项目为例mkdir -p demo_project/.claude/skills cd demo_project之后每个技能都放在.claude/skills/下的独立子目录中。例如demo_project/ ├── .claude/ │ └── skills/ │ └── pytest-runner/ │ └── SKILL.md ├── utils.py └── tests/如果技能需要附带模板或脚本可以继续在技能包里增加子目录pytest-runner/ ├── SKILL.md ├── scripts/ │ └── create_test_from_function.py └── templates/ └── test_function_template.py这些资源文件会被模型读取到。SKILL.md里可以直接告诉模型“生成测试时参考templates/下的模板文件”模型会根据指令去读取对应文件。2.3 权限模式解决“一直点确认”使用 ClaudeCode 时默认情况下模型执行文件编辑、运行命令等操作前可能会要求用户确认。在自动化脚本和技能包场景里频繁确认会打断工作流。ClaudeCode 提供了权限模式参数例如claude --permission-mode acceptEdits这个模式可以让模型在编辑文件时不再逐个询问。更精细的控制是通过工具白名单实现例如只允许运行测试相关的命令claude --allowedTools Bash(python -m pytest*), Bash(git diff*), Edit权限模式的选择需要结合场景模式或参数适用场景风险默认交互确认学习、调试、不熟悉项目最安全但是操作链路长acceptEdits信任模型做代码修改需要代码评审兜底--allowedTools白名单自动化回归、CI 场景命令白名单写错会导致任务失败完全放行所有操作不建议使用一旦模型误删文件或执行危险命令后果不可控实际项目中不要为了省事直接放行全部操作。更稳妥的方式是配置“允许编辑项目内文件、运行测试命令、读取 git 状态”但禁止rm -rf等危险操作。具体参数名和写法会随版本调整落地前先执行claude --help查看当前版本支持的模式。2.4 环境检查清单在开始写 SKILL.md 前先按清单确认环境避免后面排查时混淆问题Node.js 和 npm 已安装node -v可正常输出。claude --version能输出版本号。当前项目目录可以进入 ClaudeCode 交互界面。.claude/skills/目录已创建。已想清楚权限模式开发时用acceptEdits加速生产环境用白名单。提示如果只是想学习技能包开发优先在项目级.claude/skills/下操作。这样不会污染全局技能库出问题时删除目录即可。3. 实战目标做一个自动化测试技能包3.1 先看最小项目结构接下来开发一个名为pytest-runner的技能包。它的任务是当用户指定一个 Python 函数时自动生成 pytest 测试文件、运行测试并输出结果。最小项目结构如下demo_project/ ├── .claude/ │ └── skills/ │ └── pytest-runner/ │ └── SKILL.md ├── utils.py ├── requirements.txt └── tests/先准备一个简单的 Python 业务函数utils.pyfrom decimal import Decimal def add(a, b): Return the sum of a and b. return Decimal(str(a)) Decimal(str(b)) def divide(a, b): Return the quotient of a divided by b. if b 0: raise ValueError(b must not be zero) return Decimal(str(a)) / Decimal(str(b))这个例子故意包含了两个函数一个正常加法一个需要处理除零异常。这样技能包在生成测试时才能覆盖正常分支和异常分支。3.2 编写 SKILL.md 的 frontmatterSKILL.md的第一部分是 YAML frontmatter至少包含name和description两个字段。示例--- name: pytest-runner description: 当用户需要对 Python 函数生成单元测试、运行 pytest 测试并输出测试报告时使用。适用于工具函数、业务函数和接口函数。 ---name是技能包名称建议使用小写英文加连字符。description决定了技能是否被触发。它应该回答三个问题这个技能是干什么的在什么场景下用有什么输入和输出不要把 description 写成“这是一个测试工具”这种宽泛描述。比如下面两种写法写法一不够清晰description: 用于测试。写法二推荐description: 当用户需要对 Python 函数生成单元测试并运行 pytest 时使用。包括分析函数输入输出、生成 tests/test_*.py 文件、执行 pytest 和汇总结果。第二种写法让模型更容易在用户请求中匹配到“给 xx 函数写测试并运行”这类意图。3.3 编写 SKILL.md 的 bodyfrontmatter 下方是正文。正文中的 Markdown 内容会被模型当作操作指令。建议按“身份 - 触发条件 - 流程 - 约束 - 输出格式”的结构写。下面是一份可用的SKILL.md示例--- name: pytest-runner description: 当用户需要对 Python 函数生成单元测试、运行 pytest 测试并输出测试报告时使用。适用于工具函数、业务函数和接口函数。 --- # Pytest Runner Skill 你是一个 Python 测试工程师。收到任务后按以下流程执行 1. 定位需要测试的函数阅读函数定义和 docstring确认输入参数、返回值和异常条件。 2. 检查项目根目录是否存在 pyproject.toml、pytest.ini 或 requirements.txt确认测试依赖。 3. 如果项目没有 tests/ 目录先创建目录。 4. 在 tests/ 下生成 test_module.py 文件。测试函数命名必须遵循 test_ 前缀。 5. 测试用例必须覆盖 - 正常输入分支 - 边界值分支 - 异常分支 - 参数类型转换分支。 6. 运行命令python -m pytest --tbshort -q。 7. 如果测试失败阅读失败栈修复测试代码或被测代码然后重新运行。 8. 最终输出测试文件路径、测试命令、通过率和失败用例列表。 约束 - 不要修改 utils.py 中函数名和参数名。 - 不要使用 pytest -s 以外的交互式参数除非用户明确要求。 - 不要在测试代码中打印无关信息。 - 如果被测函数抛出的异常类型不明确先阅读源码确认再生成断言。这里的关键是“流程分步 明确约束”。模型在生成测试时如果缺少“覆盖异常分支”这条指令往往会只写正常用例。加入约束后生成质量会明显提升。3.4 添加资源文件测试模板和辅助脚本SKILL.md本身已经能完成很多工作但遇到复杂场景时可以给技能包附带资源文件。例如假设项目希望所有测试文件都遵循统一模板可以在技能包内创建模板templates/test_function_template.py模板内容示例Auto-generated test template. import pytest def test_function_name_normal(): Test normal branch of function_name. # TODO: add test code assert True def test_function_name_edge(): Test edge branch of function_name. # TODO: add edge case assert True def test_function_name_exception(): Test exception branch of function_name. with pytest.raises(ValueError): # TODO: add code that raises ValueError pass然后在SKILL.md的流程中加上生成测试文件前先读取 templates/test_function_template.py按该模板的结构生成测试代码不要改变文件整体结构。这样技能包就不只是“提示词集合”还包含了项目级规范。模型在执行时会先读取模板再生成测试代码从而保持团队风格一致。如果项目足够大还可以在scripts/下放一个 Python 脚本用于从函数签名自动生成测试骨架。SKILL.md中告诉模型“可以先运行python scripts/create_test_from_function.py utils.py生成骨架再人工补充断言”。这种方式适合批量处理几十个函数的情况。不过要控制复杂度第一个版本建议先用纯文字指令和模板跑通后再考虑脚本。4. 把技能包安装到项目里并实际跑通4.1 安装和验证技能被识别技能包写好之后启动 ClaudeCodeclaude在交互界面中用普通问题验证技能是否已加载。例如输入你现在可以使用哪些技能如果技能包加载成功模型通常会提到pytest-runner。如果它完全没提到先不要继续测试而是回到技能包目录检查命名和路径。不同版本对技能管理命令的支持有差异最稳妥的验证方式就是在对话里直接询问模型或者查看 ClaudeCode 的调试日志。4.2 在 ClaudeCode 中发起自动化任务确认技能已加载后在项目目录中发起任务。假设utils.py中有上面定义的两个函数输入请使用 pytest-runner 技能为 utils.py 中的 add 和 divide 函数生成单元测试并运行 pytest。模型应该会根据SKILL.md中的流程依次执行读取utils.py。检查requirements.txt是否包含 pytest。创建tests/test_utils.py。生成测试用例。运行python -m pytest --tbshort -q。4.3 验证输出正常情况下tests/test_utils.py会生成类似这样的内容import pytest from utils import add, divide def test_add_normal(): assert add(1.5, 2.3) 3.8 def test_divide_normal(): assert divide(10, 4) 2.5 def test_divide_zero(): with pytest.raises(ValueError): divide(10, 0)运行 pytest 后成功结果大致如下3 passed in 0.02s如果模型没有自动运行测试而是只生成了文件可能是权限模式限制了命令执行。此时可以把Bash(python -m pytest*)加入允许列表或者手动运行python -m pytest --tbshort -q4.4 没有触发时的排查顺序如果技能没有生效按以下顺序排查检查项操作判断标准目录路径ls .claude/skills/pytest-runner/必须存在SKILL.md文件名大小写是否完全一致必须是SKILL.md不能是skill.mdfrontmatter用编辑器打开查看name和description是否存在description 描述是否覆盖用户请求意图请求词和描述词是否匹配权限模式查看claude --help当前参数是否允许运行 pytest重启会话修改 SKILL.md 后重启 ClaudeCode技能包是会话开始时扫描的这里最常见的坑是修改了SKILL.md但当前 ClaudeCode 会话还在使用旧上下文。此时退出会话重新进入即可。提示技能包的加载发生在启动阶段修改SKILL.md后一定要重启会话不要指望在同一个会话中立刻生效。5. 扩展自动化多个 Skills 协同实现“提交前检查”5.1 增加 commit-helper 技能单个技能包解决单一任务。真实开发中提交代码前经常要依次执行“运行测试 - 检查 diff - 生成提交信息”。可以再开发一个commit-helper技能让两个技能包协同工作。新建技能目录.claude/skills/commit-helper/SKILL.mdSKILL.md内容示例--- name: commit-helper description: 当用户需要生成 git 提交信息、整理 commit message 或检查提交前状态时使用。适合项目使用 Conventional Commits 规范时调用。 --- # Commit Helper Skill 你是一个熟悉 Conventional Commits 规范的提交信息助手。收到任务后按以下流程执行 1. 先检查当前 git 状态git status --short。 2. 查看暂存区改动git diff --cached --stat如果暂存区为空则查看工作区改动git diff --stat。 3. 阅读改动内容后确定提交类型 - feat新增功能 - fix修复缺陷 - docs文档变更 - style格式调整不影响逻辑 - refactor重构不改功能 - test新增或调整测试 - chore构建过程或辅助工具变动。 4. 按格式输出提交信息type(scope): subject例如 feat(utils): add divide function。 5. 如果项目中有 pytest-runner 技能且用户未明确跳过测试先运行测试再生成提交信息。 约束 - 不要提交任何未暂存文件。 - 不要修改 git 配置。 - 提交信息必须一句话说明改动意图避免空泛词汇。5.2 在 SKILL.md 中调用 Bash 和文件工具commit-helper的流程里涉及git status、git diff、python -m pytest等命令。SKILL.md 作为指令并不执行这些命令真正执行命令的是 ClaudeCode 的 Bash 工具。因此你需要在 SKILL.md 中明确告诉模型“先查看状态再查看 diff再运行测试”。另外为了让模型能够用 Bash 工具当前会话需要拥有命令执行权限。可以在启动 ClaudeCode 时设置白名单claude --allowedTools Bash(git status*), Bash(git diff*), Bash(git add*), Bash(python -m pytest*)注意白名单中的命令模式不要太宽松。比如Bash(git*)会把git push、git reset --hard也放开风险较高。更推荐逐条列出本次流程需要的命令。5.3 一个技能包引用另一个技能包在commit-helper的 SKILL.md 中可以写“如果项目中有 pytest-runner 技能先运行测试再生成提交信息”。ClaudeCode 会在处理请求时发现多个技能都被触发然后按上下文把它们组合起来。这种“技能引用技能”的机制不需要写额外的加载代码只要描述清楚流程即可。实际使用时用户输入可能是帮我检查当前改动跑一遍测试然后生成提交信息。这个请求同时命中了commit-helper和pytest-runner。模型会先调用测试技能生成测试和运行测试再调用提交信息技能生成 commit message。两个技能包在同一个项目目录下共存互不干扰。5.4 自动化边界自动化不是所有事情都适合交给模型。下面的操作即使模型可以执行也建议保留人工确认git push远程推送。生产环境部署。删除数据库或批量修改数据。覆盖他人分支。安装新的系统级依赖。团队落地时可以约定技能包只负责生成命令和提示不直接执行高风险操作。比如commit-helper只生成提交信息由开发者自己执行git commit。这样既能利用 AI 提供效率又能避免失控。6. 常见问题与排查路径6.1 技能包没有被加载现象在 ClaudeCode 中询问“你可以使用哪些技能”模型没有提到自定义技能包。可能原因目录路径不对SKILL.md没有放在.claude/skills/skill-name/下。文件名大小写错误。description为空或字段名拼错。修改完 SKILL.md 后没有重启会话。检查方式find .claude/skills -name SKILL.md如果文件存在用编辑器确认 frontmatter 完整。然后重启 ClaudeCode 再试。6.2 描述不准确导致错误触发现象用户只是讨论测试思路模型却自动生成了测试文件或者用户明确要求测试模型没有触发技能。原因description写得太宽泛或太窄。例如写成“used for testing”会导致任何和测试相关的对话都可能触发写成“只处理金额函数的测试”又会漏掉其他函数。处理建议在description中写清触发条件、输入输出和边界。例如仅当用户请求生成 Python 单元测试并运行 pytest 时使用。不用于讨论测试理论不用于生成非 Python 语言的测试。6.3 模型不按 SKILL.md 执行现象流程写了“先创建 tests 目录”模型却直接在项目根目录生成了测试文件。原因SKILL.md 的指令不够强制或者缺少检查清单。模型在自由生成时容易偏离。改进方法使用“必须”“禁止”等强制性词汇。把步骤编号并让模型每完成一步就输出一个状态标记。在技能包中加入“自检清单”。自检清单可以写在 SKILL.md 末尾## 完成前自检 - 测试文件是否在 tests/ 目录下 - 测试文件名是否以 test_ 开头 - 是否覆盖了正常、边界和异常分支 - 是否运行了 python -m pytest --tbshort -q6.4 Windows 环境差异ClaudeCode 在 Windows 上需要注意几个容易踩坑的点问题原因处理命令找不到claudenpm 全局目录不在 PATH执行npm prefix -g并配置环境变量路径包含空格导致命令失败项目目录名含空格或中文在 SKILL.md 中要求模型对路径加引号PowerShell 与 bash 命令不同SKILL.md 中示例使用 Unix 命令在 Windows 项目里明确要求使用 PowerShell 兼容语法node 版本过低旧版本不兼容升级 Node.js LTS 版本具体版本要求以官方文档为准如果你的团队同时有 Windows 和 macOS 开发者建议在 SKILL.md 中不要写死命令语法而是写“根据当前操作系统选择兼容的命令”。7. Skills 开发最佳实践7.1 SKILL.md 写作规范一个高质量的 SKILL.md 应该有清晰的结构技能角色让模型知道“你是谁”。目标要完成什么任务。流程分步执行顺序。约束不能做什么。输出格式最终交付什么样。自检清单检查是否完成。避免把 SKILL.md 写成散文。模型在上下文里读取时结构化的 Markdown 比连续段落更容易被遵守。同时避免把团队内部所有历史规则都堆进去技能包只保留当前任务相关的部分。7.2 把技能包纳入版本管理.claude/skills/目录应该提交到 Git 仓库这样团队每个成员拉取代码后能获得相同的技能包。推荐在README.md或docs/中说明技能包的使用方式。团队协作时的目录建议docs/ skills/ pytest-runner.md commit-helper.md .claude/ skills/ pytest-runner/ SKILL.md commit-helper/ SKILL.md同时要注意不要在技能包中写入密钥、token、内网地址等敏感信息。SKILL.md 是给模型看的说明书也可能被团队成员和 CI 系统读取。7.3 为 Skills 做回归测试技能包是代码也需要测试。最直接的办法是准备一组典型输入 prompt每次修改 SKILL.md 后都跑一遍测试用例输入 prompt预期表现基本触发“为 utils.py 生成测试并运行”生成测试文件并执行 pytest异常分支“测试 divide 的除零场景”生成pytest.raises(ValueError)断言不误触发“帮我 review 一下测试设计”不生成测试文件而是给出建议可以把这些用例记录到docs/skills-regression.md作为技能包改版时的回归清单。7.4 最小权限原则技能包可以指示模型执行命令但权限仍控制在 ClaudeCode 的权限层。团队落地时建议只在技能包需要的命令范围内开放 Bash 权限。不开放sudo、curl下载、rm -rf等高风险命令。重要环境使用只读模式或plan模式下验证技能包是否设计合理。对 CI 或自动化流程使用独立的低权限账号运行 ClaudeCode。8. 收尾从技能包到团队自动化平台8.1 下一步扩展Skills 技能包可以逐渐从“生成测试”“生成提交信息”扩展到更多场景代码规范检查按项目 ESLint 规则扫描改动文件。接口文档生成根据函数签名生成 Markdown 文档。数据库迁移检查分析 SQL 变更文件并输出影响范围。发布检查按发布清单逐项确认版本号、变更日志和构建状态。当技能包需要访问外部系统时可以配合 MCP 使用。例如写一个 MCP Server 让 ClaudeCode 读取 Jenkins 构建状态再由技能包根据构建结果决定是否继续生成提交信息。这样 Skills 负责流程MCP 负责连通性形成相对完整的自动化链路。8.2 实践建议第一次接触 Skills 时不要一上来就写一个“全自动发布技能”。建议按这个顺序练习先写一个只有一个SKILL.md的最小技能包跑通“触发-执行-输出”闭环。加入模板文件统一输出格式。加入辅助脚本处理批量任务。设计多技能协同场景。最后再把权限白名单、回归测试和团队文档补齐。Skills 的价值不在于“写了很多个技能包”而在于让 AI 在具体项目里真正按团队的规范工作。把一次有效的对话固化成一个技能包比写一百行“万能提示词”更可靠。下一个项目里再遇到重复劳动就值得停下来想想这个操作能不能做成 ClaudeCode 的 Skills。