尧图网站建设 
如果你已经用过几天 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 --prettyformat:%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 的价值不在多而在于边界清晰什么场景用项目级的什么场景交给全局兜底心里有数整个工作流才真正顺。 Claude Code Skills 指南：从项目级安装到全局复用
如果你已经用过几天 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 --prettyformat:%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 的价值不在多而在于边界清晰什么场景用项目级的什么场景交给全局兜底心里有数整个工作流才真正顺。