我先说个真实感受一开始接触 Claude Code 的 Skills 功能时我把它想复杂了以为是什么高深的插件框架。实际用下来它其实就是给 AI 提前写好的工作手册——你把自己处理某类任务的标准步骤、注意事项、输出格式整理成一个 Markdown 文件放到指定目录里Claude Code 遇到对应场景就会主动去翻手册、照着执行。就这么个机制能解决很多实际问题代码审查规范不统一、文档风格飘忽不定、重复性任务每次都要重新描述需求。而且这里有个非常容易踩的坑很多教程只教你怎么在项目里建.claude/skills目录但没告诉你这套目录其实是项目级的——换一个项目就全失效了。如果你写过十来个 Skill 之后想把它们沉淀成自己的通用技能库就会遇到从项目级切换到全局的问题。这篇文章不绕弯子直接讲清楚 Skills 是什么、项目级和全局两种安装方式怎么操作、从项目级切到全局的具体办法、以及我在切换过程中踩过的坑。1. Skills 到底是什么值不值得装1.1 一次搞懂 Skills 的运行机制Skills 在 Claude Code 里的定位比较特殊。它不是独立运行的脚本也不是常驻后台的服务而是一份结构化的 Markdown 文档。文档里用自然语言写明这个技能适合处理什么任务、执行时应该遵循哪些步骤、最终要产出什么格式的结果。Claude Code 会在对话过程中根据用户的请求和 Skill 的描述自动判断当前是否适合调用某个技能一旦命中它就会读取对应的 SKILL.md 全文再结合当前项目上下文来执行。理解这个机制的关键在于描述触发。也就是说Skill 的触发并不靠用户手动输入固定命令而更多靠 Claude 对当前任务意图的判断。比如你写了一个代码审查的 Skill描述里写明适用于检查改动文件的 bug 风险、命名规范、遗留调试代码那么当你让 Claude 审查代码时它就有较大概率主动调用这个 Skill。这也是为什么很多人说Skill 写得好不好一半在描述写得清不清楚。从实用角度看Skills 解决的核心痛点是重复劳动。比如你每次希望 Claude 生成数据库迁移脚本时都遵循特定格式没有 Skill 的情况下你需要复制粘贴一大段规范说明有了 Skill 之后一句帮我做数据库迁移就够了规范说明由 SKILL.md 自动补全。这种效率提升对于经常使用 Claude Code 做固定类型开发任务的场景非常明显。提示一个 Skill 目录内不一定只有 SKILL.md还可以放参考文档、脚本模板、示例文件等辅助资源。Claude Code 会把整个目录视为技能的一部分技能文档里可以引用同目录下的其他文件。1.2 项目级和全局到底差在哪里接着上文的机制继续说。SKILL.md 放在.claude/skills/目录下就只对当前项目生效放在用户主目录的~/.claude/skills/目录下则对你本机上的所有项目生效。这两者官方都没有给出优先级说明但实际测试下来查找顺序是先项目级、后全局。也就是说同一个 Skill 如果两个位置都存在项目级的版本会优先被加载。这就要聊到两种模式各自适合什么场景了。项目级适合放那些和当前代码库强相关的技能比如本项目的接口文档生成规范本项目的前端组件测试模板这类技能换一个项目就失去意义放全局反而是垃圾文件。全局则适合放那些跨项目通用的技能比如生成符合 conventional commits 规范的提交信息做一个不依赖具体框架的技术方案调研这类技能希望你在任何时候都能随时调用。从维护角度看项目级 Skills 更适合放进 Git 仓库因为它们是项目资产的一部分团队成员在另一个环境 clone 代码后能自动获得这些技能全局 Skills 则是个人环境配置通常不进仓库。这个差异直接决定了你后续切换时要考虑迁移范围到底是只复制几个文件还是需要同步更新团队协作约定。2. 项目级 Skills 的完整安装过程2.1 目录结构和 SKILL.md 的最小格式项目级安装非常简单核心就是建目录加写文档。首先是创建一个名为.claude/skills的目录注意开头的点然后在这个目录下为每个技能建立一个子目录子目录名就是这个技能的标识。每个子目录内必须有一个名为SKILL.md的文件这个文件名是固定的不能随意更改。一个最小可用的目录结构是这样的.claude/ └── skills/ └── code-review/ └── SKILL.mdSKILL.md的内容由两部分组成YAML 格式的 frontmatter 元信息和 Markdown 正文。frontmatter 里最核心的字段是name和description前者是技能名称后者是给 Claude 看的触发说明。下面是一个我实际用过的 SKILL.md 骨架--- name: code-review description: 审查项目代码改动重点检查潜在 bug、未清理的调试代码、命名规范问题以及测试覆盖遗漏点。当用户要求帮我审查代码或code review时使用。 --- # 代码审查 ## 执行步骤 1. 先查看当前分支相对主分支的变更文件列表。 2. 按文件逐项审查重点关注 - 新增代码里是否有 console.log 等调试残留 - 命名是否清晰禁止使用拼音缩写 - 是否有明显无用的重复逻辑 3. 输出审查报告按严重程度分级列出问题并给出修改建议。 ## 输出格式 使用如下格式输出 - 变更概览文件数、增删行数 - 问题列表按 P0/P1/P2 分级 - 修改建议这里最关键的是description字段。很多新手会写得很随意比如审查代码结果 Claude 在对话中很难判断什么时候该触发这个技能于是经常出现两种情况让 Claude 做代码审查时它完全没想起这个 Skill或者写文档时反而误触发了。我试过几次之后总结出一个规律description里要写清楚适用于什么任务类型和用户一般会怎么表述这件事把常见触发词都放进去。触发词不是魔法它就相当于给 Claude 的一个提示词命中率自然会高很多。2.2 从零建一个技能并验证生效建完目录和文件只是第一步重要的是确认 Claude Code 真的认出了这个技能。我建议按下面的顺序做一次完整验证。先用命令创建项目级技能目录以 bash 为例cd /path/to/your/project mkdir -p .claude/skills/commit-helper vi .claude/skills/commit-helper/SKILL.md然后编写 SKILL.md 内容写完保存。接下来在项目根目录启动 Claude Code输入/skill命令。正常情况下你会看到一个技能列表里面应该包含commit-helper。如果没看到大概率是 frontmatter 格式问题常见的有两种name字段不能有空格尽量使用小写字母和连字符description字段的引号或换行处理不当会导致 YAML 解析失败。还有一种情况是目录名字和name字段不一致虽然不太影响使用但容易造成混淆建议保持两者完全一致。验证通过之后你可以直接用自然语言测试。比如输入帮我根据当前的改动生成规范的 commit message如果 Claude 开始按照 SKILL.md 里的步骤来工作说明触发成功。如果它完全不理会技能文档就回去检查description里的触发条件是不是写得足够具体。注意Claude Code 通常只在启动时扫描一次 Skills 目录。你在它运行过程中新增或修改了 SKILL.md可能需要重启会话或重新进入项目才能生效。3. 全局 Skills 的安装方法3.1 全局目录在不同系统上的位置全局 Skills 的安装逻辑和项目级几乎一样唯一的区别是目标目录从项目内的.claude/skills换成了用户主目录下的.claude/skills。具体路径取决于操作系统在 macOS 和 Linux 上通常是~/.claude/skills/在 Windows 上是%USERPROFILE%\.claude\skills\。我建议在正式安装前先用命令确认一下目录是否存在。比如在 macOS 或 Linux 上mkdir -p ~/.claude/skills ls -la ~/.claude/skills后面这个命令能让我们看清楚当前全局技能目录里已经有哪些技能。如果你看到目录下已经有其他工具或插件写入的文件不用慌只要不覆盖同名文件就行。全局目录的目录结构规范和项目级完全一致一个技能一个子目录每个子目录里至少一个 SKILL.md。3.2 手动创建和从第三方复制两种途径全局技能的来源通常有两种一是你完全手写自己的技能二是从网上或者团队内部拿到别人整理好的技能包直接复制进去。手写的过程和上一节项目级安装没有本质区别只是把目录路径换掉。第三方技能包则更关注怎么放进来因为很多技能包会附带额外的脚本文件或模板目录。假设你下载了一个名为api-doc-generator的技能包里面除了 SKILL.md 还有template.md和scripts/两个辅助资源。正确的操作是把整个api-doc-generator目录复制到~/.claude/skills/下而不是只复制 SKILL.md。因为 SKILL.md 里很可能引用了同目录下的模板文件只复制主文档会导致技能执行时找不到辅助文件而报错。复制完成后同样用/skill命令验证只不过这时候需要在一个任意项目中测试——因为全局技能理论上对所有项目生效。如果测试项目里之前已经存在同名项目级技能那就属于冲突场景了这个我在下一节详细讲。4. 核心操作从项目级切到全局4.1 切换前先想清楚该切还是不该切说句实在话不是所有项目级 Skills 都值得切到全局。我在实际使用中给自己定了一条规则只有那些和具体项目无关、换了任何一个代码库都成立的技能才往全局放。比如生成规范 commit message按统一格式输出代码审查结果帮你构建一个技术方案对比表这类它们的行为不依赖特定项目结构放全局能最大化复用。反过来那些和项目强绑定的技能比如为本项目的微服务生成 API 文档按团队的接口错误码规范生成异常处理代码就不建议切到全局。这类技能里往往写入了项目特定的目录约定、术语表、命名规则一旦全局化你在其他项目触发它时它反而会按一套完全不相关的规范来工作制造误导。如果团队约定了非常通用的开发规范那可以考虑把通用部分提取成一个新技能放全局把项目特有部分留在项目级分而治之。另外还要考虑团队协同问题。如果技能是团队资产项目级版本放在 Git 仓库里新成员拉代码就能同步获取一旦你把技能移到全局团队其他人并不会自动拥有它。这种迁移就变成了一次个人环境改造需要额外自己和团队同步。我见过只把项目级 Skill 删掉、没有同步到全局的案例结果其他人拉取最新代码后技能直接消失影响还挺大的。4.2 两种切换方法复制迁移和符号链接确认某个技能确实适合全局化之后有两种具体操作方式复制迁移和符号链接。复制迁移比较好理解就是把整个技能目录从项目级复制到全局目录然后在项目级目录里删掉原文件。以项目.claude/skills/code-review为例cp -r .claude/skills/code-review ~/.claude/skills/ rm -rf .claude/skills/code-review这种方式的优点是干净、彻底项目里以后不再保留这套技能也不会出现项目级版本和全局版本不一致的隐患。缺点是你失去了针对单个项目的定制能力。如果你在某个项目里对这个技能有特殊的补充性要求比如代码审查时额外检查依赖版本升级问题就没法直接在项目级做增量覆盖了。另一种方式是符号链接symlink把项目级目录变成指向全局目录的软链。这样做的好处是技能配置只有一处你修改全局的文件所有项目的同名链接立即生效。这个思路有点类似CommonJS 里软链 node_modules的感觉省去了同步文件的麻烦。提示macOS 和 Linux 上创建软链用ln -s例如cd /path/to/your/project/.claude/skills ln -s ~/.claude/skills/code-review code-review在 Windows 上则需要用管理员权限运行终端执行mklink /D code-review %USERPROFILE%\.claude\skills\code-review路径带空格时要小心引号转义。符号链接最大的问题在于团队协作。Git 默认是可以跟踪符号链接的但团队成员在 Windows 和 macOS 上拉取代码后软链指向的绝对路径不一定是同一个全局目录经常导致链接失效。所以如果你在团队仓库里使用符号链接方式需要提前约定好全局技能的安装方式否则不同人的环境里技能会静默失效。4.3 切换后的验证清单和冲突处理无论用哪种方式切换完成后都应该做一次完整验证别急着关终端。我一般按下面四步走。第一步看列表进入项目根目录启动 Claude Code输入/skill确认技能列表里仍然能看到code-review。如果用了复制迁移且删除了项目级文件列表里显示的就是全局版如果用了软链列表效果一样但你看不到来源的区别。第二步测触发直接用自然语言让 Claude 执行一次这个技能比如帮我 code review 一下当前的改动。这一步骤非常关键因为复制迁移最容易出问题的点在于全局目录的 SKILL.md 内容虽然没变但触发环境变了。如果 SKILL.md 里写了相对路径引用从全局执行时可能找不到项目里的辅助文件。第三步确认优先级如果你还没有删除项目级原目录此时项目级和全局同名技能同时存在Claude Code 会优先使用项目级版本。换句话说你切换到全局这件事其实并没有生效。想要验证项目级已经被覆盖掉必须确保项目级目录里已经不存在同名技能。第四步做个 Git 检查运行git status看.claude/skills目录里是否还有遗留文件。如果你删除或软链了项目级技能Git 会显示对应的变更这时候记得提交让项目仓库保持干净状态。切到全局后团队其他人也不会再通过仓库获得这个技能要同步给团队成员全局技能包的更新方式。5. 常见问题与排查技巧实录5.1 技能列表不出现或者时有时无这是遇到最多的一个问题。通常原因有三个SKILL.md 的 frontmatter 写坏了、目录结构不对、Claude Code 没有重新扫描。frontmatter 写坏的情况很经典比如description字段里用了英文冒号配合长文本YAML 解析直接失败。我建议写完 SKILL.md 后用任意 YAML 校验工具检查一遍或者至少确认name和description字段下方的正文之间有一个空行。目录结构不对的情况主要是把 SKILL.md 直接放进了skills/根目录而忘记为每个技能单独建一个子目录。Claude Code 的规范要求一级子目录下才识别技能。至于重新扫描的问题上文已经提过修改技能后需要重启 Claude Code 或重新进入项目目录。5.2 项目级和全局同名冲突到底谁赢虽然前面已经提过项目级优先但实操中很多人还是会困惑为什么我把全局技能更新了一版项目里调用时还是旧行为原因就是项目级目录里仍然残留着同名技能Claude Code 永远先读它。这种情况的排查思路很清晰先在项目里用/skill查看列表如果列表中的技能名旁有特殊标记或来源提示就能判断加载的是哪个版本如果看不出区别就手动检查项目.claude/skills下是否有同名目录。解决冲突的办法也很直接要么删除项目级版本要么保留两个版本但把全局版本改名避免混淆。我一般不推荐同名共存因为后续维护时你很容易忘记哪个才是主人改文件时改错地方简直是家常便饭。5.3 切换后技能执行报错路径与权限问题从项目级切到全局后经常出现一种奇怪的现象技能能被正常列出、触发也没问题但执行到某一步就报错文件不存在或权限不足。绝大多数情况下是因为 SKILL.md 里写了硬编码的相对路径比如./scripts/analyze.py在项目级目录下这个路径存在切到全局后 Claude Code 会把当前工作目录作为基准于是找不到全局目录里的脚本。解决方案有两个一是在 SKILL.md 中明确使用$CLAUDE_SKILL_DIR这类环境变量来拼接辅助文件路径这样无论技能放在哪里Claude 都能准确找到它同目录下的脚本二是把所有辅助脚本放在操作系统能全局执行的位置比如/usr/local/bin技能文档里只写命令名。第一种方式更符合技能构造的天然习惯也便于技能包整体移动。第二个常见报错是权限问题尤其在全局目录里放了可执行脚本时需要保证脚本有x权限。注意Claude Code 在执行 Skill 时通常会以对话工作目录为基准调用命令。如果脚本文件本身放在全局技能目录而 SKILL.md 里用相对路径引用就会出现找不到文件的误报。遇到脚本明明在却执行失败的情况先检查引用方式别急着重装技能。5.4 技能加载速度变慢description 写得太宽泛当你的全局技能数量积累到十几个以后会明显感觉 Claude Code 在每次对话时的响应决策变得慢了一些这是正常的因为 Claude 似乎需要把当前需求和可用技能做匹配。如果技能数量不算多但依然很慢问题多半出在description里写得太宽泛导致每个技能都像是候选匹配成本变高。我后来的优化方式是刻意把 description 缩短且聚焦只写明任务类型、触发词和适用条件不要在这里长篇大论介绍执行细节。执行细节放正文里触发判断只看简介。这就像给技能做一个电梯演讲说得越清楚Claude 越容易快速排除无关技能整体响应速度也会上来。5.5 一个隐藏很深的坑软链在 Windows 上失败之前在某开发者那里遇到一个案例他在 Windows 上把项目级 Skills 改成全局软链后发现 Claude Code 在项目里完全识别不到这个技能。排查到最后是他在命令里写的是mklink /D code-review %USERPROFILE%\.claude\skills\code-review没有加引号导致路径中的空格被拆分成了多个参数。修改为带引号的完整路径后恢复正常。另外 Windows 上创建符号链接需要管理员权限普通终端执行时会报你没有权限执行此操作。如果你不想每次用管理员终端可以考虑改用目录联接junctionmklink /J类型它不需要管理员权限兼容性也更好。但需要注意的是目录联接在语义上和符号链接有细微差异在 Git 等工具里可能被识别为特殊的链接类型提交到仓库后团队其他人 clone 的效果和软链不完全一致。6. 实际使用中积累的心得和经验先说说我的分类习惯。我把自己的 Skills 分成三层第一层是个人效率类比如上面的 commit-helper、review-helper这些都放全局因为它们不依赖任何特定项目的技术栈第二层是技术栈通用类比如Python 项目单元测试助手React 组件脚手架生成器这些我也放全局但会在 description 里写明当且仅当项目使用 Python/React 时触发避免在无关项目中误调用第三层是业务专属类一律放项目级目录并提交到 Git 仓库比如某个项目的数据迁移脚本规范针对旧代码库的兼容性检查这类技能换一个代码库就是垃圾信息。关于从项目级切到全局的另一个经验是不要贪多求全。我早期恨不得把所有项目级技能全部升级为全局技能结果全局目录越来越臃肿每次对话的决策速度都开始让人着急。后来我控制了一个节奏同一时间全局技能尽量保持在十五个以内这个数量既覆盖大部分通用场景又不至于拖慢整体响应。一个技能如果连续两周没有触发一次我就会考虑它是否真的值得放在全局或者是不是 description 写得不够好导致触发率低。最后再分享一个写 SKILL.md 时很容易忽略的点给技能配上不做什么的说明。在正文中写清楚这个技能不做权限校验不生成测试代码不修改已有文件的格式能帮 Claude 在关键时刻避免执行过头。我在做代码审查技能时特意加了不要直接改代码只输出建议这一条实测下来能减少很多不必要的文件改动。这一个细节看起来简单但能让你后期维护体验提升非常多也建议你在自己的技能里加上。