Claude Code 的 Skills 这个能力我是从把长段指令堆进 CLAUDE.md 开始吃透的。过去每次新开一个项目都要把一套提示词模板复制过去复制得多了维护就开始失控改一个规则得同步好几个仓库漏一处就是一次不稳定的体验。后来真正开始用 Skill尤其是把“项目级”和“全局”这两种安装方式搞明白之后才意识到它解决的不只是反复复制的问题而是让指令本身变得有结构、有归属、可管理。这篇就围绕怎么装、怎么从项目级切换成全局来写把底层逻辑和实际操作的弯路一并讲清楚。我会先解释 Skill 的组成和它跟 CLAUDE.md 这类普通指令文件的区别再讲项目级怎么落地接着重点拆解切到全局的几种方式和适用场景最后用一个完整的实践案例加问题排查来做收尾。如果你已经在每次对话前把一长串规则贴进去或者正在为“这堆技能到底放哪”发愁这篇文章应该能帮你省不少时间。1. 理解 Skill 的本质与文件结构1.1 什么是 Claude Code 的 Skill如果你把 Claude Code 本身看成一个“能看懂项目并帮你写代码”的执行者那 Skill 就是它的能力包。一个 Skill 本质上是一个目录目录里有一份核心说明文件 SKILL.md外加可选的支持文件比如模板、脚本、示例、参考文档。每次打开 Code 的时候它会扫描两个维度下的技能目录把描述信息加载进来等到对话里出现匹配场景技能就会被激活指导模型按其中定义的流程去落地。这里容易有一个误区Skill 不是插件机制也不是独立的代码快速执行规则文件。它更像是“给模型的一份带前置条件和流程约束的操作手册”。Skill 里的内容并不决定模型会不会写代码而是在模型已经具备能力的前提下规定它用什么顺序做、做什么检查、按什么风格输出以及要避免什么坑。1.2 SKILL.md 的核心结构一个标准的 Skill 我通常以这种方式组织my-skill/ SKILL.md templates/ scripts/ examples/SKILL.md 是入口。它的开头有一段 YAML 格式的 frontmatter里面最核心的两个字段是 name 和 description。description 的作用比大多数人以为的大得多后续会专门展开现在就记住一句话它是技能被选中的路由条件写得太宽泛模型就容易在无关场景里用它。正文部分是 Markdown写清楚这几类信息技能在什么情况下被激活、产出什么结果执行步骤建议用编号列出保证顺序稳定对已有代码或配置不得改动哪些部分输出格式规范、检查清单以及常见的兜底处理一个重要的建议是不要在 SKILL.md 里写“你是一个 XXX 专家”这类空泛的角色设定而是写“在执行任务时优先使用哪些方法、按什么顺序执行”。前者没有操作约束力后者才能真正改变每次运行的表现。1.3 Skill 和 CLAUDE.md 的差异很多人会问既然 CLAUDE.md 也能写规则为什么还要单独搞 Skill它们最大的差异在触发机制。CLAUDE.md 是每次会话都会自动加载等于模型的默认背景音什么任务都会带上而 Skill 是靠描述被按需调用的平时只占用一句描述信息真正执行时才把整份手册交给模型。这个区别直接影响指令维护的方式。放进 CLAUDE.md 的规则要短要普适否则无关任务比重太高既浪费上下文又会让响应风格变得拖沓。放进 Skill 的内容则可以把场面铺大步骤、细节、边界条件都可以写足因为它只会在需要时被展开。从另外一个角度看CLAUDE.md 更像是“团队的开发公约”而 Skill 是“特定场景的专项工作手册”。如果你发现自己写了很多带条件前缀的规则比如“如果要重构某个模块请先做 X”这种就是典型的该拆成 Skill 的内容。2. 项目级 Skill 的安装与使用2.1 一步步搭一个项目级 Skill项目级的安装路径很容易确认。在项目根目录下创建 .claude/skills 目录把一个 Skill 放进去就能让这个项目内的所有会话看到它。mkdir -p .claude/skills/docs-format cd .claude/skills/docs-format touch SKILL.md里面的具体内容也可以用 Claude Code 自己生成把需求描述清楚让模型帮忙起草。我第一次搭的时候直接手工写了一个文档格式 Skill结果走了不少弯路后来改成让它先输出草稿自己再做一轮删改效果好得多。把 SKILL.md 填好之后重启一个会话可以在对话中直接尝试触发它确认是否能被识别。一个注意点是会话中途新增或修改了 Skill 目录当前会话不一定能立刻加载到重启会话是最稳妥的验证方式。2.2 检查已生效的 Skill想确认当前项目加载了哪些 Skill可以查看配置文件。Claude Code 会维护一份加载清单列出项目级和全局有效的技能。用命令查看属于最常见的做法claude config get skills输出里能看到每个 Skill 的路径来源是项目级还是全局项一目了然。这里有个判断优先级的问题项目级和全局如果出现同名 Skill一般情况下项目级会覆盖全局。规则很简单越靠近项目、越贴近具体上下文的配置优先度越高。遇到同名冲突优先检查是不是项目目录里残留了一份旧版本这是最容易被忽略的坑。2.3 为什么先从项目级开始我强烈建议凡是新写的 Skill第一站都放到项目级。原因不是项目级更方便而是它给了你足够的试错空间。Skill 是会被模型反复执行的操作手册一旦有流程或描述错误影响面非常广。放到某个具体项目里后先跑两三个真实任务观察输出的稳定程度。如果这个 Skill 会让每个任务的执行时间变长、或者导致模型过度解读步骤当场就能察觉。另外项目级天然适合和当前仓库的代码风格绑定验证比如代码审查类技能只有放到真实代码仓库里才有足够的样本来检验它的规则是否合理。等它在真实项目里稳定运行了再考虑是否纳入全局。2.4 项目级 Skill 的团队协作项目级还有一层价值是它可以进版本库。.claude 目录提交到仓库后团队所有成员拉下代码就能获得同样的技能配置不需要单独分发。这里要提醒一点既然是团队共享里面就不要写个人风格太强的要求比如“换行统一用两行空行”这种无关痛痒的偏好写多了反而容易让模型输出变得死板。真正该放的是对质量有实质影响、团队一致认可的约束比如安全规则、命名约定、必须执行的检查步骤。如果某个 Skill 包含带保密性质的内容比如内部工具的使用方式、线下服务的连接方式要谨慎评估能不能进仓库。团队内部使用通常没问题但如果项目开源技能目录也会被一并公开提前清理敏感信息是必须做的。3. 从项目级切换到全局的完整流程3.1 全局 Skill 的存放位置切换的第一步是先搞清楚全局在哪。在常用的 Claude Code 目录结构中全局 Skill 放在用户主目录下的 .claude/skills 目录。以 Unix 类系统为例mkdir -p ~/.claude/skills这个目录里放置的每个 Skill 会对该用户所有项目生效不需要在项目根目录重复摆放。需要留意的是“全局”不等于“每个项目”。它指的是用户账户级别从这个维度理解你在这个机器上开启的任何会话都能感知到它。3.2 用配置命令把项目级技能加到全局最常见的做法是直接修改配置把当前项目里的技能路径注册到全局范围。在 Claude Code 中这类操作一般通过 config 相关子命令完成claude config add -g skills ~/.claude/skills/my-skill-g 的含义就是全局。执行完这条命令后新开的任意项目会话都可以使用对应技能。如果想移除某个已加载的技能使用对应删除命令claude config remove -g skills my-skill具体的命令名称根据版本不同可能有差异运行claude config --help或者直接看补全提示就能获得准确写法。我更想强调的是操作思路它本质上是维护一份技能清单文件命令只是修改这份清单的快捷键理解了底层是文件配置排查问题时就不会被命令参数带偏。补充一个细节配置全局技能时不一定要求这个路径本身就挂在 ~/.claude/skills 下。理论上你可以把特定项目里的技能路径直接注册为全局项只要该路径在启动时会保持稳定存在。但从维护角度我依然建议按默认约定把文件放到全局目录路径统一未来盘技能列表更清楚。3.3 手动迁移的常规步骤如果不用配置命令手动把技能目录挪到全局目录也是可行的操作路径如下确认源目录结构和内容完整特别注意 SKILL.md 是否存在且格式正确复制目录到全局技能目录比如cp -r .claude/skills/xxx ~/.claude/skills/在项目配置中移除该技能的项目级注册避免同名覆盖导致后续更新不生效开启一个新项目或新会话查看 config get skills 的输出确认全局项已被识别手动搬运很简单但它有一个我踩过几次的坑内容同步。项目级那份和全局那份如果都保留后续在任一位置更新了 SKILL.md另一个位置会变成旧版本下次排查问题就会出现“明明改了却没用”的困惑。所以如果决定迁到全局就要彻底从项目里清除它不要留双份。3.4 用软链接替代复制实现单点维护如果你希望技能先全局生效但还要保留在项目的维护入口推荐用软链接的方式来做单点维护。先在全局目录放一份源技能文件再在项目目录做一个软链接指向它。ln -s ~/.claude/skills/xxx ./.claude/skills/xxx这样做的好处是只维护全局路径那一份项目里的链接永远指向同一份文件。对于跨多个项目复用同一技能、且每个项目都希望有本地引用入口的场景这个方案非常顺手。缺点也很实际软链接放进版本库后团队其他人拉下来时链接可能无效因为你机器上的绝对路径在别人那里不一定存在。个人使用很香需要团队共享时还是得回归复制/手动装配的方案。3.5 从项目级升级为全局的判断标准什么时候该把一个项目级技能切到全局我的判断标准很简单当它在一个项目里已经验证稳定并且它在另一个不相关的项目里同样适用时就可以升级为全局了。代码风格类技能通常不太适合全局因为每个项目的风格约定差异很大而通用的开发流程类技能比如写规范的提交信息、按结构生成变更日志、做后台接口的冒烟测试这些跨项目体验几乎一致就非常适合全局。还有一个反向经验如果一个技能从全局切到某项目后反而表现变差比如它要求检查的流程对当前项目不适用不要急着改技能本身先在当前项目里配置局部覆盖或者直接移除保持全局版本不变是最好的处理方式。4. 实操案例做一个跨项目可用的代码审查技能有了全局和项目级切换的基础接下来用一个实际案例把整个流程串起来。我以代码审查 Skill 为例演示从零到全局部署的完整过程这个类型也比较有普适性不管你做前端、后端还是脚本都能直接套思路。4.1 设计 SKILL.md 的触发描述h2 和大多数技能的失效问题都出在触发条件写得不够精确。给这个代码审查技能写描述的时候我是这样处理的--- name: code-review-lite description: 当用户需要审查代码变更、评估Pull Request中修改的逻辑正确性、检查边界条件和资源释放问题或者要求逐行点评代码时使用。用于需要结构化审查意见的场景不用于单纯解释代码。 ---重点在后半句“不用于单纯解释代码”。这等于给模型一个负向拦截避免你把代码贴进来问“这段怎么运行”的时候它反而启动审查流程输出一堆跟提问无关的意见。4.2 SKILL.md 正文的核心流程正文我倾向用编号步骤来写让模型限定在一个固定的执行序列里# 代码审查技能 你正在执行一次结构化代码审查。无论变更规模多大始终按以下顺序执行 1. 通读变更涉及的函数或文件标出与本次改动直接相关的核心逻辑 2. 逐一检查边界条件空值、超长输入、并发冲突、异常分支 3. 检查资源释放打开的文件、临时目录、动态创建的连接是否都能正常回收 4. 检查错误处理抛出的异常是否被合适的地方捕获失败路径是否可观察 5. 按严重程度分类输出阻断性问题、建议改进、可选优化 6. 输出以列表形式组织每条意见对应到函数名和行号不写泛泛而谈的评语 禁止 - 只写代码写得不错这类无信息量的评价 - 在没有理解完整改动意图时提修改建议 - 把代码风格调整纳入阻断性问题用这个步骤跑下来模型输出的审查意见稳定度高了很多。以前让它审查一段代码它总容易直接开始改代码给出几个优化建议加了步骤约束之后它会先做逻辑审查再给意见关注的维度明显更完整。4.3 在项目里试用和迭代这个 Skill 我先在某一个内部项目里以项目级方式使用。前几次试下来有两个问题一是模型把“检查资源释放”理解得过于宽泛连普通数组遍历都开始提醒释放二是有时候输出还是偏概括。针对第一个问题我在正文里加了“资源释放仅限主动申请资源的场景例如文件句柄、网络连接、锁对象”模型的理解立刻收敛。针对第二个问题我把输出的强制格式改成“意见 位置 问题 影响 建议”配合一个示例效果也明显改善了。这类调试在项目级做非常划算因为影响面只有一个项目内容怎么改都不用担心污染其他场景。4.4 升级为全局技能技能稳定之后我把它注册为全局claude config add -g skills ~/.claude/skills/code-review-lite这里有一个交互细节我最早没搞清楚把技能路径注册到全局后并不是当前所有旧会话立即生效新建会话才会正确识别。如果你在一个会话中途想测试某个改动是否已感知直接开一个新会话最省事。我之后抽查了几个不同类型的仓库发现这个技能在脚本项目和前端项目中表现基本一致在个别框架项目里审查意见差异也主要来自项目上下文而不是技能规则本身。这让我确定它适合留在全局。4.5 从全局撤回项目级的反向流程全局技能偶尔也会造成过度干预。我遇到过另一个技能它包含的流程在某些项目里会改变模型响应结构导致局部场景反而不好用。遇到这种情况不需要删掉全局技能更合理的是在当前项目的配置里禁用或覆盖它。操作和注册对等把项目级配置指向空或换成项目专属版本即可。这种“全局默认、项目覆盖”的思路才是实践中最灵活的搭配方式。5. 常见问题与排查技巧5.1 技能没生效怎么排查技能配置好后完全没有被触发这是出现频率最高的问题。先别怀疑模型按照下面的顺序排查确认目录结构符合规范SKILL.md 直接放在技能目录下而不是嵌套在子目录里确认 frontmatter 里的 name 和 description 格式正确没有多余的空行或字段在新会话中测试避免旧会话没有加载用 config get skills 确认技能路径确实在加载列表中检查是否出现同名覆盖项目级有一个同名旧技能压住了全局的新技能这五步走完大部分“不生效”的情况都能找到原因。我碰到最隐蔽的一次是路径里多了一层目录用的还是复制快捷方式导致的混乱这类情况靠第一条检查就能抓住。5.2 描述写得宽泛导致误触发误触发比不触发更让人头疼。有一次我给一个文档生成类技能写描述时写了一句“帮用户写东西时使用”结果模型把写提交信息、写邮件都判定为匹配场景输出一套完整文档模板完全牛头不对马嘴。修正方式就是让描述可验证。不要写“需要帮助时使用”而要写“当用户明确要求生成规范的技术设计文档、接口说明、或需要结构化 Markdown 输出时使用”。另外在描述里补上“不适用于日常对话、××类型任务”能有效缩小触发范围。5.3 全局多个技能之间互相干扰技能越装越多一个会话里同时匹配多个技能的情况就会变多。我的处理原则是唯一职责一个好技能只干一件事不要把多个流程塞进一个 SKILL.md。如果已经出现两个技能职责重叠比如一个管“生成测试用例”另一个管“补充测试边界”把它们的触发描述做严格区分或者直接把边界描述写在各自的正文开头。还有个小技巧是在 description 中使用动词短语而非名词短语比如“当需要生成单元测试时使用”比“单元测试工具”更容易被准确匹配。优先保证它们在互不重叠的场景中才被触发不要设置那种听起来像总开关的宽泛技能。5.4 隐私与安全注意放到全局的技能里如果包含私密信息比如内部系统的路径或鉴权方式一定要谨慎。全局技能的加载范围覆盖所有项目和会话这个范围看起来方便泄露面也有多大。更合理的方式是把这些内容放在项目级必要时在项目级做注册或调用避免把内部细节带进无关项目里。5.5 多机器环境的同步建议如果你有多台电脑全局技能同步是一个值得规划的问题。我的做法是把整个 .claude/skills 目录纳入一份个人配置仓库换机器时直接拉下来放到用户主目录下即可。这一步做完以后新机器只需要跑一遍配置命令就能恢复所有技能。这里再补充一句工具链的版本差异也可能影响技能加载不同版本的解析规则可能存在细小差异换了机器后先开一个新会话做冒烟测试再正常开始工作可以避免在关键时刻发现技能没装上。6. 关于技能目录设计的几条实操心得技能放哪、怎么放、放多少实践后我有几条比较明确的体会。首先技能数量宜精不宜多。那些真正能提升每次会话质量的是我在多次项目里反复使用、逐步沉淀下来的少数几个。装了一堆技能但大部分时间段用不到相当于给模型背上额外的描述信息负担反而会带来噪声。项目级的技能适合和服务场景强绑定。比如某个技能依赖特定项目的目录结构、命名规范、接口约定这样的技能放到项目级里团队成员共享时才不会产生冲突。全局技能适合保存方法论层面的东西比如代码审查、提交信息规范、文档生成、命令行工具的使用约定。它们不依赖具体项目上下文抽象程度高跨项目体验一致。一个项目内的技能发现和排查我还会微调目录结构按功能模块组织子目录把相关脚本和模板和 SKILL.md 放在同一个目录下确保技能目录本身就是完整的、可独立搬运的。否则即使全局目录看到技能名称运行起来依然会缺依赖。最后持续优化也很重要。技能不是写完就固定的随着项目类型变化同一个技能的规则随时可能需要调整。定期整理负担很重容易越积越乱。我自己的习惯是每次使用时如果觉得输出里有一段结构明显的可以改进就会顺手把地方标记下来利用零散时间在项目级里做一次小版本更新确认无误后再同步到全局版本。这套稳定的流程跑下来技能库会一直保持可用状态不会慢慢变陈腐。把一个技能从项目级切到全局真正的关键并不在于那一条命令怎么写而在于你对“它属于谁”这个问题的判断。很多人的弯路是因为项目级和全局之间的边界没想清楚装了用不上删了又怕哪天需要。把技能按“项目专用”和“跨项目通用”分类再配合目录和配置双向管理Claude Code 的体验会有肉眼可见的改善。如果你正处在“项目里已经验证了一版 Skill、下个阶段要搬到全局”的节点上希望这篇能给你一份不算曲折的路线图。