1. Skills核心机制：这是一本给Claude看的手册，不是插件

先说一个认知问题：Skills 不是传统意义上那种有入口、有界面的“插件”。你把一个技能包放进对应目录，它不会弹窗，不会常驻，也不会增加什么可视化的面板。Claude 在对话里遇到相关需求时，会自己去扫描技能目录，读取合适的 SKILL.md，然后按里面的步骤执行。它更接近一份 工作手册加检查清单 。

1.1 为什么是 SKILL.md：一个文档载体的目录结构

一个 Skill 在磁盘上就是一个目录，目录里至少有一个 SKILL.md 文件，通常还可以放脚本、模板、样例数据。典型的目录结构长这样：

SKILL.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 机制的目录扫描。建议先确认版本：

如果你用的是 VS Code 里的 Claude Code 扩展，注意它和命令行版共用同一个配置目录，所以下面的目录约定同样适用。更稳的做法是跑一次环境自检，很多配置问题会在这一步直接暴露出来：

如果这一关没过，先解决 CLI 本身的安装和登录问题，再来配置 Skills。

2.2 项目目录规划：不要用怪异的命名

Skills 的目录名和 SKILL.md 里的 name 字段，建议全部用小写字母加连字符，比如 release-notes 、 pr-review 。

我刚开始在图里图方便，给一个技能命名成 APIReview ，大小写混着来，后面在某些自动触发场景里表现就不太稳定。倒不是系统区分不了大小写，而是这类命名在跨平台复制、写脚本、做校验时容易埋坑。既然目录名本身就能表达意图，就没必要给自己增加认知负担。

顺便检查一下项目里有没有 .claude 目录。很多项目默认不会在仓库里显示隐藏目录，如果你第一次创建，大概率需要自己建：

2.3 不要把整个 .claude 目录都推上仓库

这里有个容易踩的坑： .claude 目录里不是所有内容都适合提交到 Git 。

项目级的 Skills 是团队协作资产，可以放进版本库；但 .claude/settings.json 里如果包含本机相关配置，就要谨慎处理。更稳妥的方式是在 .gitignore 里放行 skills/ 、忽略不必要的本地配置：

团队的 Skill 通过 Git 分发后，成员拉下来直接就能用，这是项目级 Skills 最大的价值之一。但如果你把个人偏好也塞进去，别人用起来就会有环境差异带来的各种问题。

3. 项目级Skills安装三步走：建目录、写文档、验证调用

我把安装过程压缩成可复制的三步：建目录、写 SKILL.md、在会话里验证。整个过程不需要重启电脑，也不需要编译任何东西。

3.1 一个可以直接抄的示例：release-notes

我以实际在用的 release-notes 技能为例，看完这个例子，你基本就知道一份能用的 Skill 长什么样了。

第一步，创建目录：

第二步，在目录里创建 SKILL.md ：

这个技能的逻辑不复杂，但它提供了一套清晰的执行路径。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 是否值得全局化，只看三点：

1. 跨项目复用 ：这个技能是不是只要是个项目就能用？比如提交信息规范化、PR 审查清单、日志排查这些，和具体业务逻辑无关的，天然适合全局。
2. 行为中性 ：技能里不含某个项目的专属路径、专属命名和专属约束。如果里面有“这个项目的前端目录是 src/views”这类话，它还没到全局化的时机。
3. 依赖已独立 ：技能如果依赖脚本文件，这些脚本必须跟随 Skill 目录一起迁移，不能引用项目内的特定路径。

如果三条都满足，就可以动手了。

4.2 迁移三步走：复制、检查依赖、验证

假设你已经有了项目级 Skill 目录：

第一步，复制到全局目录：

在 Windows 环境下，全局目录对应的是：

第二步，检查 SKILL.md 里的依赖路径。这一步是迁移中最容易翻车的地方：

• 如果 Skill 引用了内部脚本文件，比如 scripts/collect_commits.py ，确认脚本目录也一并复制过去了。
• 如果正文里写了读取 .env 或某个固定路径的配置文件，全局环境下不一定存在这个文件，必须改成“由用户在对话中提供路径”或“执行前先确认文件存在”。
• 如果技能里有“项目专属”的描述，比如“本项目使用 pnpm”，全局化前建议改成“优先使用 pnpm，若无则使用 npm”，把硬编码变成可选条件。

第三步，找一个全新的项目目录启动 Claude Code，用自然语言触发一次。确认生效后，全局化才算完成。

4.3 项目级和全局同名：优先级经验笔记

迁移完成后会遇到一个问题：如果项目里刚好存在同名的 Skill，到底谁生效？

从我的实际使用体验来看， 项目级目录里的同名 Skill 会优先于全局目录里的 Skill 。这个设计很合理：团队可以在仓库里放一版适合当前项目的定制技能，个人全局技能只是兜底；项目想覆盖个人习惯时，放一个同名目录即可。

如果你改了全局 Skill 却发现没生效，第一反应先去项目目录查一遍：

如果有同名目录，那问题一般就是被项目级覆盖了，而不是配置写错。

5. 我的必装Skills清单：有明确用途才留，不追求数量

“必装”这两个字很容易让人误解成“装得越多越好”。我实际体验下来， Skills 这个东西，质量远比数量重要 。

每个 Skill 的 description 都会被 Claude 在对话时扫描匹配。你装一百个技能，等于让它在每次回答前多判断一百次“这个技能要不要用”。判断本身有开销，误触发的概率也会上升。我个人的习惯是控制在十个以内，每一个都有明确的使用场景。

下面是我长期留在全局目录里的几个技能，不一定适合所有人，但可以给你一个选型参考：

每个技能的目录结构都是一样的：一个名字清晰的小目录，一个写满操作手册的 SKILL.md 。

多说一句：社区里有很多现成 Skills 包，down 下来之后不要直接用，先读一遍 SKILL.md 里的内容。你很快就会发现，有些包的描述写得很泛，触发条件模糊不清，这种装到全局只会增加自动触发的噪音。花十分钟改一改 description，效果会好很多。

6. 排查笔记：Skill不生效、被覆盖和上下文膨胀的经验

最后这部分是排查经验合集。我不打算写成一份标准 FAQ，只挑几个我实际踩过的、网上不太容易查到的坑来说。

6.1 路径大小写和目录层级

我经历过最诡异的“不生效”，最后查到原因是文件命名成了 skill.md ，而系统要求的是 SKILL.md 。Linux 和 macOS 的文件系统默认区分大小写，在 Windows 上可能没那么严格，但 Claude Code 的扫描逻辑是按精确名称匹配的。

还有一点：Skill 的目录结构要求“技能目录的直接子目录里必须有 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 的价值不在多，而在于边界清晰：什么场景用项目级的，什么场景交给全局兜底，心里有数，整个工作流才真正顺。