把 Claude Code 装好第一次问它“帮我写一个用户注册接口”它确实能回复一堆能跑的代码。但等你真正在项目里用起来让它“检查一下这个项目哪里可能出问题”“帮我把这几处重复逻辑抽成公共方法”“给这次改动生成规范的 Commit 信息”它往往会先反问你要看哪个目录、要遵守什么规范。这时候很多人会得出一个结论Claude Code 也不过如此。我的判断是问题不在模型而在你不会给 Claude Code 配置技能。Claude Code 的 Skills 机制就是把“你在项目里反复要做的那几类工作”提前写成一套可复用的指令和脚本。它让 AI 从“你问一句它答一句”的聊天窗口变成一个真正理解你工作习惯的编程助手。这篇文章会把 Claude Code 的技能机制讲清楚并给出 7 个适合新手的 Skills 技能包方向附上可复制的 SKILL.md 模板。你不需要懂复杂的插件开发只要会建文件夹、写 Markdown就能在 10 分钟内跑通第一个技能包。1. 这篇文章真正要解决的问题很多新手在安装 Claude Code 之后很快会卡在这几个场景里生成的 Commit 信息风格五花八门项目历史一团乱让 AI 写单测它每次都把测试写成一个“孤零零的 demo”根本没接入测试框架代码重构时AI 改一个地方另一个地方就漏了让它排查问题它把整个项目从头讲一遍就是没告诉你日志里那行报错真正意味着什么。这些问题看起来是“AI 不够聪明”实际上是“AI 没有被赋予足够的任务规则”。Claude Code 缺的不是智力而是项目上下文、输出格式和操作边界。Skills 恰好能把这三样东西打包好。简单说Skills 是 Claude Code 里的“岗位说明书”。你告诉它这个技能要做什么、按什么步骤做、输出什么格式它就会在任务命中时自动进入对应模式。这篇文章适合三类读者刚接触 Claude Code装了但不知道怎么用到项目里的新手已经用 Claude Code 写代码但对输出质量不满意、想提升稳定性的开发者想给团队统一 AI 编程规范的工程负责人。读完你会掌握Skills 的原理、7 个高频技能包的设计思路、SKILL.md 的标准写法、安装和验证方法以及在实际项目中避坑的具体建议。2. Claude Code Skills 的核心概念与运作原理2.1 什么是 SkillSkill 在 Claude Code 里是一组预先定义好的指令和辅助脚本通常放在项目的.claude/skills/目录下。它不改变模型本身而是改变 AI 被触发后的“任务执行方式”。一个 Skill 由两部分组成SKILL.md技能说明文件包含触发条件、执行步骤、输出规范assets/或scripts/可选配套脚本、模板文件、工具代码。当你在 Claude Code 里用自然语言提出了一个任务Claude 会根据 SKILL.md 中声明的描述和触发字段判断当前任务是否命中这个技能。命中后它会把技能里写的规则当作“额外的系统提示词”来执行。2.2 Skill 和普通 Prompt 的区别很多人会把 Skills 理解成“长一点的 Prompt”这个理解不完整。普通 Prompt 是一段一次性指令每次都要重新粘贴Skill 则是一个可被自动发现、可版本管理、可复用的项目资产。对比一下对比项普通 PromptSkill使用方式每次手动复制粘贴任务命中后自动加载存放位置对话窗口项目目录或用户目录可复用性差换项目就要另写强可跟随项目走可组合性弱只能靠手动补充强可结合多个技能执行复杂流程团队协作难同步可通过代码仓库统一分发理解了这一点你就知道为什么说“技能包是 Claude Code 的进阶玩法”。它把个人经验变成了团队资产。2.3 Claude Code 如何发现技能从目前的机制来看Claude Code 会让 AI 在任务开始时自动扫描可用的技能目录。常用位置包括项目级技能目录.claude/skills/推荐团队项目使用用户级技能目录~/.claude/skills/适合个人长期使用的通用技能。你不需要启动任何服务只要把文件夹和 SKILL.md 放对位置下次启动 Claude Code 就会自动识别。这个设计对新手非常友好因为它没有引入一套复杂的注册流程。2.4 Skill 的适用边界Skill 不是万能的。它最适合解决**“有明确步骤、有固定输出要求”的重复性任务**不适合解决需要大规模自主探索的研究型任务。例如“按照公司规范审查这个文件指出性能问题”就适合写成 Skill“帮我设计一个微服务架构并给出完整的落地文档”就不太适合因为它需要大量上下文判断强行套规则反而会限制 AI。3. 环境准备与前置条件在创建技能包之前先确保 Claude Code 能在你本机正常跑起来。3.1 安装 Claude CodeClaude Code 当前常见的安装方式是通过 npm 安装 CLI 工具。如果你的机器上已经安装了 Node.js可以直接执行npm install -g anthropic-ai/claude-code安装完成后在终端里执行claude --version如果能正常输出版本号说明命令已经生效。如果你的使用方式是基于桌面版或编辑器插件思路也是一样的先确认你本机的 Claude Code 可用再进入项目目录创建技能文件。3.2 登录与权限检查执行claude首次进入会提示登录。你需要用有效的账号完成认证。完成登录后Claude Code 才有权限调用模型接口。这里有一个常见问题如果管理员限制了账号的 Claude Code 访问权限启动时会遇到类似your organization has disabled claude subscription access for claude code的提示。这类情况不是你的本地配置问题而是账号权限问题需要联系管理员确认授权范围。3.3 准备一个测试项目技能包最好在真实项目里创建而不是在空目录里空想。建议先准备一个小项目比如一个简单的 Python 工具库或者 Spring Boot 项目。不需要结构复杂只要能验证技能是否被触发即可。目录结构大致如下my-project/ ├── .claude/ │ └── skills/ │ └── code-reviewer/ │ ├── SKILL.md │ └── review-rules.md ├── src/ └── README.md后面的示例都会以这个结构为基础。4. 第一个技能包从 0 到 1 创建一个 Skill4.1 创建技能目录在项目根目录下执行mkdir -p .claude/skills/code-reviewer把code-reviewer当作你要创建的第一个技能它的作用是“代码审查”。4.2 编写 SKILL.md进入该目录新建SKILL.md--- name: code-reviewer description: 当用户要求审查代码、检查代码质量、查找潜在 Bug 或对代码变更提出建议时使用。 --- # 代码审查员 你是一个严谨的代码审查员。审查代码时必须按以下步骤执行 1. 先定位代码文件确认它属于哪个模块。 2. 分析代码的结构列出实际存在的风险点不要泛泛而谈。 3. 对每一个问题都给出以下信息 - 严重程度高危 / 中危 / 建议 - 问题描述具体到文件和行号 - 修复建议给出可执行的改动思路 4. 如果代码量较大优先检查错误处理、空值判断、资源释放、异常边界。 5. 如果没有发现问题明确说明“未发现明显问题”并解释为什么这么判断。这个文件的核心价值在于它把“审查代码”这个模糊任务拆解成了一个 AI 可以稳定执行的流程。4.3 在 Claude Code 中测试技能启动 Claude Codeclaude然后在对话中输入请帮我审查 src/ 目录下的代码。如果 Skills 机制正常工作Claude Code 会在生成回答时自动利用code-reviewer技能中的审查规则。一个小技巧是在首次测试时把描述写得具体一些“用 code-reviewer 技能审查本次变更的文件”。这样更容易判断到底是技能没生效还是描述没有命中。5. 7 个值得人手一份的 Skills 技能包下面这 7 个技能包是我强烈建议新手优先配置的方向。它们覆盖了日常开发中使用频率最高、最容易被 AI 做“糊弄过去”的任务。我把每个技能包的核心说明和 SKILL.md 片段都整理出来了你可以直接复制后按自己的项目改。5.1 code-reviewer代码审查与风险分析解决的问题让 Claude Code 从“夸代码写得好”变成“真的找出问题”。适用场景提交合并请求前、代码评审时、接手陌生项目时。关键逻辑只允许清单化的输出禁止模糊的“代码整体较好”这类描述。--- name: code-reviewer description: 审查代码质量、定位潜在 Bug、输出结构化评审结论。当用户提到 review、代码审查、质量问题、检查代码时使用。 --- # 代码审查规则 - 每次审查必须输出问题清单格式为严重级别 | 文件位置 | 问题描述 | 修复建议。 - 按优先级排序高危问题列在最前面。 - 不要修改代码只输出评审意见。 - 如果没有发现高危问题必须说明已检查了哪些方面。新手注意给 AI 看的审查要求越具体越好。你希望它检查“空指针”就直接写“检查可能为 null 的变量和外部输入”你希望它关注“并发安全”就明确写“检查共享状态是否存在更新竞争”。5.2 commit-helper生成规范的 Commit 信息解决的问题统一团队提交历史风格告别fix bug、update这类无意义信息。适用场景每次完成代码变更后需要生成符合 Conventional Commits 规范的提交信息。关键逻辑先读取 git diff再分析变更类型最后输出提交信息。--- name: commit-helper description: 根据 git 变更内容生成符合规范的 Commit 信息。当用户提到 commit、提交信息、提交说明时使用。 --- # Commit 信息生成 - 获取当前 git diff先分析变更涉及的功能模块。 - 提交信息格式 - type(scope): subject - type 使用feat / fix / refactor / docs / test / chore / perf。 - subject 必须使用动词开头且不超过 50 个字符。 - 如果涉及破坏性变更在 commit 信息最后说明高风险。5.3 unit-test-builder单元测试生成器解决的问题让 AI 生成“能真跑的测试”而不是“看起来像测试的模板”。适用场景新写了一个工具函数、修复了一个 Bug 需要回归测试、补充项目测试覆盖。关键逻辑先确认代码入口和依赖再基于测试框架生成用例。--- name: unit-test-builder description: 为指定函数或模块生成单元测试。当用户提到单测、单元测试、test case、测试用例时使用。 --- # 单元测试生成规则 - 先确认被测函数的入参、返回值、异常类型和外部依赖。 - 使用项目中已有的测试框架风格不要自创结构。 - 每个测试用例必须包含测试目的、输入数据、预期结果、断言说明。 - 必须覆盖正常场景、边界场景、异常场景。 - 生成完测试代码后给出运行命令。新手注意如果你不告诉它项目用的是 pytest 还是 JUnit 还是 vitest它很可能会生成一个风格完全不同的测试文件。建议在技能描述里直接写清楚测试框架名称。5.4 doc-sync文档同步与更新解决的问题代码改完了README 和接口文档还是旧的。适用场景接口参数调整、模块重命名、功能上线后文档更新。关键逻辑对比代码实现与现有文档只更新差异部分。--- name: doc-sync description: 根据代码变更同步更新 README 或接口文档。当用户提到文档更新、同步文档、更新 README 时使用。 --- # 文档同步规则 - 先读取代码变更对应的文档文件。 - 对比代码与文档不一致的地方列出差异点。 - 逐项修改文档不要重复整个文件的内容。 - 涉及接口文档时记录请求路径、请求参数、响应字段的变化。 - 修改完成后输出一个变更清单方便人工确认。5.5 refactor-master代码重构助手解决的问题AI 重构时一次改得太多或者只改表面不动逻辑。适用场景抽取公共方法、消除重复代码、调整类结构、优化函数长度。关键逻辑重构前先定义“不改运行的验证方式”再开始改动。--- name: refactor-master description: 对目标代码进行安全重构保持外部行为不变。当用户提到重构、抽取方法、消除重复、优化结构时使用。 --- # 重构规则 - 第一步介绍当前代码结构说明要保留的核心逻辑。 - 第二步给出重构方案按文件列出改动点。 - 第三步先输出重构后的核心代码再说明依赖关系变化。 - 重构过程中禁止修改公共接口的签名除非用户明确要求。 - 完成每个文件后都要提示开发如何回归验证。5.6 debug-assistant问题诊断与故障排查解决的问题AI 不给直接答案而是自说自话地给你讲一遍所有可能的报错原因。适用场景程序运行报错、日志出现异常、接口返回不符合预期。关键逻辑要求 AI 先复现问题再给出诊断链不输出无关信息。--- name: debug-assistant description: 辅助排查程序报错、日志异常和运行环境问题。当用户提到报错、异常、排查、deubg、日志分析时使用。 --- # 调试排查规则 - 第一步先读取报错堆栈或相关日志提取关键错误信息。 - 第二步定位到具体文件和代码行分析触发条件。 - 第三步只输出最可能的 3 个原因按可能性排序。 - 第四步为每个原因给出验证方法而不是直接改代码。 - 不要建议删除数据、清空缓存等高危操作除非用户明确要求。5.7 prompt-architect提示词优化与需求拆解解决的问题你已经会用 Claude Code 了但有时候它给你的代码方向不对换个问法结果完全不同。适用场景写新功能提示词时、把模糊需求拆成可执行任务时、给团队其他成员写共享提示词时。关键逻辑把需求转化为目标、约束、输入、输出四要素。--- name: prompt-architect description: 帮助优化 AI 提示词或将模糊需求拆解为可执行的任务描述。当用户提到提示词优化、prompt、需求拆解、写 prompt 时使用。 --- # 提示词优化规则 - 先输出优化后的提示词再解释为什么这样改。 - 优化后的提示词必须包含 1. 任务目标希望 AI 完成什么。 2. 输入信息需要提供哪些文件或上下文。 3. 约束条件不允许做什么、必须满足哪些规范。 4. 输出格式期望返回什么形式的结果。 - 当需求过于模糊时先列出需要用户补充的问题再尝试补全。这 7 个技能包覆盖了“写代码前、写代码中、写代码后”三个主要阶段。新手不需要一次性全部配好先挑一个你当前最痛的方向把它用熟再逐步扩展。6. 技能包的安装与使用两种实操方式很多人在意的“技能安装包”到底怎么装这里要澄清一个最常见的误区Claude Code 技能包通常不是靠某个魔改软件一键安装的它本质是“文件放对位置 写清楚说明”。你可以手动创建也可以把别人分享的技能目录复制到你的项目里。6.1 方式一手动创建技能包沿用前面的方式手动创建SKILL.md文件即可。以 5.2 节中的commit-helper为例cd my-project mkdir -p .claude/skills/commit-helper cat .claude/skills/commit-helper/SKILL.md EOF --- name: commit-helper description: 根据 git 变更内容生成符合规范的 Commit 信息。当用户提到 commit、提交信息、提交说明时使用。 --- # Commit 信息生成 - 获取当前 git diff分析变更涉及的功能模块。 - 提交信息格式type(scope): subject。 - type 使用feat / fix / refactor / docs / test / chore / perf。 - subject 必须使用动词开头且不超过 50 个字符。 - 如果涉及破坏性变更在 commit 信息最后说明高风险。 EOF这样一个最简单的技能包就创建好了。6.2 方式二复制现成技能包目录如果你从同事或开源项目里拿到一个技能包通常它是一个文件夹里面包含SKILL.md和其他资源文件。安装方式就是把它复制到你的项目目录cp -r skills/commit-helper my-project/.claude/skills/复制完成后重点检查两点SKILL.md是否存在SKILL.md开头是否包含---包裹的name和description字段。只要这两点没问题技能包就能被识别。6.3 如何触发技能技能装好后使用方式有两种在对话中自然提及“帮我审查这部分代码”AI 自动匹配对应技能。主动指定技能名称“使用 code-reviewer 技能处理 src/ 目录”让 AI 明确加载技能。第二种方式更适合新手验证技能是否生效。6.4 多技能组合技能包可以组合起来使用。例如一次需求完成后你可以连续要求先用 unit-test-builder 为本次新增函数生成测试 然后使用 commit-helper 生成提交信息。这样 AI 会在一次任务中依次加载两个技能比你手动让它“仔细一点”稳定得多。7. 常见问题与排查思路新手在配置技能包时最常遇到的几个问题如下。问题现象可能原因排查方式解决方案启动后技能不生效SKILL.md 存放位置不对检查目录是否为.claude/skills/技能名/SKILL.md把目录结构调整为标准格式技能时灵时不灵description描述太泛查看技能触发时的日志或输出把描述改成包含明确的用户意图关键词技能命中了但行为不符合预期SKILL.md 中的步骤不够具体在对话中直接问 AI“你使用了哪些规则”把任务步骤拆得更细限制输出格式检测到技能但无法调用脚本脚本缺少执行权限或依赖手动执行脚本验证给脚本加执行权限并补齐依赖不同项目技能不一致项目技能目录与用户技能目录冲突检查两边目录的 SKILL.md按优先级统一规则或删除多余技能出现权限报错当前账号未被授权使用 Claude Code查看报错信息里的账号提示联系管理员确认访问权限7.1 技能不生效先看目录Claude Code 并不会扫描任意位置的 Markdown 文件。如果你把 SKILL.md 放在.claude/根目录或者src/目录下它不会生效。正确路径.claude/skills/code-reviewer/SKILL.md错误路径.claude/code-reviewer/SKILL.md出现技能不生效时第一个排查动作就是检查路径。7.2 命中了但回答仍然很空这种情况大多是description写得太模糊。比如description: 帮助审查代码。这个描述里没有任何能触发 AI 识别的关键词。建议改成description: 当用户要求审查代码、检查代码质量、查找 bug、提出 code review 建议时使用。7.3 脚本类技能不运行如果技能包里包含 Python 或 Shell 脚本请先在终端单独执行一遍确认脚本本身能跑通。否则无论技能规则写得多好脚本一报错整个流程都会中断。8. 最佳实践与工程建议8.1 技能包要纳入版本管理.claude/skills/目录本质上和代码一样应提交到 Git 仓库。这样团队里所有成员在拉取代码后都能获得同一套技能包。建议在.gitignore中不要忽略.claude/目录。默认情况下只要你不主动把.claude加入忽略列表它就能跟随项目版本管理。8.2 命名规范技能目录名和name字段保持一致使用短横线分隔例如code-reviewerunit-test-buildercommit-helper不要在name里加版本号、作者名等无关信息。name是触发时的一句话标识越短越好。8.3 描述要面向“意图”而不是“能力”description写的是“什么情况下使用这个技能”而不是“这个技能多厉害”。好的写法description: 当用户提到 git commit、提交信息、commit message、规范提交时使用。差的写法description: 一个强大的提交信息生成工具。因为 AI 是通过语义匹配触发技能的越贴近用户的话术命中率越高。8.4 每个技能都要有“输出约束”最容易让技能输出失控的是漏掉了输出格式。建议每个 SKILL.md 都要写明先输出什么再输出什么使用列表还是表格是否允许直接修改代码是否需要给出验证命令。输出约束越明确AI 行为越稳定。8.5 不要在技能里写敏感信息技能包会跟随项目分发也会被 AI 读取作为上下文。绝对不要在 SKILL.md 里写数据库口令、API Key、内部系统地址等敏感信息。如果确实需要环境相关配置用环境变量代替并在技能说明中引用变量名。8.6 从最小技能开始迭代不要一上来就写一个几千字的超级技能。第一次使用某个技能包时先写能覆盖 80% 场景的 5 到 10 条规则用到真实项目里发现不足再加。技能包像代码一样需要维护。你越使用它越贴近你的项目习惯。9. 总结与后续学习方向Claude Code 的价值不在于它能“自动写代码”而在于你能通过 Skills 机制把项目规范、代码风格、工作流程固化下来让 AI 每次干活都照着你的标准来。这 7 个技能包本质上是把高频开发任务标准化AI 的输出质量会因此明显提升。下一步建议先选一个你最痛的点比如 Commit 信息混乱创建你的第一个 Skill在真实项目里用一周记录 AI 哪些回答仍然不达标根据这些不达标场景回填 SKILL.md 的规则当技能包稳定后再提交到团队仓库让整个团队共享。如果你刚开始用 Claude Code不建议看太多复杂的插件和架构先把技能包的基础用法跑通。等你对 SKILL.md 的写法越来越熟自然会开始设计更复杂的多技能协作流程。把这个技能机制用起来比换一个更强的模型对你的日常开发效率影响更大。 Claude Code Skills实战：7个技能包让AI编程助手真正懂你的项目
把 Claude Code 装好第一次问它“帮我写一个用户注册接口”它确实能回复一堆能跑的代码。但等你真正在项目里用起来让它“检查一下这个项目哪里可能出问题”“帮我把这几处重复逻辑抽成公共方法”“给这次改动生成规范的 Commit 信息”它往往会先反问你要看哪个目录、要遵守什么规范。这时候很多人会得出一个结论Claude Code 也不过如此。我的判断是问题不在模型而在你不会给 Claude Code 配置技能。Claude Code 的 Skills 机制就是把“你在项目里反复要做的那几类工作”提前写成一套可复用的指令和脚本。它让 AI 从“你问一句它答一句”的聊天窗口变成一个真正理解你工作习惯的编程助手。这篇文章会把 Claude Code 的技能机制讲清楚并给出 7 个适合新手的 Skills 技能包方向附上可复制的 SKILL.md 模板。你不需要懂复杂的插件开发只要会建文件夹、写 Markdown就能在 10 分钟内跑通第一个技能包。1. 这篇文章真正要解决的问题很多新手在安装 Claude Code 之后很快会卡在这几个场景里生成的 Commit 信息风格五花八门项目历史一团乱让 AI 写单测它每次都把测试写成一个“孤零零的 demo”根本没接入测试框架代码重构时AI 改一个地方另一个地方就漏了让它排查问题它把整个项目从头讲一遍就是没告诉你日志里那行报错真正意味着什么。这些问题看起来是“AI 不够聪明”实际上是“AI 没有被赋予足够的任务规则”。Claude Code 缺的不是智力而是项目上下文、输出格式和操作边界。Skills 恰好能把这三样东西打包好。简单说Skills 是 Claude Code 里的“岗位说明书”。你告诉它这个技能要做什么、按什么步骤做、输出什么格式它就会在任务命中时自动进入对应模式。这篇文章适合三类读者刚接触 Claude Code装了但不知道怎么用到项目里的新手已经用 Claude Code 写代码但对输出质量不满意、想提升稳定性的开发者想给团队统一 AI 编程规范的工程负责人。读完你会掌握Skills 的原理、7 个高频技能包的设计思路、SKILL.md 的标准写法、安装和验证方法以及在实际项目中避坑的具体建议。2. Claude Code Skills 的核心概念与运作原理2.1 什么是 SkillSkill 在 Claude Code 里是一组预先定义好的指令和辅助脚本通常放在项目的.claude/skills/目录下。它不改变模型本身而是改变 AI 被触发后的“任务执行方式”。一个 Skill 由两部分组成SKILL.md技能说明文件包含触发条件、执行步骤、输出规范assets/或scripts/可选配套脚本、模板文件、工具代码。当你在 Claude Code 里用自然语言提出了一个任务Claude 会根据 SKILL.md 中声明的描述和触发字段判断当前任务是否命中这个技能。命中后它会把技能里写的规则当作“额外的系统提示词”来执行。2.2 Skill 和普通 Prompt 的区别很多人会把 Skills 理解成“长一点的 Prompt”这个理解不完整。普通 Prompt 是一段一次性指令每次都要重新粘贴Skill 则是一个可被自动发现、可版本管理、可复用的项目资产。对比一下对比项普通 PromptSkill使用方式每次手动复制粘贴任务命中后自动加载存放位置对话窗口项目目录或用户目录可复用性差换项目就要另写强可跟随项目走可组合性弱只能靠手动补充强可结合多个技能执行复杂流程团队协作难同步可通过代码仓库统一分发理解了这一点你就知道为什么说“技能包是 Claude Code 的进阶玩法”。它把个人经验变成了团队资产。2.3 Claude Code 如何发现技能从目前的机制来看Claude Code 会让 AI 在任务开始时自动扫描可用的技能目录。常用位置包括项目级技能目录.claude/skills/推荐团队项目使用用户级技能目录~/.claude/skills/适合个人长期使用的通用技能。你不需要启动任何服务只要把文件夹和 SKILL.md 放对位置下次启动 Claude Code 就会自动识别。这个设计对新手非常友好因为它没有引入一套复杂的注册流程。2.4 Skill 的适用边界Skill 不是万能的。它最适合解决**“有明确步骤、有固定输出要求”的重复性任务**不适合解决需要大规模自主探索的研究型任务。例如“按照公司规范审查这个文件指出性能问题”就适合写成 Skill“帮我设计一个微服务架构并给出完整的落地文档”就不太适合因为它需要大量上下文判断强行套规则反而会限制 AI。3. 环境准备与前置条件在创建技能包之前先确保 Claude Code 能在你本机正常跑起来。3.1 安装 Claude CodeClaude Code 当前常见的安装方式是通过 npm 安装 CLI 工具。如果你的机器上已经安装了 Node.js可以直接执行npm install -g anthropic-ai/claude-code安装完成后在终端里执行claude --version如果能正常输出版本号说明命令已经生效。如果你的使用方式是基于桌面版或编辑器插件思路也是一样的先确认你本机的 Claude Code 可用再进入项目目录创建技能文件。3.2 登录与权限检查执行claude首次进入会提示登录。你需要用有效的账号完成认证。完成登录后Claude Code 才有权限调用模型接口。这里有一个常见问题如果管理员限制了账号的 Claude Code 访问权限启动时会遇到类似your organization has disabled claude subscription access for claude code的提示。这类情况不是你的本地配置问题而是账号权限问题需要联系管理员确认授权范围。3.3 准备一个测试项目技能包最好在真实项目里创建而不是在空目录里空想。建议先准备一个小项目比如一个简单的 Python 工具库或者 Spring Boot 项目。不需要结构复杂只要能验证技能是否被触发即可。目录结构大致如下my-project/ ├── .claude/ │ └── skills/ │ └── code-reviewer/ │ ├── SKILL.md │ └── review-rules.md ├── src/ └── README.md后面的示例都会以这个结构为基础。4. 第一个技能包从 0 到 1 创建一个 Skill4.1 创建技能目录在项目根目录下执行mkdir -p .claude/skills/code-reviewer把code-reviewer当作你要创建的第一个技能它的作用是“代码审查”。4.2 编写 SKILL.md进入该目录新建SKILL.md--- name: code-reviewer description: 当用户要求审查代码、检查代码质量、查找潜在 Bug 或对代码变更提出建议时使用。 --- # 代码审查员 你是一个严谨的代码审查员。审查代码时必须按以下步骤执行 1. 先定位代码文件确认它属于哪个模块。 2. 分析代码的结构列出实际存在的风险点不要泛泛而谈。 3. 对每一个问题都给出以下信息 - 严重程度高危 / 中危 / 建议 - 问题描述具体到文件和行号 - 修复建议给出可执行的改动思路 4. 如果代码量较大优先检查错误处理、空值判断、资源释放、异常边界。 5. 如果没有发现问题明确说明“未发现明显问题”并解释为什么这么判断。这个文件的核心价值在于它把“审查代码”这个模糊任务拆解成了一个 AI 可以稳定执行的流程。4.3 在 Claude Code 中测试技能启动 Claude Codeclaude然后在对话中输入请帮我审查 src/ 目录下的代码。如果 Skills 机制正常工作Claude Code 会在生成回答时自动利用code-reviewer技能中的审查规则。一个小技巧是在首次测试时把描述写得具体一些“用 code-reviewer 技能审查本次变更的文件”。这样更容易判断到底是技能没生效还是描述没有命中。5. 7 个值得人手一份的 Skills 技能包下面这 7 个技能包是我强烈建议新手优先配置的方向。它们覆盖了日常开发中使用频率最高、最容易被 AI 做“糊弄过去”的任务。我把每个技能包的核心说明和 SKILL.md 片段都整理出来了你可以直接复制后按自己的项目改。5.1 code-reviewer代码审查与风险分析解决的问题让 Claude Code 从“夸代码写得好”变成“真的找出问题”。适用场景提交合并请求前、代码评审时、接手陌生项目时。关键逻辑只允许清单化的输出禁止模糊的“代码整体较好”这类描述。--- name: code-reviewer description: 审查代码质量、定位潜在 Bug、输出结构化评审结论。当用户提到 review、代码审查、质量问题、检查代码时使用。 --- # 代码审查规则 - 每次审查必须输出问题清单格式为严重级别 | 文件位置 | 问题描述 | 修复建议。 - 按优先级排序高危问题列在最前面。 - 不要修改代码只输出评审意见。 - 如果没有发现高危问题必须说明已检查了哪些方面。新手注意给 AI 看的审查要求越具体越好。你希望它检查“空指针”就直接写“检查可能为 null 的变量和外部输入”你希望它关注“并发安全”就明确写“检查共享状态是否存在更新竞争”。5.2 commit-helper生成规范的 Commit 信息解决的问题统一团队提交历史风格告别fix bug、update这类无意义信息。适用场景每次完成代码变更后需要生成符合 Conventional Commits 规范的提交信息。关键逻辑先读取 git diff再分析变更类型最后输出提交信息。--- name: commit-helper description: 根据 git 变更内容生成符合规范的 Commit 信息。当用户提到 commit、提交信息、提交说明时使用。 --- # Commit 信息生成 - 获取当前 git diff先分析变更涉及的功能模块。 - 提交信息格式 - type(scope): subject - type 使用feat / fix / refactor / docs / test / chore / perf。 - subject 必须使用动词开头且不超过 50 个字符。 - 如果涉及破坏性变更在 commit 信息最后说明高风险。5.3 unit-test-builder单元测试生成器解决的问题让 AI 生成“能真跑的测试”而不是“看起来像测试的模板”。适用场景新写了一个工具函数、修复了一个 Bug 需要回归测试、补充项目测试覆盖。关键逻辑先确认代码入口和依赖再基于测试框架生成用例。--- name: unit-test-builder description: 为指定函数或模块生成单元测试。当用户提到单测、单元测试、test case、测试用例时使用。 --- # 单元测试生成规则 - 先确认被测函数的入参、返回值、异常类型和外部依赖。 - 使用项目中已有的测试框架风格不要自创结构。 - 每个测试用例必须包含测试目的、输入数据、预期结果、断言说明。 - 必须覆盖正常场景、边界场景、异常场景。 - 生成完测试代码后给出运行命令。新手注意如果你不告诉它项目用的是 pytest 还是 JUnit 还是 vitest它很可能会生成一个风格完全不同的测试文件。建议在技能描述里直接写清楚测试框架名称。5.4 doc-sync文档同步与更新解决的问题代码改完了README 和接口文档还是旧的。适用场景接口参数调整、模块重命名、功能上线后文档更新。关键逻辑对比代码实现与现有文档只更新差异部分。--- name: doc-sync description: 根据代码变更同步更新 README 或接口文档。当用户提到文档更新、同步文档、更新 README 时使用。 --- # 文档同步规则 - 先读取代码变更对应的文档文件。 - 对比代码与文档不一致的地方列出差异点。 - 逐项修改文档不要重复整个文件的内容。 - 涉及接口文档时记录请求路径、请求参数、响应字段的变化。 - 修改完成后输出一个变更清单方便人工确认。5.5 refactor-master代码重构助手解决的问题AI 重构时一次改得太多或者只改表面不动逻辑。适用场景抽取公共方法、消除重复代码、调整类结构、优化函数长度。关键逻辑重构前先定义“不改运行的验证方式”再开始改动。--- name: refactor-master description: 对目标代码进行安全重构保持外部行为不变。当用户提到重构、抽取方法、消除重复、优化结构时使用。 --- # 重构规则 - 第一步介绍当前代码结构说明要保留的核心逻辑。 - 第二步给出重构方案按文件列出改动点。 - 第三步先输出重构后的核心代码再说明依赖关系变化。 - 重构过程中禁止修改公共接口的签名除非用户明确要求。 - 完成每个文件后都要提示开发如何回归验证。5.6 debug-assistant问题诊断与故障排查解决的问题AI 不给直接答案而是自说自话地给你讲一遍所有可能的报错原因。适用场景程序运行报错、日志出现异常、接口返回不符合预期。关键逻辑要求 AI 先复现问题再给出诊断链不输出无关信息。--- name: debug-assistant description: 辅助排查程序报错、日志异常和运行环境问题。当用户提到报错、异常、排查、deubg、日志分析时使用。 --- # 调试排查规则 - 第一步先读取报错堆栈或相关日志提取关键错误信息。 - 第二步定位到具体文件和代码行分析触发条件。 - 第三步只输出最可能的 3 个原因按可能性排序。 - 第四步为每个原因给出验证方法而不是直接改代码。 - 不要建议删除数据、清空缓存等高危操作除非用户明确要求。5.7 prompt-architect提示词优化与需求拆解解决的问题你已经会用 Claude Code 了但有时候它给你的代码方向不对换个问法结果完全不同。适用场景写新功能提示词时、把模糊需求拆成可执行任务时、给团队其他成员写共享提示词时。关键逻辑把需求转化为目标、约束、输入、输出四要素。--- name: prompt-architect description: 帮助优化 AI 提示词或将模糊需求拆解为可执行的任务描述。当用户提到提示词优化、prompt、需求拆解、写 prompt 时使用。 --- # 提示词优化规则 - 先输出优化后的提示词再解释为什么这样改。 - 优化后的提示词必须包含 1. 任务目标希望 AI 完成什么。 2. 输入信息需要提供哪些文件或上下文。 3. 约束条件不允许做什么、必须满足哪些规范。 4. 输出格式期望返回什么形式的结果。 - 当需求过于模糊时先列出需要用户补充的问题再尝试补全。这 7 个技能包覆盖了“写代码前、写代码中、写代码后”三个主要阶段。新手不需要一次性全部配好先挑一个你当前最痛的方向把它用熟再逐步扩展。6. 技能包的安装与使用两种实操方式很多人在意的“技能安装包”到底怎么装这里要澄清一个最常见的误区Claude Code 技能包通常不是靠某个魔改软件一键安装的它本质是“文件放对位置 写清楚说明”。你可以手动创建也可以把别人分享的技能目录复制到你的项目里。6.1 方式一手动创建技能包沿用前面的方式手动创建SKILL.md文件即可。以 5.2 节中的commit-helper为例cd my-project mkdir -p .claude/skills/commit-helper cat .claude/skills/commit-helper/SKILL.md EOF --- name: commit-helper description: 根据 git 变更内容生成符合规范的 Commit 信息。当用户提到 commit、提交信息、提交说明时使用。 --- # Commit 信息生成 - 获取当前 git diff分析变更涉及的功能模块。 - 提交信息格式type(scope): subject。 - type 使用feat / fix / refactor / docs / test / chore / perf。 - subject 必须使用动词开头且不超过 50 个字符。 - 如果涉及破坏性变更在 commit 信息最后说明高风险。 EOF这样一个最简单的技能包就创建好了。6.2 方式二复制现成技能包目录如果你从同事或开源项目里拿到一个技能包通常它是一个文件夹里面包含SKILL.md和其他资源文件。安装方式就是把它复制到你的项目目录cp -r skills/commit-helper my-project/.claude/skills/复制完成后重点检查两点SKILL.md是否存在SKILL.md开头是否包含---包裹的name和description字段。只要这两点没问题技能包就能被识别。6.3 如何触发技能技能装好后使用方式有两种在对话中自然提及“帮我审查这部分代码”AI 自动匹配对应技能。主动指定技能名称“使用 code-reviewer 技能处理 src/ 目录”让 AI 明确加载技能。第二种方式更适合新手验证技能是否生效。6.4 多技能组合技能包可以组合起来使用。例如一次需求完成后你可以连续要求先用 unit-test-builder 为本次新增函数生成测试 然后使用 commit-helper 生成提交信息。这样 AI 会在一次任务中依次加载两个技能比你手动让它“仔细一点”稳定得多。7. 常见问题与排查思路新手在配置技能包时最常遇到的几个问题如下。问题现象可能原因排查方式解决方案启动后技能不生效SKILL.md 存放位置不对检查目录是否为.claude/skills/技能名/SKILL.md把目录结构调整为标准格式技能时灵时不灵description描述太泛查看技能触发时的日志或输出把描述改成包含明确的用户意图关键词技能命中了但行为不符合预期SKILL.md 中的步骤不够具体在对话中直接问 AI“你使用了哪些规则”把任务步骤拆得更细限制输出格式检测到技能但无法调用脚本脚本缺少执行权限或依赖手动执行脚本验证给脚本加执行权限并补齐依赖不同项目技能不一致项目技能目录与用户技能目录冲突检查两边目录的 SKILL.md按优先级统一规则或删除多余技能出现权限报错当前账号未被授权使用 Claude Code查看报错信息里的账号提示联系管理员确认访问权限7.1 技能不生效先看目录Claude Code 并不会扫描任意位置的 Markdown 文件。如果你把 SKILL.md 放在.claude/根目录或者src/目录下它不会生效。正确路径.claude/skills/code-reviewer/SKILL.md错误路径.claude/code-reviewer/SKILL.md出现技能不生效时第一个排查动作就是检查路径。7.2 命中了但回答仍然很空这种情况大多是description写得太模糊。比如description: 帮助审查代码。这个描述里没有任何能触发 AI 识别的关键词。建议改成description: 当用户要求审查代码、检查代码质量、查找 bug、提出 code review 建议时使用。7.3 脚本类技能不运行如果技能包里包含 Python 或 Shell 脚本请先在终端单独执行一遍确认脚本本身能跑通。否则无论技能规则写得多好脚本一报错整个流程都会中断。8. 最佳实践与工程建议8.1 技能包要纳入版本管理.claude/skills/目录本质上和代码一样应提交到 Git 仓库。这样团队里所有成员在拉取代码后都能获得同一套技能包。建议在.gitignore中不要忽略.claude/目录。默认情况下只要你不主动把.claude加入忽略列表它就能跟随项目版本管理。8.2 命名规范技能目录名和name字段保持一致使用短横线分隔例如code-reviewerunit-test-buildercommit-helper不要在name里加版本号、作者名等无关信息。name是触发时的一句话标识越短越好。8.3 描述要面向“意图”而不是“能力”description写的是“什么情况下使用这个技能”而不是“这个技能多厉害”。好的写法description: 当用户提到 git commit、提交信息、commit message、规范提交时使用。差的写法description: 一个强大的提交信息生成工具。因为 AI 是通过语义匹配触发技能的越贴近用户的话术命中率越高。8.4 每个技能都要有“输出约束”最容易让技能输出失控的是漏掉了输出格式。建议每个 SKILL.md 都要写明先输出什么再输出什么使用列表还是表格是否允许直接修改代码是否需要给出验证命令。输出约束越明确AI 行为越稳定。8.5 不要在技能里写敏感信息技能包会跟随项目分发也会被 AI 读取作为上下文。绝对不要在 SKILL.md 里写数据库口令、API Key、内部系统地址等敏感信息。如果确实需要环境相关配置用环境变量代替并在技能说明中引用变量名。8.6 从最小技能开始迭代不要一上来就写一个几千字的超级技能。第一次使用某个技能包时先写能覆盖 80% 场景的 5 到 10 条规则用到真实项目里发现不足再加。技能包像代码一样需要维护。你越使用它越贴近你的项目习惯。9. 总结与后续学习方向Claude Code 的价值不在于它能“自动写代码”而在于你能通过 Skills 机制把项目规范、代码风格、工作流程固化下来让 AI 每次干活都照着你的标准来。这 7 个技能包本质上是把高频开发任务标准化AI 的输出质量会因此明显提升。下一步建议先选一个你最痛的点比如 Commit 信息混乱创建你的第一个 Skill在真实项目里用一周记录 AI 哪些回答仍然不达标根据这些不达标场景回填 SKILL.md 的规则当技能包稳定后再提交到团队仓库让整个团队共享。如果你刚开始用 Claude Code不建议看太多复杂的插件和架构先把技能包的基础用法跑通。等你对 SKILL.md 的写法越来越熟自然会开始设计更复杂的多技能协作流程。把这个技能机制用起来比换一个更强的模型对你的日常开发效率影响更大。