如果你已经用过几天 Claude Code，大概率碰到过这个场景：每次新建一个项目，都要把项目结构、代码规范、发布流程这些背景信息重新向 Claude 解释一遍。第一次可以忍，第二次开始烦躁，第三次我就认真研究起 Claude Code 的 Skills 机制。一开始我以为它只是“把常用命令封装得短一点”的小工具，真正用上后才发现，它更像一份给 Claude 预置的“工作手册”，按需展开、随时调用。
这篇文章写给两类人：一类是刚装好 Claude Code、想搞清楚 Skills 到底怎么装的新手；另一类是已经把某个 Skill 在单个项目里调通、想把它提升为全局 Skills、让所有新项目都能直接复用的同学。内容分成两部分：先讲项目级怎么装，再讲我实际总结出来的“项目级切到全局”的路径。结尾附带我的必装清单和几个踩坑记录，全是从实操里得到的判断，不是照着文档念。
1. Skills核心机制：这是一本给Claude看的手册，不是插件
先说一个认知问题：Skills 不是传统意义上那种有入口、有界面的“插件”。你把一个技能包放进对应目录，它不会弹窗，不会常驻，也不会增加什么可视化的面板。Claude 在对话里遇到相关需求时，会自己去扫描技能目录，读取合适的 SKILL.md，然后按里面的步骤执行。它更接近一份工作手册加检查清单。
1.1 为什么是 SKILL.md：一个文档载体的目录结构
一个 Skill 在磁盘上就是一个目录，目录里至少有一个SKILL.md文件，通常还可以放脚本、模板、样例数据。典型的目录结构长这样：
.claude/ skills/ release-notes/ SKILL.md scripts/ collect_commits.pySKILL.md是核心。文件头部有一段 YAML 格式的 frontmatter，用来声明技能的名称、描述、触发场景；正文部分则用 Markdown 写清楚操作步骤、边界条件和注意事项。Claude 读到这份文档，就知道“这个技能是干什么的、什么时候该用、用的时候按什么顺序做”。
这个设计的巧妙之处在于：它把“教 Claude 怎么做”这件事从一次性对话中抽了出来，变成可版本管理、可复用、可分享的文件。你在 A 项目里调通了一套处理逻辑，复制到 B 项目就能用，不需要重新调教。
1.2 项目级与全局级到底差在哪
在 Claude Code 的目录约定里，Skills 有两个存放层级：
- 项目级：放在当前项目根目录下的
.claude/skills/里，只有在这个项目打开会话时才会被扫描到。 - 全局级：放在用户主目录下的
~/.claude/skills/里，任何目录下启动 Claude Code 都能识别到。
用一句话概括就是：项目级影响一个仓库，全局级影响你所有的仓库。
所以“从项目级切到全局”这个操作，本质上不是安装一个新技能，而是把已经验证过的技能从局部作用域提升到全局作用域，让它变成你的个人工作流基础设施。
1.3 从“项目内尝试”开始，比一开始就全局更靠谱
我看到不少人一上来就把 Skills 放进全局目录，结果发现这个技能在某个特定项目里不太适配，又得去改，改了之后还影响其他项目。我的建议是：新技能先在项目级目录里跑通、跑顺，再决定要不要全局化。
项目级的试错成本很低：改动只影响当前仓库，不满意直接删目录就行，不会波及其他工作环境。而全局化等于把这个技能“发布”到所有项目，一旦有路径依赖或环境假设，翻车面会被放大。
2. 动手前的环境检查：目录、版本与两个容易被忽略的细节
在正式动手之前，有几个前置检查点。这些检查花不了五分钟，但能省掉后面大把排查时间。
2.1 确认基础环境是可用的
首先要确保 Claude Code CLI 本体能正常跑起来，这听起来像废话，但我见过好几次“Skill 没生效”排查到最后，发现是 CLI 版本太旧，根本不支持 Skills 机制的目录扫描。建议先确认版本：
claude --version如果你用的是 VS Code 里的 Claude Code 扩展，注意它和命令行版共用同一个配置目录，所以下面的目录约定同样适用。更稳的做法是跑一次环境自检，很多配置问题会在这一步直接暴露出来：
claude doctor如果这一关没过，先解决 CLI 本身的安装和登录问题，再来配置 Skills。
2.2 项目目录规划：不要用怪异的命名
Skills 的目录名和SKILL.md里的name字段，建议全部用小写字母加连字符，比如release-notes、pr-review。
我刚开始在图里图方便，给一个技能命名成APIReview，大小写混着来，后面在某些自动触发场景里表现就不太稳定。倒不是系统区分不了大小写，而是这类命名在跨平台复制、写脚本、做校验时容易埋坑。既然目录名本身就能表达意图，就没必要给自己增加认知负担。
顺便检查一下项目里有没有.claude目录。很多项目默认不会在仓库里显示隐藏目录，如果你第一次创建，大概率需要自己建：
mkdir -p .claude/skills2.3 不要把整个 .claude 目录都推上仓库
这里有个容易踩的坑：.claude 目录里不是所有内容都适合提交到 Git。
项目级的 Skills 是团队协作资产，可以放进版本库；但.claude/settings.json里如果包含本机相关配置，就要谨慎处理。更稳妥的方式是在.gitignore里放行skills/、忽略不必要的本地配置：
.claude/settings.local.json团队的 Skill 通过 Git 分发后，成员拉下来直接就能用，这是项目级 Skills 最大的价值之一。但如果你把个人偏好也塞进去，别人用起来就会有环境差异带来的各种问题。
3. 项目级Skills安装三步走：建目录、写文档、验证调用
我把安装过程压缩成可复制的三步：建目录、写 SKILL.md、在会话里验证。整个过程不需要重启电脑，也不需要编译任何东西。
3.1 一个可以直接抄的示例：release-notes
我以实际在用的release-notes技能为例，看完这个例子，你基本就知道一份能用的 Skill 长什么样了。
第一步，创建目录：
mkdir -p .claude/skills/release-notes第二步，在目录里创建SKILL.md：
--- name: release-notes description: 在当前仓库生成发布说明。当用户要求“生成发布说明”“整理 CHANGELOG”“列出从某个分支到 HEAD 的提交清单”时使用。不要在我只问某一次提交内容时使用。 --- # release-notes ## 目标 根据 Git 提交记录，生成一份结构清晰的发布说明草稿。 ## 执行步骤 1. 确认当前分支和基准分支，基准分支默认是 main。 2. 执行命令获取提交记录： `git log --no-merges --pretty=format:"%h %s" <base>..HEAD` 3. 按类型对提交信息分类：feat、fix、refactor、docs、chore。 4. 每个类别筛选出最重要的 2-3 条，合并同质内容。 5. 输出草稿格式如下： - 版本号建议 - 新功能 - 问题修复 - 技术调整 - 其他变化 6. 先让用户确认，再把最终内容写入 CHANGELOG.md。 ## 注意事项 - 不包含 merge 提交。 - 如果提交信息本身不规范，先提醒用户，不要强行猜测。 - 不修改 package.json 版本号，只生成文档。这个技能的逻辑不复杂，但它提供了一套清晰的执行路径。Claude 看到“生成发布说明”的请求后，会读取这份手册，按步骤执行，而不是现场发挥。
3.2 frontmatter 里的 description 是自动触发的关键
很多人写 SKILL.md 时只关注正文，忽略了 description 的打磨。实际上，description 决定了 Claude 在什么场景下会主动翻出这份手册。
描述写得越具体，自动触发越准。我会在描述里写清楚三件事：
- 什么时候用：用户说哪些话、涉及哪些操作时该读取。
- 什么时候不用：排除容易混淆的场景。
- 边界是什么：不要越权处理哪些内容。
比如上面release-notes的描述里我特意加了一句“不要在我只问某一次提交内容时使用”。这句话看着多余，但在实测里非常管用，能大幅降低误触发概率。
3.3 在项目会话里做验证
写完文件后，在当前项目的 Claude Code 会话里直接测试。最简单的方式是手动触发：在输入框里输入斜杠命令的写法，然后空格加参数。
也可以用自然语言触发验证：直接说“帮我把从 main 到当前分支的提交整理成发布说明”。如果 Skill 生效，Claude 会参考 SKILL.md 里的步骤，先确认分支范围，再执行git log获取提交记录，最后输出分类草稿。
如果没生效，先不要急着改文件。大多数情况下是路径写错了，或者文件名不是SKILL.md（大小写必须完全一致）。这个坑非常隐蔽，因为目录结构看起来没区别，但扫描规则是精确匹配文件名。
4. 从项目级切到全局：迁移顺序、文件依赖和优先级判断
当一个 Skill 在你手头的几个项目里都被验证过，并且你发现自己每次新建项目都在重复同样的配置时，就该考虑把它转成全局 Skill 了。
4.1 值得全局化的三个判断标准
我判断一个 Skill 是否值得全局化，只看三点：
- 跨项目复用：这个技能是不是只要是个项目就能用？比如提交信息规范化、PR 审查清单、日志排查这些，和具体业务逻辑无关的，天然适合全局。
- 行为中性：技能里不含某个项目的专属路径、专属命名和专属约束。如果里面有“这个项目的前端目录是 src/views”这类话，它还没到全局化的时机。
- 依赖已独立：技能如果依赖脚本文件，这些脚本必须跟随 Skill 目录一起迁移，不能引用项目内的特定路径。
如果三条都满足，就可以动手了。
4.2 迁移三步走：复制、检查依赖、验证
假设你已经有了项目级 Skill 目录：
my-project/.claude/skills/release-notes/第一步，复制到全局目录：
mkdir -p ~/.claude/skills cp -r .claude/skills/release-notes ~/.claude/skills/在 Windows 环境下，全局目录对应的是：
%USERPROFILE%\.claude\skills\第二步，检查 SKILL.md 里的依赖路径。这一步是迁移中最容易翻车的地方：
- 如果 Skill 引用了内部脚本文件，比如
scripts/collect_commits.py，确认脚本目录也一并复制过去了。 - 如果正文里写了读取
.env或某个固定路径的配置文件，全局环境下不一定存在这个文件，必须改成“由用户在对话中提供路径”或“执行前先确认文件存在”。 - 如果技能里有“项目专属”的描述，比如“本项目使用 pnpm”，全局化前建议改成“优先使用 pnpm，若无则使用 npm”，把硬编码变成可选条件。
第三步，找一个全新的项目目录启动 Claude Code，用自然语言触发一次。确认生效后，全局化才算完成。
4.3 项目级和全局同名：优先级经验笔记
迁移完成后会遇到一个问题：如果项目里刚好存在同名的 Skill，到底谁生效？
从我的实际使用体验来看，项目级目录里的同名 Skill 会优先于全局目录里的 Skill。这个设计很合理：团队可以在仓库里放一版适合当前项目的定制技能，个人全局技能只是兜底；项目想覆盖个人习惯时，放一个同名目录即可。
如果你改了全局 Skill 却发现没生效，第一反应先去项目目录查一遍：
ls .claude/skills如果有同名目录，那问题一般就是被项目级覆盖了，而不是配置写错。
5. 我的必装Skills清单：有明确用途才留，不追求数量
“必装”这两个字很容易让人误解成“装得越多越好”。我实际体验下来，Skills 这个东西，质量远比数量重要。
每个 Skill 的 description 都会被 Claude 在对话时扫描匹配。你装一百个技能，等于让它在每次回答前多判断一百次“这个技能要不要用”。判断本身有开销，误触发的概率也会上升。我个人的习惯是控制在十个以内，每一个都有明确的使用场景。
下面是我长期留在全局目录里的几个技能，不一定适合所有人，但可以给你一个选型参考：
| 技能名 | 适用场景 | 为什么值得留 |
|---|---|---|
| git-commit-police | 写提交信息、整理提交模板 | 统一提交规范，跨项目通用，能减少 review 时对提交信息的讨论 |
| pr-review-checklist | 提交 PR 前的自检 | 把遗漏项检查从记忆变成流程，不容易漏掉测试、文档和兼容性 |
| release-notes | 整理发布说明、更新 CHANGELOG | 上面示例讲过，适合需要定期发布的项目 |
| log-troubleshooter | 看日志、定位线上异常 | 让 Claude 先分析日志格式再给出排查路径，避免凭猜测乱说 |
| api-cleanup | 清理冗余接口和未使用的导出 | 对老项目重构特别有用，能自动找出未被引用的函数和变量 |
每个技能的目录结构都是一样的：一个名字清晰的小目录，一个写满操作手册的SKILL.md。
多说一句：社区里有很多现成 Skills 包，down 下来之后不要直接用，先读一遍 SKILL.md 里的内容。你很快就会发现，有些包的描述写得很泛，触发条件模糊不清，这种装到全局只会增加自动触发的噪音。花十分钟改一改 description，效果会好很多。
6. 排查笔记：Skill不生效、被覆盖和上下文膨胀的经验
最后这部分是排查经验合集。我不打算写成一份标准 FAQ，只挑几个我实际踩过的、网上不太容易查到的坑来说。
6.1 路径大小写和目录层级
我经历过最诡异的“不生效”，最后查到原因是文件命名成了skill.md，而系统要求的是SKILL.md。Linux 和 macOS 的文件系统默认区分大小写，在 Windows 上可能没那么严格，但 Claude Code 的扫描逻辑是按精确名称匹配的。
还有一点：Skill 的目录结构要求“技能目录的直接子目录里必须有 SKILL.md”。如果你多套了一层，比如：
skills/ release-notes/ v1/ SKILL.md那么扫描器可能根本不会识别v1这一层。想区分版本，用技能名加后缀更可靠，比如release-notes-v2，而不是嵌套子目录。
6.2 配置文件里可以禁用技能
新版 Claude Code 支持通过配置文件对 Skills 做更细的控制。如果你在某个项目里不想让某一个全局技能参与自动触发，可以在项目的.claude/settings.json里把它列入禁用列表。具体字段名在不同版本里略有差异，不要凭记忆写死，跑一次claude doctor看输出提示，或者统一用“技能目录改名”这个最朴素的办法——把目录名前加_，扫描器就会跳过它，需要时再改回来。
这个操作比删目录稳妥，因为技能内容还在，随时能恢复。
6.3 更新 Skill 后，一定要开新会话再测
Skills 的本质是文本文件，所以更新它就是在改文本。但 Claude Code 在对话中不会每次都重新扫描所有技能文件——这里我实际遇到的坑是：更新完SKILL.md后，在同一个会话里继续测试，发现行为还是旧的。
解决办法很简单：更新文件后，新开一个会话再验证。新会话会重新加载技能目录，旧会话里的一些索引已经在前一轮对话中固化，不会自动跟着文件变更。这也解释了为什么有时候你觉得改了没生效，其实文件已经改对了，只是会话状态没刷新。
6.4 上下文膨胀是隐性问题
每个被匹配到的 Skill，其 SKILL.md 内容都会作为参考信息进入上下文。如果某个技能的手册写得特别长，每次都带几万字进去，对整体响应质量是有影响的。
这也是为什么 SKILL.md 的正文要尽量精炼。能用十条要点表达清楚，就不要写两万字。好的 Skill 文档应该是“精简到不能再删”的：既保证 Claude 能看懂步骤，又不让它背上沉重的阅读负担。
写到这里，最后分享一个我自己的操作习惯：每次新建项目时，先看一眼当前项目的.claude/skills下放了什么，再想想全局目录里有没有重复的。这个习惯帮我避免了很多“项目里明明有全套配置，Claude 还是用错了规则”的情况。Skills 的价值不在多，而在于边界清晰：什么场景用项目级的，什么场景交给全局兜底，心里有数，整个工作流才真正顺。
