1. 为什么 Skills 是 Claude Code 的分水岭1.1 从“能聊天”到“能干活”的那道坎Claude Code 刚上手的时候很多人第一反应是“这不就是个终端里的聊天框吗”。你问它问题它回答你让它改代码它给你一段 diff。用几天之后就会发现真正拉开效率差距的不是模型本身有多聪明而是它能不能记住你的项目约定、能不能自动加载你团队的那套规范、能不能在你敲一个斜杠命令的时候就把一整套流程跑完。这个“能不能”的答案就落在 Skills 上。Skills 本质上是一组可复用的指令包每个 Skill 通常包含一个说明文件描述这个技能干什么、什么时候触发以及可选的脚本、模板、参考资料。Claude Code 在运行时会根据当前上下文去匹配这些技能匹配上了就自动加载对应的指令相当于给模型临时“补课”。你可以把它理解成给一个通用助手发了一本岗位操作手册——平时它什么都能聊但一旦进入你的项目目录它就知道该按哪本手册办事。我见过太多人卡在“装完 Claude Code 就不知道怎么往下走”的阶段。命令行能跑起来claude一敲能进交互界面然后呢每次都要重新解释项目结构每次都要重复“我们用的是 pnpm 不是 npm”“我们的组件都放在 src/components 下面”“提交信息要遵循 conventional commits”。这些重复劳动Skills 就是专门来消灭的。1.2 项目级和全局到底差在哪这是最容易被忽略、也最容易踩坑的一个点。Skills 的存放位置决定了它的作用范围而作用范围又直接影响到加载优先级和团队协作方式。项目级 Skills放在项目根目录下的.claude/skills/里。它的特点是跟着仓库走你 clone 下来项目技能就在那儿团队里每个人用的都是同一套。适合放什么放这个项目特有的东西这个项目的代码规范、这个项目的部署流程、这个项目特有的 API 封装约定。换一个项目这些约定就不适用了所以它们不该被带到别的项目里去。全局 Skills放在用户主目录下的~/.claude/skills/里。它的特点是跟着你这个人走不管你打开哪个项目这些技能都在。适合放什么放你个人的通用工作习惯你习惯的提交信息格式、你常用的代码审查清单、你跨项目都要用的那些工具脚本。换公司、换电脑把这些带走就行。两者同时存在的时候Claude Code 的加载逻辑是项目级优先。也就是说如果同一个技能名在项目级和全局都存在项目级会覆盖全局。这个设计很合理——项目约定应该压过个人习惯否则团队协作就乱套了。但很多人不知道这个优先级结果在全局装了一个技能进项目发现没生效排查半天才发现是被项目级的同名技能盖住了。提示判断一个技能该放哪问自己一句话——“换一个项目这个技能还成立吗”成立就放全局不成立就放项目级。1.3 装之前先想清楚的三件事在动手装任何 Skill 之前我建议先把这三个问题过一遍能省掉后面大量的返工。第一这个技能解决的是重复劳动还是偶发需求。如果一个操作你一周要做五次那值得做成 Skill如果一个月才用一次写个笔记就够了做成 Skill 反而是维护负担。Skills 是要长期维护的项目结构变了、工具升级了技能里的指令可能就过时了你得跟着改。第二这个技能是给一个人用还是给一个团队用。给团队用的必须放项目级并且提交到仓库还要在 README 里写清楚怎么用给自己用的放全局就行不用污染项目仓库。我见过有人在项目里塞了一堆个人习惯的技能结果同事 clone 下来一脸懵不知道这些技能是干嘛的。第三这个技能会不会和已有的冲突。装之前先ls一下现有的 skills 目录看看有没有同名的、功能重叠的。功能重叠的技能同时存在Claude Code 匹配的时候可能加载了不是你预期的那个行为就会很诡异。2. 安装 Claude Code 与 Skills 目录结构2.1 先把 Claude Code 本身装利索Skills 是 Claude Code 的能力扩展所以第一步得先有一个能正常工作的 Claude Code。安装方式取决于你的系统我按最常见的几种情况说。macOS 和 Linux 下官方推荐的方式是通过包管理器或者直接下载二进制。如果你用 Homebrew一条命令的事如果没有 Homebrew用 curl 拉安装脚本也行。Windows 下稍微麻烦一点原生支持在逐步完善很多人会选择在 WSL 里跑这样和 Linux 环境一致踩的坑最少。我个人的建议是如果你主力是 Windows 又不想折腾 WSL那就用官方提供的 Windows 版本但要注意路径分隔符和权限的问题后面讲排查的时候会细说。装完之后验证一下终端里敲claude --version能打印出版本号就说明装好了。如果提示 command not found八成是 PATH 没配好。macOS/Linux 下检查~/.local/bin或者/usr/local/bin在不在 PATH 里Windows 下检查环境变量。这一步看着基础但我见过太多人卡在这儿后面所有操作都做不了。还有一个容易被忽略的点Node 版本。Claude Code 依赖 Node 运行时版本太低会报各种奇怪的错。用node -v看一下建议 18 以上20 更稳。如果你用 nvm 管理 Node记得nvm use切到合适的版本而且要注意 nvm 装的 Node 在不同终端会话里可能不生效需要配置默认版本。2.2 目录结构长什么样Claude Code 读取 Skills 的路径是固定的你得把技能放到正确的位置它才认。全局技能目录~/.claude/skills/项目级技能目录你的项目根目录/.claude/skills/每个技能是目录下的一个子文件夹文件夹名就是技能名。文件夹里面通常有一个SKILL.md作为主说明文件还可以有scripts/、templates/、references/等子目录放辅助资源。结构大概是这样~/.claude/skills/ ├── commit-helper/ │ ├── SKILL.md │ └── scripts/ │ └── format.sh ├── code-review/ │ └── SKILL.md └── api-doc/ ├── SKILL.md └── templates/ └── endpoint.mdSKILL.md是整个技能的核心它用自然语言描述这个技能是干什么的、什么时候该被触发、触发后要执行什么步骤。Claude Code 读的就是这个文件。写得好的 SKILL.md模型一看就知道该在什么场景下用它写得烂的模型要么不触发要么触发了乱执行。2.3 手动创建第一个技能与其去网上找现成的不如先手动建一个最简单的把整个流程跑通心里有底了再去装别人的。第一步建目录mkdir -p ~/.claude/skills/hello-skill第二步写 SKILL.md--- name: hello-skill description: 当用户询问项目基本信息时使用输出当前项目的技术栈概览 --- # 项目信息速览 当被触发时执行以下步骤 1. 读取项目根目录的 package.json如果存在 2. 提取 dependencies 和 devDependencies 中的关键依赖 3. 按框架、构建工具、测试工具分类整理 4. 用简洁的列表输出不要展开每个包的版本号第三步进 Claude Code 测试。在项目目录里启动claude然后问一句“这个项目用了什么技术栈”看它会不会加载这个技能并按你写的步骤执行。这个最小示例跑通了你就理解了 Skills 的运作机制description 决定什么时候触发正文决定触发后干什么。后面所有复杂的技能都是在这个骨架上加东西。注意description写得越具体触发越准。写“处理代码相关任务”这种大而全的描述会导致技能在不该触发的时候乱触发反而干扰正常使用。3. 从项目级切到全局的完整操作3.1 什么时候该做这个切换先说清楚什么情况下需要把技能从项目级挪到全局。最常见的情况是你在某个项目里写了一个技能用了一段时间发现它其实跟项目本身没关系是你个人的通用习惯。比如你写了一个“生成符合你个人风格的提交信息”的技能放在项目里结果换个项目又得重新写一遍。这时候就该把它挪到全局去。另一种情况是你一开始图省事把所有技能都塞在项目级结果项目仓库里多了一堆.claude/skills/的文件同事看着烦你自己维护也累。这时候需要做一次梳理把通用的挪到全局只留项目特有的在项目里。还有一种情况是团队协作你希望某个技能全团队都能用但不想让它进项目仓库比如涉及个人工作流的那就放全局然后告诉同事他们也各自装一份。不过这种情况我更建议直接进项目仓库团队共享的东西放全局反而容易版本不一致。3.2 迁移的具体步骤迁移本身不复杂就是把目录从项目级挪到全局但有几个细节要注意。第一步确认全局目录存在mkdir -p ~/.claude/skills第二步把技能目录复制过去先复制别急着删确认没问题再删cp -r .claude/skills/your-skill ~/.claude/skills/第三步检查有没有同名冲突ls ~/.claude/skills/如果全局已经有一个同名技能你得决定是覆盖还是改名。覆盖的话原来全局那个技能就没了改名的话记得同步改 SKILL.md 里的name字段。第四步验证。进 Claude Code触发一下这个技能看行为是不是和之前在项目级时一致。一致的话再把项目级的删掉rm -rf .claude/skills/your-skill第五步如果这个项目级的技能之前提交到了 git记得把删除也提交上去否则同事那边还留着旧版本。3.3 迁移后容易出的岔子迁移之后最常见的两个问题一个是路径引用失效一个是优先级变化导致的行为差异。路径引用失效是这样的技能里的脚本可能用了相对路径比如./scripts/format.sh。在项目级的时候这个相对路径是相对于项目根目录的挪到全局之后相对路径的基准变了脚本就找不到了。解决办法是把脚本里的路径改成绝对路径或者用环境变量来定位。优先级变化导致的行为差异是这样的之前在项目级这个技能压着全局的同名技能挪走之后全局的那个同名技能就生效了行为可能和你预期的不一样。所以迁移之前一定要确认全局没有同名技能或者确认同名技能的行为是你想要的。还有一个坑是权限。全局目录下的脚本执行权限可能和项目级不一样。迁移之后如果脚本跑不起来先chmod x一下试试。4. 技能选型与实战推荐4.1 挑技能的几个判断标准网上现成的 Skills 越来越多怎么挑是个问题。我的判断标准有这么几条。看 description 的触发条件是否清晰。一个好的技能description 会明确说“当用户做 X 的时候使用”。如果 description 写得含糊比如“用于提升开发效率”那这个技能大概率会在你不想要的时候乱触发。看正文步骤是否可执行。有些技能的 SKILL.md 写得像散文全是“要仔细分析”“要深入理解”这种没法执行的话。好的技能应该是步骤化的每一步都有明确的动作和产出。看有没有维护痕迹。技能所依赖的工具、命令、API 是会变的。如果一个技能半年没更新里面用的命令可能已经过时了。装之前扫一眼它的更新记录。看它是不是在重复造轮子。有些技能的功能其实 Claude Code 原生就有装了反而多一层干扰。比如有的技能号称“帮你读文件”但 Claude Code 本来就能读文件这种技能就是多余的。4.2 几类值得优先装的技能根据我自己的使用经验下面这几类技能是投入产出比最高的。代码规范类。把团队的 lint 规则、命名约定、目录结构约定写成一个技能每次让 Claude Code 写代码的时候它都会自动遵守。这类技能放项目级团队共享。提交与 PR 类。提交信息格式、PR 描述模板、变更日志生成这些是高频重复劳动。做成技能之后一句话就能生成符合规范的提交信息。这类技能可以放全局因为格式通常是你个人的习惯。文档生成类。从代码注释生成 API 文档、从组件生成使用说明这类技能能省掉大量手工整理的时间。放项目级还是全局取决于文档模板是不是项目特有的。测试辅助类。生成测试用例骨架、根据失败用例定位问题、补充边界条件这类技能在写测试的时候特别有用。环境检查类。检查依赖版本、检查配置文件完整性、检查环境变量是否齐全这类技能在接手新项目或者排查环境问题时很实用。4.3 一个完整的技能示例拆解拿“提交信息生成”这个技能来完整拆一遍你能看到从需求到落地的全过程。需求是每次提交代码希望提交信息符合 conventional commits 规范并且自动带上影响范围。SKILL.md 大概长这样--- name: commit-message description: 当用户要求生成提交信息、或执行 git commit 相关操作时使用 --- # 生成规范提交信息 ## 触发条件 用户说“帮我写提交信息”“生成 commit message”“提交这些改动”等。 ## 执行步骤 1. 运行 git diff --staged 查看暂存区的改动 2. 如果暂存区为空提示用户先 git add 3. 分析改动内容判断类型 - feat: 新功能 - fix: 修复 - docs: 文档 - refactor: 重构 - test: 测试 - chore: 杂项 4. 判断影响范围scope取改动最集中的目录名 5. 生成格式type(scope): 简短描述 6. 描述用中文不超过 50 字动词开头 7. 如果改动较大在正文补充详细说明 ## 输出格式 直接输出提交信息文本不要加额外解释。这个技能的关键在于步骤明确、判断规则清晰、输出格式固定。模型拿到之后不需要猜照着做就行。装好之后你git add完跟 Claude Code 说“帮我写提交信息”它就会自动跑git diff --staged分析改动生成一条规范的提交信息。整个过程你只需要复制粘贴。实操心得技能里的判断规则不要写太死。比如 scope 的判断如果你写“必须取第一层目录名”遇到改动分散在多个目录的情况就会卡住。写成“取改动最集中的目录名”更灵活。5. 常见问题与排查实录5.1 技能不触发怎么办这是最高频的问题。你装了一个技能满心期待地测试结果 Claude Code 压根没理它。排查顺序是这样的。第一确认目录位置对不对。全局技能必须在~/.claude/skills/下项目级必须在项目根/.claude/skills/下。路径错一层技能就找不到。用ls确认一下。第二确认 SKILL.md 的 frontmatter 格式对不对。name和description必须在---包裹的 frontmatter 里格式错了整个技能就废了。YAML 对缩进敏感冒号后面要有空格。第三确认 description 的触发条件够不够具体。如果你写的是“处理代码”那模型可能觉得任何代码相关的事都算反而不知道该不该触发。改成“当用户要求生成提交信息时使用”这种具体的描述。第四确认没有被同名技能覆盖。项目级和全局有同名技能时项目级优先。如果你在全局装了技能但项目里有同名的全局那个就不生效。第五重启 Claude Code。技能是在启动时加载的你新加了技能但没重启它读不到。退出重进一下。5.2 技能触发了但行为不对技能触发了但执行的结果不是你想要的。这种情况通常是 SKILL.md 的正文写得不够明确。常见的原因是步骤有歧义。比如你写“分析代码质量”模型不知道你要分析哪些维度就按自己的理解来结果和你预期的不一样。改成“检查以下五项命名规范、函数长度、重复代码、错误处理、注释完整性”就明确了。另一个原因是缺少边界条件。比如你写“读取配置文件”但没说什么配置文件、找不到怎么办。模型遇到找不到的情况可能就卡住了或者随便找个文件读。补上“如果配置文件不存在提示用户并终止”这样的边界处理。还有一个原因是输出格式没约束。模型默认会加一堆解释性的话如果你只想要结果得在技能里明确写“只输出结果不要解释”。5.3 排查速查表现象可能原因排查动作技能完全不触发目录位置错误确认在~/.claude/skills/或项目.claude/skills/技能完全不触发frontmatter 格式错误检查---包裹和 YAML 缩进技能完全不触发description 太宽泛改成具体的触发场景描述技能完全不触发未重启 Claude Code退出重进技能触发了但没生效被同名技能覆盖检查项目级和全局是否有同名技能触发了但行为不对步骤有歧义把步骤拆细明确每步动作技能触发了但行为不对缺少边界处理补充异常情况的处理逻辑技能触发了但行为不对输出格式没约束明确指定输出格式脚本执行失败路径引用失效改用绝对路径或环境变量脚本执行失败权限不足chmod x加执行权限5.4 几个我踩过的坑坑一技能名用了中文。虽然理论上支持但实际用下来中文技能名在某些终端环境下会出现编码问题导致技能加载失败。建议技能名一律用英文小写加连字符。坑二SKILL.md 写太长。有人觉得写得越详细越好结果 SKILL.md 写了上千行模型读起来反而抓不住重点。技能说明控制在 100 行以内把最关键的步骤和规则写清楚就行细节可以放到 references 子目录里按需加载。坑三在技能里硬编码路径。比如写死/Users/yourname/project/...换台电脑就废了。用相对路径或者环境变量让技能可移植。坑四装了太多技能。技能不是越多越好装了几十个技能之后模型每次都要在大量技能里匹配匹配准确率反而下降。保持精简只留真正高频使用的。坑五忘了同步给团队。项目级技能提交到仓库之后要通知同事 pull 一下否则他们本地没有这些技能行为和你不一样。最好在 README 里写一段说明新同事 clone 下来就知道有这些技能可用。6. 让技能真正融入日常工作流6.1 从手动触发到自动匹配技能装好只是第一步真正提升效率的是让它在你需要的时候自动出现。这依赖于 description 的触发条件写得准。我的做法是先手动用一段时间观察自己在什么场景下会去调用这个技能然后把这些场景的关键词提炼出来写进 description。比如“提交信息”这个技能我发现自己会说“写提交信息”“生成 commit”“提交一下”就把这几个说法都写进触发条件里。另一个技巧是在技能之间建立引用。比如“代码审查”技能里可以写“如果发现问题调用 commit-message 技能生成修复提交”。这样技能之间能串联起来形成工作流。6.2 定期清理和迭代技能是会过时的。项目重构了、工具升级了、你的习惯变了技能里的内容可能就不适用了。我一般每个月花十分钟过一遍现有的技能看看哪些还在用、哪些可以删、哪些需要更新。判断一个技能该不该留看它最近一个月有没有被触发过。如果一次都没触发要么是触发条件写得不对要么是这个需求其实不存在两种情况都该处理。迭代的时候把改动记在技能目录下的一个 CHANGELOG 里方便回溯。尤其是团队共享的技能改动要让所有人知道。6.3 团队协作中的技能管理团队用 Skills最重要的是约定和同步。约定方面团队应该有一个统一的技能命名规范、目录结构规范、SKILL.md 模板。新加技能的时候照着模板来避免风格混乱。同步方面项目级技能跟着仓库走这个天然同步。全局技能是个人装的团队没法强制同步所以重要的团队技能一定要放项目级。如果某个技能确实需要放全局比如涉及个人账号配置的那就在项目 README 里写清楚“请自行安装 XX 技能”并附上安装说明。还有一个实践是技能评审。新加一个项目级技能的时候让团队里另一个人看一眼 SKILL.md确认触发条件和步骤没有歧义。这个成本很低但能避免很多“为什么我的 Claude Code 行为和你的不一样”的问题。6.4 我个人的技能清单最后分享一下我目前全局装的几个技能给你一个参考。一个是提交信息生成前面详细拆过高频使用。一个是代码审查清单每次让 Claude Code 审查代码的时候自动加载按固定维度检查。一个是文档骨架生成从代码结构生成文档框架省掉手工搭结构的时间。还有一个是环境自检接手新项目的时候跑一遍检查依赖、配置、环境变量是否齐全。项目级的话每个项目根据自己的技术栈和规范来定。前端项目一般会有组件规范、样式约定、路由约定这几个技能后端项目会有 API 规范、数据库迁移、日志规范这几个。技能这个东西装的时候花点心思用起来是真的省事。但别贪多精简、准确、持续维护比数量重要得多。