Claude Code 的 Skills 机制刚出来那阵子我踩的第一个坑特别典型在项目根目录下建了.claude/skills写了个自动生成组件文档的 skill本地跑得好好的换到另一个仓库就完全失效。当时以为是 skill 写错了反复改 frontmatter、改触发描述折腾了大半天才反应过来——skill 的存放位置决定了它的作用域项目级和全局级是两套完全独立的加载路径。这件事之后我把 Skills 的安装、迁移、调试流程完整梳理了一遍也就是下面这些内容。如果你刚开始接触 Claude Code或者已经会写 skill 但一直搞不清为什么这个 skill 在这个项目能用、换个目录就没了这篇应该能帮你把项目级和全局级这两层结构彻底理清楚。我会从 skill 到底是什么讲起然后分别拆解两种作用域的安装方式、目录结构、迁移步骤最后给一套我自己在用的排查清单。1. 先把 Skills 的本质说清楚它不是插件是带元数据的提示词包很多人第一次听到 Skills 会下意识类比成 VS Code 插件或者 npm 包这个类比会带来一堆误解。Skills 不是可执行程序也不是需要编译的扩展它本质上就是一个目录 一个 SKILL.md 文件Claude Code 在启动时扫描特定路径把这些文件读进上下文当你的对话内容匹配到 skill 的描述时模型就按 SKILL.md 里写的流程去执行。1.1 SKILL.md 里到底装了什么一个最小可用的 skill 长这样--- name: component-doc description: 当用户要求为 React 组件生成文档时使用输出 props 表格和用法示例 --- # 组件文档生成 ## 执行步骤 1. 读取目标组件的源码文件 2. 提取 props 定义、默认值、类型 3. 按固定模板输出 Markdown 表格 4. 附上一段最小可运行示例frontmatter 里的name和description是给模型看的路由信息description写得越具体触发越准。正文部分才是真正的提示词模型会把它当成一份操作手册来遵循。这里有个反直觉的点skill 的正文不是给你看的文档是给模型看的指令所以写法要像在给一个新人交代任务而不是像在写 README。1.2 为什么它比直接写提示词更值得用你完全可以在对话里手打一段长提示词让 Claude 做同样的事但 skill 解决了三个问题。第一是复用写一次之后每次匹配到相关任务自动加载不用重复粘贴。第二是版本化skill 是文件可以进 git可以 review可以回滚团队里谁改了流程一目了然。第三是作用域隔离这也是本文的核心——你可以让某个 skill 只在特定项目生效也可以让它在你所有项目里都能用。我自己的习惯是凡是我每周至少要用三次的流程就固化成 skill凡是只在这个仓库有意义的流程就放项目级凡是跨项目通用的就提到全局。这个判断标准后面还会反复用到。1.3 一个常见的认知误区不少人以为装了 skill 之后 Claude 会自动变强其实不是。skill 只有在描述匹配到当前任务时才会被加载如果你的 description 写得太泛比如帮助写代码要么永远不触发要么到处乱触发。我见过最离谱的一个是把 description 写成处理各种开发任务结果每次对话它都想插一脚反而干扰了正常输出。所以 description 的写法是 skill 质量的分水岭这一点在项目级和全局级上的影响还不一样——全局 skill 因为覆盖面广description 写不好造成的干扰会被放大好几倍。2. 项目级 Skills跟着仓库走的那一层项目级 skill 是我最推荐的起步方式因为它天然跟着 git 走团队协作时不会出现我这儿能跑你那儿不能跑的情况。2.1 目录结构和你该放哪项目级 skill 的标准位置是仓库根目录下的your-project/ ├── .claude/ │ └── skills/ │ ├── component-doc/ │ │ └── SKILL.md │ └── api-mock/ │ └── SKILL.md ├── src/ └── package.json注意是.claude/skills/不是.claude/skill/也不是.skills/。这个路径我踩过坑——早期版本对目录名比较宽容后来收紧了写错就直接静默不加载没有任何报错。所以如果你发现 skill 不生效第一件事就是ls -la .claude/skills/确认路径拼写。每个 skill 一个独立子目录子目录名建议和 frontmatter 里的name保持一致虽然不强制但排查问题时能省很多事。2.2 从零装一个项目级 skill 的完整流程假设我要给当前项目加一个生成 changelog的 skill步骤如下。第一步建目录mkdir -p .claude/skills/changelog-gen第二步写 SKILL.md--- name: changelog-gen description: 当用户要求生成或更新 CHANGELOG 时使用基于 git log 按约定式提交分类整理 --- # Changelog 生成 ## 前置检查 - 确认仓库有 git 历史 - 确认存在 CHANGELOG.md没有则创建 ## 执行步骤 1. 运行 git log --oneline --no-merges 获取提交列表 2. 按 feat / fix / refactor / docs / chore 分类 3. 每个分类下按时间倒序排列 4. 合并进 CHANGELOG.md 的 Unreleased 段落 5. 不修改已发布版本的段落第三步验证加载。重启 Claude Code 会话然后问一句帮我生成 changelog观察它是否按你写的步骤走。如果没反应先检查路径再检查 description 是否和你的提问措辞差太远。2.3 项目级 skill 的协作优势与代价优势很直接进 git团队共享。新人 clone 下来就自带这套流程不用口头交接。而且项目级 skill 可以针对这个仓库的特殊约定来写比如所有 API 路由必须放在src/routes下组件必须用我们内部的BaseButton而不是原生 button这种强上下文的东西放全局就是灾难。代价是每个项目都要单独维护。如果你有十个仓库都需要同一个 skill就得复制十份改一次要改十处。这时候就该考虑提到全局了——但别急着提先看下一节的作用域判断。2.4 一个容易忽略的细节项目级 skill 的加载时机项目级 skill 是在 Claude Code 以该目录为工作目录启动时加载的。如果你在子目录里启动或者用了一些会改变工作目录的启动方式可能加载不到。我的做法是始终在仓库根目录启动这样最稳。另外如果你在 monorepo 里.claude/skills放在最外层根目录子包里的 skill 不会自动被识别需要显式配置或者干脆都放根目录。3. 全局 Skills一次配置所有项目通用全局 skill 解决的就是跨项目复用这个问题。装一次之后你在任何目录启动 Claude Code 都能用。3.1 全局目录在哪全局 skill 的位置在用户主目录下~/.claude/skills/ ├── commit-helper/ │ └── SKILL.md └── pr-review/ └── SKILL.mdWindows 上对应的是C:\Users\你的用户名\.claude\skills\。这个路径和项目级的.claude/skills结构完全一样区别只在于它在用户目录而不是仓库里。3.2 把项目级 skill 迁到全局的实操迁移不是简单复制粘贴有几个点要注意。第一步确认这个 skill 真的通用。判断标准它里面有没有硬编码某个项目的路径、某个仓库特有的命名、某个只有这个团队懂的缩写。如果有先抽象掉再迁。第二步复制目录cp -r .claude/skills/commit-helper ~/.claude/skills/第三步从项目里删掉。这一步很多人会漏结果同一个 skill 在项目级和全局级各有一份改了全局的发现没生效因为项目级的优先级更高把它盖住了。我建议迁移后立刻删掉项目里的那份避免双份维护。第四步换个目录验证。cd到一个完全无关的仓库启动 Claude Code测试 skill 是否触发。这一步是迁移是否成功的唯一标准。3.3 全局 skill 的 description 要写得更克制这是全局 skill 和项目级最大的区别。项目级 skill 的 description 可以写得比较激进因为它的作用范围就那么大误触发的影响有限。但全局 skill 会在你所有项目里参与匹配description 一旦写宽了会在各种不相关的场景里被拉进来稀释上下文、干扰输出。我的经验是全局 skill 的 description 要满足两个条件触发词足够具体排除条件写清楚。比如--- name: pr-review description: 当用户明确要求 review 一个 pull request 或 diff 时使用。不适用于普通的代码解释、不适用于单文件阅读 ---后半句不适用于……就是排除条件能显著降低误触发。这个技巧在项目级 skill 上可有可无在全局级上几乎是必须的。3.4 全局 skill 的版本管理问题全局 skill 不在任何 git 仓库里改坏了没有回滚点。我的做法是在主目录下单独建一个 git 仓库来管理~/.claude/skills或者至少定期打包备份。听起来有点小题大做但当你攒了十几个全局 skill、某天手滑删错一个目录时就知道这个习惯值多少钱了。4. 项目级和全局级同时存在时到底谁生效这是被问得最多的一个问题也是我一开始踩坑的地方。答案是两层都会被扫描项目级优先。但优先的具体表现需要说清楚不然容易误判。4.1 同名 skill 的覆盖规则如果项目级和全局级有同名 skill项目级的那份生效全局的被忽略。这个设计是合理的——项目级代表这个仓库的特殊约定应该盖过通用版本。但要注意覆盖是按name字段判断的不是按目录名。所以如果你目录名一样但 frontmatter 里的 name 不同两份都会加载可能造成混乱。保持目录名和 name 一致这个习惯在这里就体现出价值了。4.2 不同名 skill 的共存不同名的 skill 会同时存在模型在匹配时看到的是两层的合集。这意味着全局 skill 的 description 如果和某个项目级 skill 语义重叠可能出现两个都被拉进来、指令打架的情况。我遇到过一回全局有个通用代码审查skill项目里有个本仓库审查规范skill结果模型把两套规则混着用输出里既有通用建议又有项目约定看着很乱。解决办法是给全局 skill 的 description 加上当项目内没有更具体的审查 skill 时使用这类兜底措辞。4.3 一张表看清两层差异维度项目级全局级存放路径repo/.claude/skills/~/.claude/skills/作用范围仅当前仓库所有项目是否进 git是团队共享否个人配置优先级高同名覆盖全局低description 写法可以激进必须克制带排除条件适用场景仓库特有约定跨项目通用流程维护成本每仓库一份一处修改全局生效这张表建议存下来每次纠结这个 skill 该放哪的时候对照一下基本能秒判。4.4 一个判断作用域的小技巧拿不准的时候问自己一句话这个 skill 换到隔壁仓库还成立吗成立就放全局不成立就放项目级。如果介于两者之间比如大部分项目成立但有两个特殊仓库要改那就放全局然后在特殊仓库里放一个同名项目级 skill 覆盖它。这个全局打底 项目覆盖的模式是我目前用得最顺的。5. 装完之后不生效按这个顺序排查skill 不触发是最高频的问题我把排查链路整理成固定顺序基本能覆盖九成情况。5.1 第一步永远是确认路径# 项目级 ls -la .claude/skills/ # 全局级 ls -la ~/.claude/skills/确认目录名是skills不是skill确认每个 skill 有自己的子目录确认子目录里有SKILL.md大小写敏感skill.md不行。这一步能解决一半以上的不生效。5.2 第二步检查 frontmatter 格式SKILL.md开头的 frontmatter 必须是标准 YAML用---包裹name和description两个字段不能少。常见错误包括冒号后面没空格、description 里用了未转义的特殊字符、---只写了一半。这些错误不会报错只会静默失败所以只能靠肉眼核对。5.3 第三步看 description 和你的提问是否对得上skill 的触发靠语义匹配如果你的 description 写的是生成组件文档而你问的是帮我写个 README那大概率不触发。测试时用 description 里的原词去问先确认能触发再逐步换成更自然的措辞看泛化能力。5.4 第四步确认没有同名覆盖如果你在项目里测试一个全局 skill 没反应先看看项目级有没有同名 skill 把它盖了。反过来也一样。用find快速对比find .claude/skills ~/.claude/skills -name SKILL.md 2/dev/null把两边的 name 列出来对比一眼就能看出有没有冲突。5.5 第五步重启会话skill 是在会话启动时扫描的你在会话进行中新建的 skill 文件当前会话不一定能感知到。改完 skill 之后开一个新会话再测这是最省时间的习惯。提示排查时不要一次改多个地方每次只动一个变量否则你无法确定到底是哪一步修好的。我早期就是又改路径又改 description结果好了也不知道为什么好下次遇到还是不会。6. 我踩过的几个真实坑以及现在的固定习惯最后这部分是纯经验文档里不会写但每一个都让我浪费过至少半小时。6.1 坑一在子目录启动导致项目级 skill 不加载有次我在packages/web下启动 Claude Code发现项目级的 skill 全没了。原因是工作目录变了.claude/skills是相对于工作目录找的。现在的习惯是永远在仓库根目录启动需要处理子包时用对话里指定路径而不是cd进去。6.2 坑二全局 skill 写太宽污染所有项目前面提过我有个全局 skill 的 description 写成了处理各种开发任务结果它在每个项目里都抢着触发。后来我把全局 skill 的 description 全部重写了一遍每条都加上明确的适用边界和排除条件。全局 skill 宁少勿滥我现在全局目录里只留了五个真正跨项目通用的其余全下沉到项目级。6.3 坑三迁移时忘了删项目里的旧副本这个坑最隐蔽因为表面上一切正常直到你改了全局版本发现没生效——因为项目级那份优先级更高一直在盖着。现在的固定动作是迁移完立刻rm -rf项目里的旧目录然后git status确认删除被记录。6.4 我现在的固定习惯新 skill 一律先在项目级写用满两周确认稳定后再考虑提全局全局 skill 的 description 必须包含排除条件每次改完 skill 开新会话测试不在旧会话里验证~/.claude/skills单独用 git 管理改坏了随时回滚定期用find对比两层目录清理重复和废弃的 skill这套习惯跑下来我现在基本不会再遇到skill 莫名其妙不生效的情况。Skills 这个机制本身不复杂复杂的是作用域这层——把项目级和全局级的分工想清楚剩下的就是写 description 的手感问题了而那个只能靠多写多测慢慢磨。