用 Claude Code 写代码有一阵子了坦白讲最让我觉得这个工具真的不一样的不是它改代码有多快也不是终端命令执行得有多顺而是 Skills 这套机制。简单说Skills 就是把一段精心组织过的专业知识、工作流或工具能力打包成 Claude Code 能随叫随到的模块。你写前端时它给你一套组件审查规范你写后端时它帮你按团队规范生成接口文档你甚至可以让它按你的习惯整理提交信息。这篇文章我会从 Skills 的安装讲起重点说清楚项目级和全局 Skills 的区别以及怎么从项目级平滑地切换到全局——这是很多人卡住的地方。Skills 适合谁如果你是 Claude Code 的重度用户或者你所在团队已经把 Claude Code 当作日常开发工具那这篇内容基本就是刚需。就算你只是刚接触 Claude Code搞明白 Skills 的安装逻辑也能少走很多弯路。全文没有太多空泛的概念全部是我实际动手验证过的操作路径。1. 先把 Skills 的机制彻底讲明白1.1 Skills 到底是什么从文件结构上看一个 Skill 就是一个目录目录里有一个 SKILL.md 文件以及若干辅助文件。这个 SKILL.md 是核心它用 Markdown 写成顶部有一段 YAML frontmatter里面包含 name、description 这类元信息正文则是完整的操作说明、步骤、代码模板、注意事项等。Claude Code 在启动时会扫描指定目录把每个包含 SKILL.md 的文件夹识别为一个可用的 Skill。当你的对话内容或当前任务与某个 Skill 的 description 匹配时模型就会自动加载这个 Skill 的内容作为上下文你也可以通过 skill-name 这样的方式显式调用。这里有个很关键的点加载 Skill 不等于执行脚本更准确地说是把 Skill 里的知识和规范喂给模型让它按照你的预期来完成后续任务。我举个具体例子。假设你在 .claude/skills/review-frontend/SKILL.md 里写了一套前端代码审查规范里面包括组件拆分原则、性能检查清单、可访问性注意事项。那么当你对 Claude 说帮我 review 一下这个页面组件时它就会自动读取这个 Skill按照你定义的规范来审查而不是用默认那套通用标准。这相当于把你自己和团队多年攒下的经验固化成了一个每次都能用的专家手册。这里还说一下 Skills 的辅助资产。SKILL.md 正文里可以直接引用同目录下的其他文件比如 checklist.md、模板文件、示例代码。当 Skill 被加载时Claude 会根据正文的引用按需读取这些文件。这个设计挺实用因为它意味着你不需要把所有内容堆进一个 SKILL.md 里可以把大段的示例代码、详细的模板拆成单独文件主文件保持精简按需展开。1.2 为什么 Skill 和 CLAUDE.md 不一样很多人会问我已经有 CLAUDE.md 了里面写了很多项目约定为什么还需要 Skills这两个东西定位其实不同。CLAUDE.md 是项目级记忆Claude Code 每次会话都会自动加载它适合放那些你希望无时无刻都被遵守的规则比如技术栈说明、目录结构、代码风格偏好。它的问题是不分场景、不分任务全部塞进上下文。如果项目大CLAUDE.md 写长了每次对话都会白白消耗上下文窗口而且大量信息可能和当前任务无关。Skills 则是按需加载的能力模块。平时不影响上下文只有在任务匹配时才被加载。Skill 的描述写得越好模型越能在合适的时机精准地拉起它。所以我的实践建议是把应该被记住的放 CLAUDE.md把需要时拿来用的做成 Skill。这两者搭配才能既省上下文又保证规范不丢。另外 Claude Code 还有 Commands斜杠命令那个适合快捷操作比如 /commit 这种固定流程。Skills 比 Commands 更重、更完整适合封装一整套工作流而不仅是触发一条命令。两者的边界偶尔会模糊但大方向是Commands 偏向执行某个动作Skills 偏向注入一段专业知识和工作方法。1.3 适用范围项目级、用户级和插件级Skills 存放的位置决定了它的适用范围这也是这篇文章的核心。项目级放在当前项目的 .claude/skills/ 目录下。只有在这个项目目录里启动 Claude Code 时才能用适合项目专属的规范和流程。一般会提交到 Git 仓库团队共享。用户级全局放在 ~/.claude/skills/ 目录下Windows 是 C:\Users\你的用户名.claude\skills。任何项目里启动 Claude Code 都能用适合个人通用的技能比如统一的 commit 规范、通用的代码审查清单。插件级由 Claude Code 插件市场安装一般会落在用户的插件安装目录下由插件统一管理。搞清楚这三层后面安装和切换就顺理成章了。很多人之所以在切换项目级到全局时感到迷惑根源就是没意识到这三层的作用域差异。先在心里画一张路径到作用域的对应图后面所有的操作都围绕这个图展开。2. 项目级 Skills最标准的装法2.1 目录结构和命名规则项目级 Skills 的安装目录是 .claude/skills/要从 Claude Code 的项目根目录算起。举个例子my-project/ ├── .claude/ │ └── skills/ │ ├── review-frontend/ │ │ ├── SKILL.md │ │ ├── checklist.md │ │ └── examples/ │ │ └── bad-component.tsx │ ├── write-api-doc/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── api-doc-template.md │ └── conventional-commit/ │ └── SKILL.md每个 Skill 文件夹名字最好用短横线命名法kebab-case比如 review-frontend、write-api-doc因为这个名字会成为 Skill 的标识太啰嗦或含空格都不方便。辅助文件不一定需要有但 SKILL.md 是底线缺了它整个文件夹都不会被识别。需要特别留意.claude 目录是 Claude Code 自定义配置的根目录除了 skills 还有 commands、settings.json 等。别把 Skills 文件夹放错位置最常见的问题就是把技能目录直接放到了 .claude/ 的根目录下或者放在了 src/ 里面结果模型根本扫不到。还有一个容易被忽略的细节在 Monorepo 或多模块项目里如果你在子目录启动 Claude Code它扫描的是启动目录下的 .claude。不同子目录各自维护一套 Skills 完全没问题但如果你希望整个仓库统一一套规范我更建议在仓库根目录启动并只维护根目录的 .claude/skills。2.2 SKILL.md 的 Frontmatter 到底怎么填SKILL.md 顶部是用三个短横线包裹的 YAML frontmatter这是 Skill 能否被正确识别和触发的关键。最核心的三个字段nameSkill 的唯一标识建议和文件夹名保持一致。比如 name: review-frontend。description最重要的字段。模型靠它来判断当前任务是不是该用这个技能。描述写得越具体、越包含触发场景关键词触发准确率越高。不要写用于代码审查这种空话要写当用户要求审查 React 组件、检查前端性能问题、评估组件拆分合理性时使用包含团队自定义的审查清单和规范。allowed-tools可选字段声明这个 Skill 运行时可用的工具白名单。如果 Skill 不需要调用工具可以不写如果写了就限定在这几个工具范围内超出会被拒。除了这三个还支持一些扩展字段比如 license、metadata 等但对绝大多数使用场景name 和 description 就够用了。正文部分没有固定模板但好的 SKILL.md 一般具备几个特征开头先用一两句话说清楚这个技能解决什么问题然后是分步骤的操作说明步骤要具体到可以照着执行关键部分给代码模板或配置示例最后写注意事项和常见坑。整篇文件不要太长我建议控制在 200 到 500 行之间。太短说明内容不够具体太长则会稀释重点加载时也更容易占用上下文。我补一个 frontmatter 的常见错误YAML 里冒号后面必须有空格键值对的缩进要一致否则解析直接失败。很多人粘贴模板时把 description 换行了但没缩进好Skill 就被静默忽略列表里怎么都看不到。排查的时候先盯这个。2.3 手动安装项目级 Skill 的操作步骤演示一下最标准的安装流程你照着做一遍后面所有安装就都通了。第一步创建目录。在项目根目录下执行mkdir -p .claude/skills/review-frontend第二步创建 SKILL.md 文件。可以用编辑器也可以直接用命令行cat .claude/skills/review-frontend/SKILL.md EOF --- name: review-frontend description: 当用户要求审查 React 前端组件、检查性能与可访问性问题时使用。包含团队自定义审查清单。 --- # 前端代码审查 ## 审查原则 ... ## 审查步骤 1. ... 2. ... ## 注意事项 ... EOF第三步把辅助资产放进去。比如 checklist.md、示例代码文件等都放在 Skill 文件夹内。SKILL.md 正文里可以引用这些文件的相对路径模型在需要时会去读取。第四步验证。回到项目根目录启动 Claude Code输入 /skills 或者类似的功能命令也可以直接问你现在有哪些 skills。看到自己的 Skill 出现在列表里就说明安装成功了。这里要特别强调一个实际操作中的点有些场景下安装完 Skill 后当前会话不一定立即生效最保险的做法是重启一下 Claude Code 会话。我遇到过很多次明明目录和文件都没问题但列表里就是不显示重启会话后一切正常。这多半是会话启动时的扫描缓存导致的不是你的文件有问题。2.4 项目级 Skills 的团队协作建议项目级 Skills 天然适合团队共享但前提是纳入版本管理。我建议把 .claude/ 目录至少是 skills 子目录纳入 Git 追踪这样每个成员 clone 完就能用同一套技能不用各自手动装。不过团队场景下有两个注意点。一是别把个人偏好的 Skill 放进项目级比如某成员自己的 commit 信息习惯这种应该放全局二是项目级 Skills 的修改要走 Code Review因为它会影响所有人的 Claude Code 行为。我见过团队里有人往项目级 Skill 里写了一句所有代码都用 TypeScript 重写结果全组人的 Claude Code 都开始按这个要求工作场面一度很混乱。Skill 的内容一旦进入共享目录就是团队资产不是个人实验田。3. 从项目级切到全局操作与决策逻辑3.1 为什么要切成全局项目级 Skills 最大的优势是团队共享、随仓库走。但如果你发现自己某个 Skill 在好几个项目里都能用——比如常规代码审查、提交信息规范、README 生成——那放在项目级就太浪费了。每个项目都要维护一份副本改一处要同步好几处很容易版本漂移。这时候就该把它提到全局目录让所有项目共用同一份。另外还有一种常见场景你在公司项目里写了一个不错的 Skill想带到个人项目里用。由于项目级 Skill 在仓库里直接复制过去也行但复制意味着两份副本后续更新要手动同步。切成全局只需要一份改动一处处处生效。我现在的习惯是一个 Skill 只要是与具体业务无关的通用经验一律全局化只有那种绑定了特定项目目录结构、特定框架约定的技能才留在项目级。3.2 三种切换方式实操方式一移动文件。# 从项目级移到全局 mkdir -p ~/.claude/skills mv .claude/skills/review-frontend ~/.claude/skills/这是最直觉的方式适合不需要保留项目副本的场景。注意先确认目标目录存在否则 mv 的时候可能移动出嵌套关系后面反而乱。另外移动后记得在项目里把原来的空目录清理掉避免别人看着 confusion。方式二复制并启用。cp -r .claude/skills/review-frontend ~/.claude/skills/适合既想在当前项目保留一份又想全局能用的场景。但如果项目里那份后面还要改记得定期同步否则两边内容会不一致。我自己的经验是这种方式只适合短期过渡不适合长期维护因为人一定会忘记同步。方式三符号链接。ln -s $(pwd)/.claude/skills/review-frontend ~/.claude/skills/review-frontend做符号链接的话全局目录里的 Skill 其实是指向项目目录里那一份。这样你只需要维护项目里那一份原始文件全局自动跟着更新。缺点是对团队其他人不友好——他们 clone 仓库后没有你的全局链接目录所以这种方式只适合个人使用不适合团队共享。而且要记得如果项目目录被移动或删除全局链接就失效了。我个人推荐方式一作为默认方案确定这个 Skill 是通用的就果断全局化如果只是项目专属就留在项目级。不要搞出半全局半项目的状态维护起来最痛苦。3.3 切到全局后要注意什么切到全局后有几个坑我逐一提醒。第一路径切换后要重启会话。全局 Skills 的扫描同样是启动时完成的移动完成后建议重启 Claude Code 或至少重新加载一次否则当前会话可能仍旧按旧路径去找。第二团队项目里的 .claude/skills 如果被 Git 管理移动文件后记得把变更提交上去避免团队其他人还对着旧路径使用。最好同步更新一下项目文档写明哪些通用 Skill 已经全局化、不再随仓库分发。第三全局目录的 Skills 对所有项目生效所以一旦某个 Skill 写得有问题影响面会比项目级大得多。我在全局放过一个写得不严谨的接口文档生成技能结果那段时间所有项目的文档风格都被带偏了。所以全局 Skills 更值得花时间打磨上线前先在隔离环境验证几次。第四如果项目级和全局存在同名 Skill以项目级为准。Claude Code 的解析优先级是项目级优先于用户级。这点后面还会细说但它直接影响你对切换这件事的判断切到全局后如果原项目里还留着旧的同名副本你用的时候很可能会发现全局那份根本没生效。3.4 怎么查看当前生效的 Skills想确认当前有哪些项目级和全局 Skills直接问模型是最快的你当前加载了哪些 Skills分别来自项目级目录还是全局目录它会把你加载到的技能列表和来源告诉你。也可以手动查看文件系统项目级看 .claude/skills全局看 ~/.claude/skills。两边文件一对比哪些是通用的、哪些是唯一的一目了然。如果两边有同名目录再用 diff 对比一下内容差异排查为什么我改了全局没反应这类问题时这一步非常关键。4. 更省事的安装来源与批量管理4.1 从插件市场安装 Skills手动创建 Skill 适合自己写技能但如果你想直接用别人做好的高质量技能从插件市场或第三方仓库安装就省事得多。Claude Code 的插件市场本质上是一堆插件包的集合插件包里可以包含 Skills、Commands、Agent 配置等。通过 /plugin 相关的命令可以挂载市场地址然后安装对应插件其中的 Skills 会被自动识别并部署。不过我要提醒的是插件安装后一般落在用户插件目录下属于用户级范畴。这意味着一旦安装它会对你的所有项目生效。有些插件会一次带进来好几个 Skill如果你只想要其中某一个装完最好检查一下不需要的 Skill 要把对应的文件夹移走避免不必要的上下文负担。4.2 从 GitHub 仓库安装 Skill现在很多开源 Skill 以 GitHub 仓库形式分发仓库里就是一个或几个 Skill 文件夹。安装方式很简单# 全局安装 git clone https://github.com/example/awesome-claude-skills ~/.claude/skills-tmp mv ~/.claude/skills-tmp/review-frontend ~/.claude/skills/ rm -rf ~/.claude/skills-tmp之所以用临时目录再移动是因为很多仓库的根目录并不是直接放 SKILL.md而是套了好几层目录结构。直接把整个仓库 clone 进 skills 目录可能会出现一个文件夹套着一个文件夹的嵌套情况Claude 扫描不到。移动到标准结构是最稳的。装第三方 Skill 前我一般会先看三样东西一是 SKILL.md 的 frontmatter 是否完整。name 和 description 是底线description 写得太模糊的触发率大概率不行。二是文件有没有附带可执行脚本。有些 Skill 依赖脚本文件做代码分析如果脚本是 Python 写的而你环境里没有相应依赖Skill 跑起来就会报错。装之前看一下依赖说明不匹配就谨慎使用。三是维护活跃度。GitHub 上长时间不更新的 Skill里面用的接口、命令可能已经跟新版本不兼容。我踩过这个坑一个老版本的前端审查 Skill 用的命令格式变了加载后一直报错排查半天才发现是 Skill 本身过时了。4.3 版本升级对 Skills 的影响Claude Code 迭代速度很快版本升级后 Skills 的解析规则、工具权限逻辑都可能有变化。我自己遇到过几个典型变化早期 Skills 只要放在目录里就能被扫到后来版本对 frontmatter 的字段校验更严格缺字段的 Skill 被静默忽略还有版本调整过 description 字段的匹配逻辑以前能自动触发的技能升级后需要优化描述才能稳定触发。所以建议是每次 Claude Code 升级后抽空跑一遍 skill 列表命令确认自己常用的 Skill 都还在、还能被识别。别等到要用的时候才发现技能已经失效了。尤其是在团队协作环境里一个人的版本升级影响不到别人但同一个仓库的 Skills 文件是共享的一旦新版本不兼容旧格式全员都会受影响这时候要尽快统一升级节奏。5. 常见问题与排查技巧实录5.1 Skill 装好了但列表里看不到这是遇到最多的问题。排查顺序如下第一目录对不对。项目级必须是 .claude/skills/[skill-name]/SKILL.md全局必须是 ~/.claude/skills/[skill-name]/SKILL.md。注意不要少了嵌套层级比如把 SKILL.md 直接放在 skills/ 下面是不行的每个 Skill 必须有一层自己的文件夹。第二frontmatter 对不对。SKILL.md 第一行必须是 ---最后一行也必须是 ---中间是 YAML 键值对。偶尔有人把 frontmatter 写成了注释格式或者冒号后面没有空格解析失败就会找不到。第三文件编码。尽量用 UTF-8 无 BOM有些编辑器默认保存成带 BOM 的格式可能导致 frontmatter 解析出问题。第四重启会话。我前面提过这是最常见的假故障目录文件都没问题只是会话缓存导致没扫到。重启就好。5.2 Skill 存在但从不自动触发这说明 description 写得不够好。模型判断是否加载 Skill 的依据就是 description 跟当前任务的语义匹配度。如果 description 写得太泛比如帮助优化代码那它几乎不会把具体任务和这个描述关联起来如果写得太窄比如只提到了 Vue那它永远不会在 React 项目里触发。我建议的 description 写法是包含触发场景、对象和任务类型三个要素。比如当用户要求审查 React 组件代码、定位性能瓶颈、检查可访问性合规性时使用。这样模型在多种相关场景下都有机会拉起它。实在不行你还可以显式要求用 review-frontend 技能来审查这段代码直接按名字点菜。不要怕 description 写得太长只要每句话都提供有效的匹配信号都比空泛的一行强。5.3 权限和工具受限问题Skill 在执行某些操作时可能报tool not allowed之类的错误。排查分两步一是看 Skill 的 frontmatter 里有没有 allowed-tools 声明如果声明了白名单而实际上需要调用里没列的工具就会受限二是看 Claude Code 本身的工具权限配置比如你在设置里禁用了某些工具Skill 也就没法用。这时要么调整 allowed-tools要么检查 settings.json 的权限配置。我遇到过一种特殊场景Skill 里写了一个 shell 命令但命令内部又调用了另一个未被授权的子命令。报错信息很让人困惑表面上是命令执行失败实际是权限链断在了中间环节。这时候要逐层拆开命令找到真正被拦截的那一步再决定是调整权限还是改写 Skill 的命令逻辑。5.4 同名冲突与优先级项目级和全局如果存在同名 Skillname 字段相同以项目级为准。这个设计其实合理项目级代表了这个项目的特定约定全局只是通用兜底。但如果你发现全局的某个技能莫名其妙不被使用先查一下项目级是不是有个同名的。另外装插件时也可能带来同名冲突插件里的 Skill name 如果和你的自定义 Skill 撞了要留意最终生效的是哪一个。我建议给 Skill 命名时加上团队或用途前缀减少撞名概率。比如 wf-review-frontend、wz-api-doc虽然长了点但在多来源 Skill 混合的环境里清晰度和可控性比短名字更重要。撞名前期的排查成本远高于多打几个字符的成本。5.5 排查一个真实 case我实际遇到过一个很典型的 case。当时全局目录里放了一个生成接口文档的 Skill但某一天开始它突然不触发了。我没有立刻看文件而是先用列表命令确认 Skill 还在确实在。再去检查 description发现那个 Skill 是从一个第三方仓库直接弄来的description 写的还是那个仓库作者的项目场景跟我的实际接口文档需求匹配度很低。我重写了一份 description改成直接描述生成接口文档、包含请求响应示例、标注错误码等场景词保存重启后触发率明显提升。这类问题非常常见不是 Skill 坏了而是它的自我介绍不够好。模型只能通过 description 来认识你的 Skill描述质量直接决定它会不会在关键时刻想起这个能力。所以每装一个第三方 Skill第一件事就是重读它的 description理解作者的意图再决定是原样使用还是改造成适合自己场景的版本。6. 一些实操心得放在最后说三个我自己的经验总结。第一个建议不要把太多东西塞进一个 Skill。我最早的全局 Skill 试图涵盖前端开发全流程从脚手架搭建到部署检查都写进去了结果文件一千多行每次触发都要消耗大量上下文反而影响主任务的执行质量。后来我把它们拆成五个小 Skill每个只负责一件具体的事触发率和执行质量都明显上升。一个 Skill 一个主题这是最值得坚持的原则。判断是否拆分的标准很简单如果一个 Skill 的 description 需要用和字连接两个以上场景就该拆了。第二个建议给 Skill 做版本标记。在 SKILL.md 正文或文件名里带一个版本标注比如 v1.2。每次修改完更新一下这个版本号。这样以后无论是模型加载还是你自己排查都能很快知道当前用的是哪个版本避免改了但不知道改没改成功的尴尬。我看到很多优秀开源 Skill 都会在文件头注释里写明变更时间和版本这个习惯值得学。第三个建议团队协作时把项目级 Skills 纳入 Code Review 范围。因为 Skills 本质上是团队规范的可执行版本如果某个人改错了影响的是所有人的开发体验。我们团队现在每次改动涉及 .claude/skills/ 目录必审。把 Skills 当作与业务代码同等重要的资产来管理它才能真正沉淀为团队的能力而不是某个人桌面上的孤品。最后再补一个很多人不知道的小技巧你可以把 SKILL.md 里写好的段落直接复制到对话里让模型帮你抽提出 frontmatter 和正文结构整理成一个标准 SKILL.md。我很多时候不是从零写 Skill而是先在日常对话里把规范和流程说清楚验证可行之后再让模型输出整理好的标准格式我保存到目录里。这样既省时间又能保证描述与实际操作一致。