1. Skills 装的是什么先搞懂 SKILL.md 机制1.1 Skills 不是插件是一份“说明书 工具包”先说个我自己的经历。上个月我接手一个老项目代码里全是没有注释的 React 组件页面状态管理乱成一锅粥。我本来想手写一份代码审查规范一条条贴给 Claude Code后来发现直接把规范写成一个 Skill让它自己读、自己按规范审效果完全不一样。Claude Code 的 Skills 机制说穿了就是给模型额外准备一批“专用工作手册”。每个 Skill 本质是一个文件夹里面放着一个核心的SKILL.md文件以及这个技能可能用到的脚本、模板、参考文档。模型在对话过程中会根据你的任务描述自动判断要不要调用某个 Skill一旦调用就会读取这个SKILL.md然后按照里面写的步骤、规则、示例来执行任务。它不是传统意义上的“插件”不需要改 Claude Code 本身的内部逻辑也不需要写复杂的 API 接口。它更像是给模型一份“说明书”让模型知道“在这种场景下你应该按这样的流程做”。比如你写了一个“前端代码审查 Skill”那SKILL.md里会写明审查时先看组件拆分再看状态管理最后检查样式和可访问性每一项列出检查点和常见反模式。模型读完这份说明书再用自己已有的编程能力去执行相当于一个资深工程师拿着 checklist 在帮你做 review。我见过很多新手用户一上来就问“Skills 要不要写代码”答案是大部分情况下只要会写 Markdown 就行。复杂一点的 Skill 会配合scripts/目录里的 Python 或 Node 脚本完成特定操作比如读取配置文件、扫描文件依赖、生成测试用例但脚本只是辅助工具真正的“灵魂”是那份结构化说明书。1.2 一个 Skill 的标准目录结构少一层或多一层都识别不了Docs 的规范其实不复杂目录结构是固定的skill-name/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── generate_report.js ├── assets/ │ ├── prompt_templates.md │ └── examples.json └── references/ └── coding_standards.md其中SKILL.md是唯一必须存在的文件它顶部有一段 YAML frontmatter大概长这样--- name: frontend-review description: 用于对 React 项目做代码审查检查组件拆分、状态管理、样式规范与可访问性问题。 ---name是 Skill 的唯一标识description尤其重要模型就是靠这个描述来判断“现在这个任务该不该用这个 Skill”。描述写得越具体触发就越准确。如果你只写“用于代码审查”模型可能在三四种场景下都犹豫要不要调用如果你写“用于 React 项目的前端代码审查重点检查……” 那模型在遇到相关任务时基本会第一时间加载。SKILL.md正文部分是实际的指令通常包括适用场景、执行步骤、必须遵守的规则、输入输出格式、示例。为了让模型稳定复现步骤要写得像操作手册而不是散文。下面是一段实际可用的SKILL.md简化示例--- name: commit-message-helper description: 根据 git diff 生成符合 Conventional Commits 规范的提交信息 --- # Commit Message Helper ## 适用场景 当用户要求生成 git commit message、改写提交信息、批量处理多个提交时使用。 ## 执行步骤 1. 运行 git diff --cached 获取暂存区改动。 2. 若无暂存内容提示用户先执行 git add。 3. 根据改动类型判断 typefeat / fix / docs / style / refactor / perf / test / build / chore。 4. 生成不超过 50 字的标题行可附加 scope。 ## 规则 - 标题行必须小写开头禁止句号结尾。 - 正文按“为什么改 / 怎么改 / 影响范围”三段组织。你可能会问这些东西不写进 Skill直接把文字贴在对话里不也一样吗不一样。Skill 的优势在于它是“可复用、可沉淀、可共享”的文件资产。你把这段逻辑写成SKILL.md放进对应目录下次在任何一个项目里只要提到“帮我提交一下代码”模型就会自动加载这份规则不需要你重新长篇大论教一遍。这才是它真正的价值。2. 项目级与全局它们到底有什么区别2.1 三种存放位置作用范围完全不同Claude Code 的 Skills 存放位置并不只是一个按作用范围可以分为项目级、用户级通常叫全局以及组织级。实际用下来绝大多数人只需要搞清楚前两个。项目级的位置是项目目录下的your-project/ ├── .claude/ │ └── skills/ │ ├── frontend-review/ │ │ └── SKILL.md │ └── api-doc-generator/ │ └── SKILL.md全局的位置则是在用户主目录下的.claude目录~/.claude/ └── skills/ ├── commit-message-helper/ │ └── SKILL.md ├── frontend-review/ │ └── SKILL.md └── weekly-report/ └── SKILL.md注意这里的“全局”指的是对当前用户所有项目生效而不是对操作系统所有用户生效。理解了这个层级关系你就明白为什么很多人会纠结“这个 Skill 到底该放项目级还是全局”。我把两类目录的区别总结成一张表你一眼就能看明白对比项项目级技能全局技能存放位置项目目录.claude/skills/用户目录~/.claude/skills/生效范围仅当前项目当前用户的所有项目随仓库分发会进入 Git团队共享不进入仓库仅自己可见适用场景项目特有规范、领域规则通用工作流、个人效率工具优点可版本控制、团队统一一次安装到处用、管理集中缺点每个项目都要单独装容易堆积垃圾技能一个常见误区是以为全局技能会自动出现在项目代码里其实不会。Claude Code 启动时会在启动目录找到项目级 skills 目录同时加载用户全局目录中的技能两边互不冲突。2.2 怎么选才不后悔别把每个 Skill 都塞进全局我在刚接触 Skills 时犯过一个很典型的错误看到一个不错的 Skill 就复制到全局导致~/.claude/skills/里存了几十个技能真正常用的却不到五个。模型每次开新对话都要扫描一遍这些说明文档虽然不至于拖慢速度但触发准确率反而降低了——有些描述模糊的技能会“抢戏”在明显不适合的场景下被错误加载。我的建议是遵循“三放三不放”原则。放项目级的场景团队内部独有的代码规范或接口约定比如“调用支付网关必须经过统一封装”。项目专属的文档模板、目录结构要求。该项目的技术栈特有检查项比如只在这个项目里用的 GraphQL 实践约定。放全局的场景通用的 git 操作助手比如“生成 Conventional Commits 提交信息”。跨项目复用度高的代码审查、调试排错、性能分析技能。个人工作效率工具比如“整理周报”“生成每日站会纪要”“批量重命名文件”。不放全局的场景和特定项目绑定的技术规则放全局反而会让其他项目误触发。包含敏感信息的技能比如写死了某个服务的 token一旦全局生效所有项目只要满足触发条件就可能读到内容。还没验证过可靠性的实验性技能先放项目级跑几次再说。这个取舍没有绝对正确核心标准就一条你会不会在超过两个项目里用到它。如果不会就别放全局。3. 安装从找到 Skill 到让它跑起来3.1 去哪里找现成的 Skills官方市场与社区清单很多人问“Skills 到底去哪下载”答案并不只有 GitHub。目前比较靠谱的途径有这么几条。第一是 GitHub 直接搜索。搜索关键词很有讲究不要只搜 “Claude Skills”那样出来的结果太杂。我常用的搜索词是awesome claude skills、claude code skills、agent skills再加具体领域词比如claude skill react、claude skill backend。GitHub 上有不少整理好的 Awesome 列表比如一些仓库专门汇总社区里高质量的 Skill按“前端、后端、运维、写作、数据分析”分类整理看到合适的直接复制目录内容到本地。第二是官方商城和第三方社区平台。随着 Skills 生态成熟已经有专门发布和下载 Skills 的站点可以在网页上浏览技能介绍、预览SKILL.md内容再一键复制安装。不同平台的规则略有差别但本质上拿到手都还是一堆文件夹。第三是直接看别人的配置仓库。很多开发者会把自己整套~/.claude/skills/目录开源出来你浏览他们的配置仓库比看单个 Skill 收益更高能看到真实使用场景下的目录命名、层级组织方式、以及哪些技能会搭配使用。比如有人会同时装“代码审查”“提交信息生成”“CHANGELOG 自动维护”三个技能组合使用这种搭配思路非常值得借鉴。3.2 安装实操项目级和全局各自的命令安装的本质就是“把一个 Skill 文件夹放到正确的位置”。很多网传的 “claude skills add” 命令在不同版本里并不通用我建议你直接掌握文件操作这样在任何环境都不会被卡住。先看项目级安装。假设你下载了一个api-doc-generator技能目录名字叫api-doc-generator/里面是完整的SKILL.md和辅助脚本。在项目根目录执行# 确保项目级技能目录存在 mkdir -p .claude/skills # 把技能复制到项目级目录 cp -R api-doc-generator .claude/skills/ # 查看最终结构 find .claude/skills -maxdepth 2 -type f这样这个 Skill 就只对当前项目生效。如果你的项目还没有.claude目录上面的命令会自动创建。再看全局安装。全局目录是~/.claude/skills/操作基本相同# 确保全局技能目录存在 mkdir -p ~/.claude/skills # 把技能复制到全局目录 cp -R api-doc-generator ~/.claude/skills/ # Windows 用户注意主目录路径通常是 C:\Users\你的用户名\.claude\skills # macOS / Linux 用户注意~ 已经代表当前用户主目录如果你使用的是 git 克隆方式可以直接把仓库克隆到对应目录再删掉仓库里多余的说明文件和.git目录git clone https://github.com/example/api-doc-generator.git ~/.claude/skills/api-doc-generator # 删除 git 元数据避免多余干扰 rm -rf ~/.claude/skills/api-doc-generator/.git有些技能包是压缩包格式先解压再放进目录道理一样。安装完后强烈建议你回头看一眼SKILL.md的 frontmatter 里name字段确认它和文件夹名一致。不一致的话可能引发一些玄学问题虽然大部分场景下模型能容忍但既然规范摆在那里保持一致总归更稳。如果用的是 VS Code 的 Claude Code 扩展你也可以在扩展面板里找设置入口配置里通常有 skills 目录路径的自定义项不过默认情况下依然读的是项目级和用户级这两个标准位置。3.3 安装完怎么确认加载成功很多朋友装完 Skill 后心里没底“它到底加载了没有”我给你几个验证思路。最简单的方法是直接在 Claude Code 对话里输入你当前加载了哪些 skills请列出所有可用的 skill 名称和描述。如果模型能清清楚楚列出一串技能名说明管理机制正常。如果某个新装的技能没出现在列表里那就得排查目录结构了。第二种方法是直接触发式提问。比如你想验证frontend-review有没有生效就直接针对一个文件问“用 frontend-review 技能帮我审查这个组件的代码”。模型如果正确加载了技能它会按照 SKILL.md 里的步骤和检查项逐条执行而不是自由发挥。你可以从它的回答结构里看出来——遵循了技能模板的输出格式就说明加载成功。第三种方法是看调试日志。在 Claude Code 中开启详细日志模式启动时会打印加载了多少个 skills、每个技能来自哪个路径。不同版本日志开关不一样通常可以在配置里打开 debug。这个方法适合排查疑难问题日常验证用前两种就够了。装完第一个 Skill 后我建议你立刻做一件事在项目里新建一个测试文件故意制造一个能触发该技能的场景完整跑一遍。这一步能帮你确认“技能描述触发”这条链路是通的而不是等到真实项目里才发现技能根本没被调用。4. 从项目级切到全局迁移的正确姿势4.1 为什么要迁移几个典型场景迁移需求通常在两种情况下出现。第一种是技能在项目 A 里验证效果好你想在项目 B、C、D 里复用。比如我在一个 React 项目里写了state-management-review技能专门检查 Redux 状态拆分是否合理后来发现同样的问题在另一个 Vue 项目里也存在只是检查点要微调。这时候与其在三个项目里各复制一份不如把通用部分提炼出来放到全局再分别编写每个项目的局部规则。第二种是团队项目和个人配置混在一起你想把它们拆开。项目级技能会进入 Git 仓库别人克隆项目就会同步拿到。如果你的项目级目录里混着纯个人工作习惯的技能比如“总结今天工作并生成日报”队友会很困惑为什么提交代码的项目里会有这种东西。拆开之后项目级只留团队共享规范个人工具统一放全局双方互不打扰。还有一种比较隐蔽的场景你在多个项目里维护同一套技能的多份副本每次修改都要一个个同步漏改一个就出现两个项目行为不一致。迁移到全局后单一副本就成为唯一来源修改一次所有项目生效维护成本直线下降。4.2 迁移实操复制、检查、测试三件套迁移不是简单地把文件夹拖过去我总结了一套“复制、检查、测试”三件套流程。第一步复制。把项目级技能目录里的技能拷贝到全局目录# 假设当前在项目根目录 mkdir -p ~/.claude/skills # 复制单个技能 cp -R .claude/skills/state-management-review ~/.claude/skills/ # 前端代码审查、提交信息助手这类通用技能可以批量复制 cp -R .claude/skills/frontend-review ~/.claude/skills/ cp -R .claude/skills/commit-message-helper ~/.claude/skills/注意这里用的是cp而不是mv原因后面细说。第二步检查。复制完成后检查三件事。一是目录层级打开~/.claude/skills/确认每个技能文件夹下确实有SKILL.md而不是嵌套了一层同名目录错误~/.claude/skills/frontend-review/frontend-review/SKILL.md 正确~/.claude/skills/frontend-review/SKILL.md二是检查 frontmatter 里的name是否和文件夹名一致。三是有没有引用项目里的相对路径比如某个脚本写死了../config.json复制到全局后这个路径就失效了。第三步验证加载。启动一个新的 Claude Code 会话用上一节说的“列出所有技能”法确认它出现在全局技能列表中再到另一个无关项目里测试触发确保没有依赖原项目的特殊配置。如果技能内部使用了环境变量或外部命令记得确认这些依赖在当前环境同样存在。4.3 迁移后优先级问题项目级和全局重名了怎么办迁移过程中最容易踩的坑就是重名冲突。比如你原来在项目里放了commit-helper现在又把全局同名技能也放上了两边都叫commit-helper那 Claude Code 会怎么办根据我这段时间的实际观察不同版本对冲突的处理策略并不完全一致但总原则是“更具体的范围优先”。也就是说项目级技能通常优先于全局技能因为项目目录是模型启动时的当前上下文更贴近当前任务环境。不过每个版本更新都可能调整行为所以最稳妥的做法还是主动避免重名。我的建议是迁移时先查看项目级目录里有没有同名技能有的话先决定保留哪一份。如果你想保留全局版本就把项目级版本重命名或者删掉如果你想保留项目级版本就不要把它复制到全局否则后续修改时容易搞混“我改的到底是谁”。这里我再补一句个人体会我一般会给全局技能起名时加个人前缀比如my-commit-helper这样即使和团队的项目级技能重名也不会出现行为覆盖的混乱。4.4 为什么不用 mv团队协作视角下的考量我在教别人的时候发现一个非常普遍的操作update 命令用mv .claude/skills/xxx ~/.claude/skills/。这个操作放在个人项目里没问题但在团队项目里会埋雷。项目级技能通常是要提交到 Git 仓库里的团队成员克隆项目后git status会显示你删掉了这个技能文件下一次提交时其他人可能不小心把这个删除操作提交上去导致整个团队都失去了这个技能。即使是你自己的项目如果这个技能还在被 CI 流程引用直接移动也会让流程中断。所以迁移的标准动作一定是“复制到全局再决定项目级去留”。你可以先让全局和项目级共存跑几天确认全局版本工作正常再把项目级版本移除。移除方式建议用git rm -r .claude/skills/xxx而不是直接rm这样版本历史清晰可控后面想找回也更方便。5. 常见问题与排查实录5.1 Skill 没有被识别的最常见原因我踩过的坑里最经典的就是目录层级不对。有一次我解压一个技能包发现里面套了一层同名目录直接把它放到~/.claude/skills/下后Claude 完全没有反应。原因就是SKILL.md不在预期的位置。你下载到带嵌套目录的压缩包时先看看目录结构再决定是整体放进去还是剥掉一层外壳放进去。第二高频的问题是 description 写得不够明确。模型的触发逻辑就是拿你的问题描述和技能的description做匹配如果你写的是“用于前端开发”那模型可能久久不触发如果你写成“用于审查 React 函数组件的 props 类型、状态提升和性能优化问题在用户提出代码审查请求时使用”触发的概率会明显提升。我把这看作“给模型的路标”——路标越具体模型越容易找过来。第三类是权限问题。如果某个 Skill 依赖脚本文件而脚本没有执行权限模型调用时就会报错。在 Linux/macOS 下记得给scripts/下的文件加执行权限chmod x ~/.claude/skills/xxx/scripts/*.sh chmod x ~/.claude/skills/xxx/scripts/*.pyWindows 用户则需要确认脚本能被当前环境直接调用比如 Python 是否在 PATH 中。第四类是缓存问题。Claude Code 会缓存技能信息有时候新装的内容不会立即出现在当前会话中。遇到这种情况重启一个新的对话即可大多数情况都能解决。5.2 使用姿势避坑别让技能变成“一次性说明书”很多人以为把 Skill 放进去就完事了其实使用方式也有讲究。先说触发方式。你可以直接说“用某个技能做某事”这是强制指定也可以不指定让模型根据上下文自动选用。自动触发依赖 description 写得够不够具体如果你的描述像“会帮我做一些事情”这种废话那基本不会被自动选中。我建议在项目初期多尝试强制指定观察技能是否按预期执行稳定后再试自动触发这样能更快迭代出高质量的技巧。第二个坑是“把所有步骤都写死在 SKILL.md 里”。有些人为了让模型严格照做把每一个细小动作都写进去结果反而限制了模型的判断力。Skills 的正确姿态是“给定目标、规则、边界和检查点”而不是“逐字逐句指导怎么敲键盘”。比如写“审查时关注组件是否超过 200 行”这叫作可执行的规则写“第一行应该输出一个标题第二行输出一个列表”这叫作过度设计。前者提高模型表现后者只会让输出变得机械。第三个坑涉及安全。SKILL.md文件里不要写任何密钥、token、密码。因为你可能在某个项目里用了项目级技能后来把它复制到全局那这份敏感信息就随着你的全局目录扩散了。更危险的是如果你从网上下载别人共享的技能其中可能包含恶意脚本安装前一定要打开SKILL.md和scripts/里的文件快速看一遍确认没有访问第三方接口、上传数据、执行可疑命令的行为。我见过有人分享“自动挖洞”之类的技能这类技能如果加一点私货你根本察觉不到。5.3 快速排查表一张表定位常见问题结合我实际操作中踩过的坑整理成一张排查表你按这个顺序查基本能解决 90% 的问题症状可能原因解决动作新技能完全不被提到目录层级错误检查SKILL.md是否在预期路径技能被加载但行为异常脚本路径或依赖缺失查看脚本引用的相对路径、环境命令技能列表里能看到但从不触发description 不具体重写 description写明适用场景与触发词会话中用了技能但结果不理想SKILL.md 指令太模糊补充检查点、规则、输出格式示例迁移到全局后行为不一样依赖项目配置或环境变量检查脚本中的硬编码路径与变量技能目录很多但响应变慢全局技能堆得太多定期清理删除不常用技能5.4 为什么“必装 Skills”这么火生态现状与我的观察最近社区里关于“必装 Skills”的讨论非常多一方面是因为 Claude Code 的 Skills 生态已经积累了一批经过验证的高质量技能另一方面也是因为很多人开始意识到Skills 机制的价值不在于“装一个工具”而在于“把团队的最佳实践沉淀成可复用的标准流程”。我注意到现在讨论的方向已经越来越细了。有人专门研究如何为 Claude Code 接入不同的第三方模型服务比如通过统一配置工具管理不同模型的调用方式让同一个 Skills 资产在不同模型下都能跑起来。也有人在做类似“技能市场”的聚合平台尝试把分散在 GitHub 各处的技能按类别、质量、下载量排序帮助用户更快找到想要的资产。这些方向都说明这个生态正在从“扔一个 SKILL.md 就完事”的阶段往“工程化管理、跨环境复用、质量控制”的方向走。以我自己的经验看现阶段最值得做的并不是追求装几十个技能而是挑三四个高频场景反复打磨。比如前端开发人员可以先装一个代码审查技能、一个提交信息生成技能、一个接口文档生成技能每个技能认真调一版让描述、步骤和规则都贴合自己的项目跑顺之后再逐步扩展。技能贵精不贵多一套用得顺手的工作流比一百个落灰的说明书有价值得多。最后再分享两个实用技巧第一个技巧给全局技能做“每周清理”。我每周末会花两分钟看一眼~/.claude/skills/把超过两周没用过的技能移到archive/目录而不是直接删除。这样既不污染正常加载又能保留后续想用时的可能性。时间一长留下来的都是经过真实项目验证的高频技能目录越来越薄但每个都能打。第二个技巧把description当成“搜索文案”来写。想象你的技能是一个页面模型是搜索引擎description就是它的 SEO 标题和摘要。好的描述要包含任务场景、具体对象、推荐时机、预期结果不要写空泛的形容词。我经常会迭代这个字段观察到某段时间技能总是没被触发第一反应不是改 SKILL.md 正文而是改 description。很多时候光改这一段触发率就能翻一倍。说到底Claude Code 的 Skills 就是一个“沉淀经验、复用流程”的机制项目级和全局的切换也只是选择资产作用范围的问题。关键在于想清楚这个技能服务谁、给谁用、用多久。把这些基础问题想明白了安装和迁移都只是顺手的事。