如果你已经在用 Claude Code 写代码大概率遇到过这样的场景看别人分享了一套很顺手的 frontend skills克隆到本地之后愣了几秒——这一步该放到哪是项目根目录的.claude下还是用户主目录的.claude下我最早入坑的时候也在这卡过后来把项目级 skills 切到全局之后才算真正把这东西用明白。这篇就聊清楚skills 怎么装项目级和全局级到底什么区别以及怎么从项目级切到全局。先说结论Claude Code 的 skills 本质上是一份给 Claude 看的岗位说明书不是传统意义上的插件。它通过SKILL.md文件告诉 Claude你什么时候该用我、用了该怎么做。装的位置决定了它的作用范围放在项目目录里就是项目级放到用户主目录里就是全局。很多教程只教你怎么写SKILL.md却很少讲这层放哪的学问但恰恰是这一步决定了你的 skills 是跟着仓库走、还是跟着你这个人走。1. Skills 不是插件是给 Claude 的岗位说明书1.1 为什么 Claude Code 需要 SkillsClaude Code 本身是一个很通用的编码 agent你给它一个任务它能自己读代码、改文件、跑命令。但通用意味着不专精它知道所有编程语言但它不了解你的团队规范、你的项目结构、你的代码风格偏好。Skills 就是用来补这层信息的。打个比方Claude Code 像一个刚入职的全能实习生什么都会一点但不知道你公司的代码规范是什么样的。Skills 相当于是你递给他的几本工作手册——这是我们前端组的要求你照着这个来这是部署流程你按这个步骤走这是日志格式规范你输出的时候遵守。这样一来Claude 就不再是什么都懂的门外汉而是懂你们团队规矩的自己人。1.2 SKILL.md 的组成和触发逻辑一个标准的 skill 是一个目录目录里必须有一个SKILL.md旁边可以跟着脚本、模板、参考文档。SKILL.md的结构是 YAML frontmatter 加 Markdown 正文最关键的字段是name和description--- name: frontend-review description: 审查前端代码时使用。检查 React/Vue 组件结构、样式规范、可访问性与基础性能问题。当用户要求 review 前端代码、检查组件质量或进行代码评审时触发。 --- # Frontend Review ## 执行步骤 1. 梳理被审查文件的组件树确认数据流方向 2. 检查样式方案是否与项目规范一致 3. 检查可访问性img 是否有 alt、按钮是否有可读文本 4. 输出问题清单按严重程度排序Claude 读取这个文件的逻辑很直接每次对话开始或任务变化时它会把当前可用的 skills 的name和description放进上下文当作候选工具清单。当你的任务描述和某个 skill 的description匹配度高时它就会加载这个 skill 的完整正文按照里面的步骤执行。所以description写得好不好直接决定了 skill 会不会被触发。写得越具体、越贴近用户真实说法命中率越高。你要是只写一句用于前端审查Claude 很可能在你需要它的时候想不起来用。1.3 Skills、MCP、Subagent 到底什么关系很多人第一次接触 skills 时会把它们和 MCPModel Context Protocol搞混。我用一张表把三者的区别捋清楚维度SkillsMCP ServerSubagent本质上下文说明 可选脚本外部工具接口独立子任务 agent交互方式Claude 读取文档按步骤执行Claude 调用工具 API把子任务委托给专门 agent典型用途规范、流程、模板、批处理查数据库、调接口、访问外部系统长文档分析、大型重构是否需要联网不需要通常需要不需要学习成本最低会写 Markdown 就行中等需要理解协议中等实际使用中三者的边界没有那么死。复杂场景经常是 skills 里写清楚流程流程中用 MCP 工具查数据遇到大块独立任务再拆给 subagent。但如果你只是想给 Claude 注入某个领域的做事方法那 skills 绝对是性价比最高的切入点不需要写服务、不需要管协议一个目录一个文件就搞定。2. 装之前先搞清楚两个 .claude 目录2.1 环境检查确认 Claude Code 可用动手装 skills 之前先确认 Claude Code 已经正确安装。终端里执行claude --version能正常输出版本号就说明环境没问题。如果提示找不到命令说明 CLI 还没装好或者没进入当前 shell 的 PATH。装好的前提下你会发现系统里有几个.claude相关的目录容易混淆的就两个项目根目录下的.claude/当前仓库专属。用户主目录下的~/.claude/当前操作系统用户专属。Skills 就放在这两个目录下的skills/子目录里。目录结构的完整形态是这样的项目根目录/ ├── .claude/ │ ├── skills/ │ │ └── frontend-review/ │ │ ├── SKILL.md │ │ └── rules/ │ │ └── style-guide.md │ └── settings.json └── ... ~/.claude/ ├── skills/ │ └── commit-message/ │ ├── SKILL.md │ └── templates/ │ └── conventional.md └── settings.json2.2 项目级和全局级到底差在哪一句话说明项目级 skills 跟着仓库走任何 clone 这个仓库的人都会看到全局 skills 跟着用户走你在任何项目里都能看到。这两个级别都不难理解难的是判断该放哪。我的判断标准很简单项目级和当前仓库强相关的东西。比如本项目的前端规范本项目的部署流程本项目数据模型的增删改查约定。这些内容对别的项目没有意义甚至可能有冲突放进全局反而是污染。全局级和生产工具、个人习惯、通用能力相关的东西。比如如何写规范的 conventional commit、如何生成项目 README、代码 review 检查清单。这些在任何项目里都用得上应该跟着人走。如果你把一套通用 review skills 放进某个项目的.claude/skills/那换下一个项目你就得再装一次更尴尬的是团队里其他人 clone 仓库时也会看到你的个人 review 习惯这不一定是他们想要的。所以通用能力放全局项目私有放项目级这个原则值得刻在脑子里。2.3 一个 npm 视角的类比如果你用过 npm这个模型其实非常好懂。npm 区分dependencies项目依赖和全局包npm install -g项目依赖装在某个仓库的node_modules里随着package.json被团队共享全局包装在系统目录里是我这台机器上有、你未必有的东西。卸载全局包用npm uninstall -g xxx卸载项目依赖则在项目目录里执行npm uninstall xxx。Claude Code 的 skills 两级机制几乎是同一个思路。项目级可以类比为项目依赖进仓库、随团队走全局级可以类比为全局包是个人环境的一部分。只是 npm 全局包需要用-g参数显式安装Claude Code 的全局 skills 则是把目录放到~/.claude/skills/下更接近文件即安装。理解了这层类比之后很多操作就顺理成章了项目装了一半想共享其实就是把文件从项目级目录复制到全局目录想给某个项目临时禁用一个全局 skill用项目级同名 skill 覆盖就行。后面我会细讲。3. 项目级安装从目录到验证的完整链路3.1 最朴素可靠的装法手动放目录虽然现在有不少第三方工具能帮你管理 skills但最可靠、最不会出问题的永远是手动放置因为你完全掌控目录结构和最终状态。假设我想给当前项目装一个 frontend-review skill# 1. 进入项目根目录 cd ~/work/my-frontend-project # 2. 创建 skill 目录 mkdir -p .claude/skills/frontend-review # 3. 把 SKILL.md 放进去 cp ~/Downloads/frontend-review/SKILL.md .claude/skills/frontend-review/如果你的 skill 还带辅助文件模板、脚本、参考文档一样复制进去cp -r ~/Downloads/frontend-review/rules .claude/skills/frontend-review/这里有个很容易踩的坑SKILL.md必须直接放在 skill 目录的根上不能多套一层子目录。也就是说下面这种结构是无效的.claude/skills/ └── frontend-review/ └── frontend-review/ └── SKILL.mdClaude 扫描时只认skills/skill-name/SKILL.md这个固定层级套多了它就找不到。我第一次装别人的 skill 时就犯过这个错克隆下来的压缩包自带一层目录我没解压处理直接丢进去结果/skills里什么都看不见。3.2 从零写一个前端 review skill如果你没找到现成的自己写一个也不难。我以前端代码 review为例给你一份可以直接用的骨架--- name: frontend-review description: 执行前端代码审查。当用户要求 review 前端代码、检查 React/Vue 组件、评估代码质量或进行代码评审时触发。如果任务涉及修改而非审查不要触发本 skill。 --- # Frontend Code Review ## 审查维度 1. **组件结构**组件是否过大超过 200 行是否拆分为职责清晰的小组件 2. **样式规范**是否使用项目统一的样式方案是否存在内联样式滥用 3. **可访问性**img 是否有 alt交互元素是否有键盘可访问性色彩对比是否达标 4. **性能**是否存在不必要的重渲染列表项是否有稳定 key 5. **可维护性**命名是否清晰是否存在魔法数字是否有重复逻辑 ## 输出格式 按以下格式输出审查结果 - 严重问题必须修复 - 建议改进推荐修复 - 可选优化有时间再处理 每个问题附上文件路径、行号、问题描述和修改建议。有几个写的时候需要留意的细节name用连字符小写命名不要用空格和中文。description里最好写明什么情况下不要触发这能显著降低误触率。比如上面写的如果任务涉及修改而非审查不要触发就是因为审查和修改完全是两件事Claude 很容易混淆。正文里的步骤要写得像标准作业程序而不是泛泛的原则。你写得越具体Claude 的执行结果越稳定。3.3 验证怎么看 skills 有没有真正生效装完之后别急着让 Claude 干活先在会话里输入/skills。这会列出当前会话可见的所有 skills带路径说明是从哪个级别加载的。如果你在/skills里看到了frontend-review说明装载成功。更进一步的验证是实际触发一次。开一个新的对话输入类似帮我 review 一下 src/App.tsx 这个组件正常情况下 Claude 会回答我会按 frontend-review 的流程来检查然后按照你定义的审查维度逐项输出。如果它只是泛泛地看了一眼就给出评论说明 skill 的 description 写得不够精确回去优化它。我在这一步还有个小经验验证时故意用口语化指令比如帮我瞅瞅这个组件有没有问题而不是规规矩矩说请执行代码审查。因为用户日常说话往往不那么正式如果 skill 只对官方说法有反应那实际使用率会大打折扣。description 里建议把用户可能的多种说法都覆盖进去。4. 从项目级切到全局三条路线怎么选4.1 为什么需要把项目级切到全局最常见的场景是你在项目 A 里精心配了一套 skills用了两周发现效果不错开项目 B 的时候希望也能直接用。这时候两个选择要么把文件再复制一遍到项目 B要么直接把 skills 提为全局让所有项目共享。我的建议是只要这套 skills 不是和项目 A 深度绑定的一律提全局。因为 skills 是有迭代成本的——你改了新版项目 B 里的旧版不会自动同步时间一长就出现不同项目行为不一致的问题。提到全局之后你只维护~/.claude/skills/这一份就够。具体操作有三条路线我逐个说清楚利弊。4.2 路线一直接复制项目保留副本# 把项目里所有 skills 复制到全局 cp -r .claude/skills/* ~/.claude/skills/ # 如果只想复制某一个 cp -r .claude/skills/frontend-review ~/.claude/skills/复制是信息最安全的方式项目里的那份还在万一全局出了问题可以回退。缺点也很明显以后你改了全局版本项目里的旧版本就和新版本脱节了。如果你希望各个项目表现一致下次记得回到项目里同步或者干脆这么做之前先想清楚。我的判断标准是如果这套 skills 本身就是全局共享的复制之后建议把项目里那份删掉避免下次打开项目时出现重复加载的感觉同一套东西有两份版本还不一样。4.3 路线二移动彻底迁移mv .claude/skills/frontend-review ~/.claude/skills/移动的本质是剪贴源目录里不再保留。好处是一份文件、一个真相源以后只改全局那份就行坏处是项目 clone 给别人时这套 skills 不会跟着走毕竟它已经属于个人环境了。这条路线最适合个人开发、多项目复用的工作流skills 是我的工具不属于任何单一仓库。4.4 路线三软链接集中维护分散展现我的首选如果你在项目里既想保留这层目录比如团队协作时其他人需要看到又不想真的维护两份可以用软链接# 全局放真实文件 mkdir -p ~/.claude/skills/frontend-review # 真实文件放到全局 vim ~/.claude/skills/frontend-review/SKILL.md # 项目里建立软链接 ln -s ~/.claude/skills/frontend-review .claude/skills/frontend-review这样项目里的.claude/skills/frontend-review只是全局目录的一个入口你改全局文件项目里立刻生效。团队其他人 clone 后看到目录存在但如果不做同样的链接动作他们本地不会有内容——这其实是可控的因为链接本身一般不会提交进 git。我自己现在就是用这种方式管理大部分通用 skills。唯一的坑是如果哪天你把整个项目目录打包发给别人软链接解压后可能失效对方会看到一个空的 skill 目录。所以正式交付仓库时要么把真实文件放进去要么在 README 里写清楚需要执行 ln 命令建立链接。4.5 切换后的验证清单不管你选哪条路线切完之后建议按这套清单检查一遍在全局目录下执行ls ~/.claude/skills/确认目录结构正确。随便进入一个新项目打开 Claude Code 会话输入/skills确认这些 skills 能跨项目看到。实际触发一次确认行为和项目级时一致。如果选择了复制或移动顺手把项目.claude/skills/下多余的文件清理干净避免以后产生混淆。5. 切到全局之后冲突、更新与清理5.1 同名冲突项目级优先还是全局优先切到全局之后迟早会遇到一个问题某个项目的.claude/skills/里有一个frontend-review全局~/.claude/skills/里也有一个frontend-review两个内容还不一样。Claude 加载时优先用哪一个根据 Claude Code 的约定项目级 skills 会覆盖全局同名 skills。理由是项目级通常代表了这个仓库的特殊约定比个人通用习惯更具体所以优先。这个设计平时很省心但也是隐藏的问题源你在全局改进了一套通用 review 规范某项目里躺着一份两年前的旧版项目级 reviewClaude 在该项目里表现的还是旧版行为。排查时很难想到根因是那里有份旧的项目级文件。我的建议是不做特殊处理的情况下项目根目录的.claude/skills/里只放真正项目相关的东西别图方便把通用 skills 都复制进去。宁可让 Claude 加载慢一点也不要让多份同名文件互相打架。5.2 更新迭代别让全局 skills 变成僵尸版本全局 skills 最大的风险不是装不上而是装了再也不更新。比如你在网上看到一篇很好的 skill 分享复制进来之后原作者的仓库迭代了好几个版本你本地还躺着初版。解决思路分两种一种是手动更新定期去~/.claude/skills/下检查如果某个 skill 来自公开仓库直接把仓库 clone 到临时目录再覆盖过去。另一种是自建统一管理如果你攒的 skills 多了建议把所有 skill 源文件放到一个独立 git 仓库里比如my-claude-skills/然后用脚本一键同步到~/.claude/skills/。脚本代码不复杂核心就是#!/usr/bin/env bash # 同步脚本把仓库里的技能同步到全局目录 set -euo pipefail for skill_dir in my-claude-skills/*/; do skill_name$(basename $skill_dir) cp -r $skill_dir $HOME/.claude/skills/$skill_name done echo Synced $(ls -d my-claude-skills/*/ | wc -l) skills to ~/.claude/skills/用 git 管理的好处是你能看到每个 skill 的变更历史哪天改出问题了可以 diff 回滚这比无版本管理的复制要职业得多。5.3 清理删掉不用的 skill时间一长全局目录里总会有一些装完就再也没用过的 skills。判断标准很简单某个 skill 已经超过一两个月没触发过或者你看到名字都想不起来是干嘛的那就删。删除操作rm -rf ~/.claude/skills/obsolete-skill删除前建议先整个压缩包备份一次tar -czf claude-skills-backup-$(date %Y%m%d).tar.gz ~/.claude/skills这样删错了也能恢复。我在清理时还会顺手做一件事把每个保留下来的 skill 的 description 重新读一遍看看有没有过时的工具名、失效的路径。因为很多 skill 会引用绝对路径的脚本路径一变skill 就废了但 Claude 不会主动告诉你这个 skill 引用的文件不存在。6. 值得装的 skills 方向与自建注意事项6.1 优先推荐的方向结合我实际使用的经验给几个最容易见效的方向前端开发相关。包括组件审查、样式规范检查、可访问性审计等。前端项目规范通常很琐碎正好是 Claude 容易凭感觉发挥的地方有个 skill 做约束输出质量立刻不一样。Git 提交信息规范。让 Claude 按 Conventional Commits 规范帮你生成 commit message。这属于典型的任何项目都用得上的全局 skill值得第一时间装上。代码 review 流程。定义审查维度、输出格式、严重程度分级适合团队统一 code review 口径。但注意这类 skill 如果涉及团队特定规范更适合放项目级通用审查放全局。文档生成。根据代码生成 README、更新 API 文档、整理 CHANGELOG都属于重复性高、需要固定格式的活交给 skill 做最稳。测试生成。让 Claude 按你的测试框架约定自动补测试可以定义测试文件命名、mock 方式、断言风格。这个需要对团队规范做定制一般放项目级。6.2 自建 skill 的四个注意点看了很多如何写 skill的教程但实际踩过坑之后我觉得有四点是真正决定成败的第一description 要写用户会怎么说而不是你想让 Claude 做什么。用户说帮我看看这个函数有没有问题不会说请对该函数执行静态代码质量评估。你写的时候多想想真实对话里的措辞触发率能提高一大截。第二步骤要可执行不要写空话。分析代码质量和检查是否存在重复逻辑、命名是否清晰、是否有魔法数字、函数是否超过 50 行是完全不同的两段描述后者的执行结果稳定得多。第三善用allowed-tools字段约束行为。如果 skill 内部需要读取某个项目目录或运行特定脚本可以在 frontmatter 里声明允许的工具避免 Claude 因为权限不足而中途放弃。但要克制尽量遵循最小权限原则别把所有工具都放开。第四skill 不是越详细越好。一个 SKILL.md 写了上千行Claude 在匹配时反而会犹豫——它需要判断哪些内容适用。理想的长度是能讲清楚触发条件和执行步骤剩下细节放到附加文件里让 Claude 按需加载。收尾再补两个实操细节作为补充最后说两个我在实际操作中发现的小细节都是文档里不太会写的。第一个是关于/skills命令的。有时候你装好了一个 skill重启会话后/skills里却没有。别急着怀疑目录结构先看看是不是缓存问题。Claude Code 对 skills 的索引并不是每次会话都全量刷新有缓存机制。遇到这种情况完全退出当前会话重新打开基本都能解决。实在不行就检查一下文件权限确保~/.claude/skills/和项目.claude/skills/的目录权限可读。第二个是关于项目级切到全局的心理包袱。我见过不少朋友觉得把项目级 skills 提全局会污染自己所有的项目。但实际上只要你按照通用能力放全局、项目专属留本地的原则规划全局目录再乱也乱不到哪去。真正让全局目录失控的从来不是切过来的 skill 太多而是那些当时觉得有用、后来再没碰过的僵尸 skill。所以定期清理、定期更新比纠结该不该切全局重要得多。从第一次手动往.claude/skills/里放文件到现在用软链接统一管理大部分通用技能我对 skills 的态度也变了不少它不只是给 Claude 加技能更像是在给自己沉淀一套可复用的工作方法。所有踩过的坑都会变成下一套 skill 里的规则而规则越多Claude 的表现就越接近你理想中的那个靠谱同事。