这几天我把手头两个项目的 Claude Code 配置彻底重理了一遍起因特别朴素我在项目 A 里辛辛苦苦配好的几个 Skills切到项目 B 时发现全都不在了。更让我意外的是我一直以为 Skills 只能装在当前项目里直到翻完官方文档才发现Claude Code 的 Skills 其实分“项目级”和“全局”两套目录生效范围和迁移方式完全不同。这篇文章不绕弯子就从我这次实际迁移的完整过程讲起先把 Skills 的目录机制说清楚再手把手演示怎么把项目级 Skills 平滑切到全局最后附上我踩过的坑和排查方法。适合所有在用 Claude Code、又不想反复重复造轮子的开发者。1. 一个 Skill 到底装了什么为什么值得专门研究1.1 Skills 的本质是“专业技能包”不是简单提示词先说个容易误解的地方Claude Code 里的 Skills 并不是普通插件也不是一段随手写的 prompt。它更像是一份“岗位工作手册”——里面写清楚了在什么场景下应该做什么、按什么步骤做、输出格式是什么有时还附带脚本和模板。Claude 会在对话中根据你对任务的自然语言描述动态判断要不要加载某个 Skill。市面上一些教程把 Skills 说得玄乎其实拆开看就几样东西一个SKILL.md文件是灵魂里面用 YAML 头写元信息正文写具体执行指令。如果这个 Skill 需要跑脚本旁边还会有一个scripts/目录需要固定模板就有templates/目录。这和 MCP 那种“连接外部工具”的机制完全是两码事后者的重点是把数据库、浏览器、GitHub 这类能力接进来而 Skill 的重点是给模型注入“专业流程和领域知识”。我自己后来的判断标准很简单需要操作外部系统优先想 MCP需要规范做事方式优先写 Skill。1.2 描述description写得好不好直接决定 Skill 会不会被触发这里有一个很关键的机制Claude 不会把每个 Skill 的全文都塞进上下文而是先看每个 Skill 的description再把与当前任务相关的 Skill 内容加载进来。这就解释了为什么有人装了一堆 Skill 却感觉“没生效”——很可能不是没装而是描述写得不够精准模型根本没意识到该用这个 Skill。我见过太多人把描述写成“处理代码问题”“辅助开发”这种空话结果模型永远不知道该不该触发干脆全都不触发。比较实用的写法是回答三个问题这个 Skill 在什么场景下用、前置条件是什么、期望输出是什么。比如我写的前端审查 Skilldescription 是“当用户要求审查 HTML/CSS/JavaScript 代码质量、性能和安全问题时使用。适用场景包括提交 PR 前的代码检查、定位影响页面加载速度的写法、排查明显的 XSS 风险写法。输出为按严重程度排序的审查报告。” 这句描述比正文还费心思因为它是模型判断“要不要用”的唯一依据。1.3 为什么不该再靠“现场写提示词”替代 Skills很多人的第一反应是既然 Claude 上下文窗口那么大我每次把要求讲清楚不就行了短期看确实可以但长期看有四个问题。第一是上下文浪费每次都把完整流程塞进去没过几分钟窗口就满了第二是不可复用换个项目、换个任务又得重新组织语言第三是不稳定你上午写的提示词和下午写的基本不会完全一致输出的质量自然飘忽不定第四是没法团队共享个人打字的速度永远追不上团队规范的更新节奏。把流程固化进 Skill 文件之后等于把这些知识资产存下来了还能放进 git 里做版本管理这才是把它当成工程资产来对待的态度。我现在的工作习惯是任何重复执行过两次以上的编码任务都值得花十分钟整理成 Skill。前期投入不大后期省下来的时间非常可观。2. 安装前的三件事版本、登录状态和基础文件目录2.1 先确认 Claude Code 处于支持 Skills 的版本这个听起来像废话但我真的要提醒一句如果版本太老后面的所有目录规则都可能对不上。先用命令确认版本claude --version如果版本偏旧优先用官方的在线升级命令claude --update如果你当初是用 npm 全局安装的也可以这样升级npm update -g anthropic-ai/claude-code国内网络环境下 npm 下载慢是常见问题解决思路是给 npm 换一个速度更友好的镜像源比如在 npm 配置里设置国内镜像地址后重新安装这一步属于常规的 npm 配置操作和 Claude Code 本身无关具体按你惯用的镜像源说明走就行。升级完成后记得重开终端别在一个旧版本的进程里验证新功能。2.2 确认登录状态和账号地区是否可用登录状态直接影响 Skills 能否正常加载因为 Skills 依赖 Claude Code 的客户端能力。一般在终端执行claude进入交互界面第一次使用会引导登录按提示在浏览器里完成授权就行。如果界面里能正常对话、能看到模型响应登录就是通的。这里要专门提一个很多人会遇到的提示运行时如果告诉你“Claude Code might not be available in your country”之类的话一般意味着账号所属地区不在官方当前的支持范围内。处理思路很简单先核实账号地区和支付方式是否满足官方要求再关注官方对该地区的支持范围有没有调整。不要尝试任何非官方渠道的“绕行方案”一是不符合使用条款二是稳定性毫无保障出了问题你连日志都没法正经排查。2.3 先把两个 Skills 目录建好后面不慌乱无论你打算装项目级还是全局提前把目录结构建立起来总是对的。在终端里执行# 全局目录当前登录用户通用 mkdir -p ~/.claude/skills # 项目级目录在项目根目录下执行 cd /path/to/your-project mkdir -p .claude/skillsmacOS 上~默认就是/Users/你的用户名Linux 是/home/你的用户名Windows 上是%USERPROFILE%。如果你用的是 VS Code 里的 Claude Code 扩展目录规则也一样扩展只是套了一层编辑器界面底层读取的还是这两个位置。建好目录之后用ls -la ~/.claude/看一眼确认没有权限问题。3. 项目级和全局差在哪路径、场景与优先级3.1 项目级目录跟着仓库走适合团队共享项目级 Skills 放在项目根目录的.claude/skills/下面。它的特点非常明显随仓库走、随 git 走。你在.gitignore里只要不特意排除这个目录就会被提交到代码仓库团队成员拉下代码后自动拥有同样的 Skills。适合放项目级的内容通常是和这个项目强绑定的规则与流程。举个例子某个 Vue 前端项目里约定组件必须用script setup语法、样式必须走设计系统的 token、图片必须统一走懒加载组件这些规范写成一个frontend-code-standardSkill 放在项目里团队成员在 Claude Code 里干活时模型就会自动按这套规范审查和生成代码。这比在 README 里写一大段规范更有效因为规范直接作用在 AI 助手的工作流上。3.2 全局目录跟着用户走适合个人通用能力全局 Skills 放在~/.claude/skills/下面。它的特点是跨项目生效和你在哪个仓库工作没关系是所有项目都能调用的“个人能力库”。适合放全局的是那些和具体项目无关、但你天天都在用的技能。比如生成规范的 commit message、审查代码通用问题、写README、整理 CHANGELOG、把接口文档转成 TypeScript 类型定义。这些技能放在任意项目里都能用放全局可以省去每个项目重复安装的麻烦。我之前把commit-helper从项目级切到全局后现在无论在哪家仓库写提交信息都能走同一套格式规范体验非常顺。3.3 同名冲突时谁说了算项目级优先在实际使用中我测试过同一个 Skill 名称在两边都存在的情况结论是项目级优先。也就是说如果全局有一个code-review项目里的.claude/skills/code-review也存在Claude 在项目里干活时加载的是项目里那个版本。这其实是个很有用的设计可以玩出“全局通用版 项目定制版”的组合。统一规则放全局个别项目的特殊要求用同名 Skill 覆盖。需要注意的是这个行为我没有在官方文档里看到非常明确的描述更多是我在实际测试中的观察建议你自己搭两个一次性目录验证一遍几分钟就能确认之后用起来心里有底。4. 干货实操把项目级 Skills 平滑迁移到全局4.1 迁移前先盘点看看项目里到底装了什么迁移第一步不是动手而是先搞清楚手里有什么。先进入项目根目录列出当前项目级 Skillscd /data/webapp ls -la .claude/skills/我当时的项目里有两个自定义 Skill 和一个从插件市场装来的 Skillfrontend-audit、commit-helper、html-scan。其中frontend-audit和commit-helper是我自己写的html-scan是从官方 skills 市场里装进来的插件型 Skill。对比之后我发现前两个和项目没有强绑定关系适合全局html-scan当时还处在试用阶段我决定先在项目里再观察几天。这一步千万别偷懒。你至少要逐个打开SKILL.md看一眼描述和依赖确认它是“项目专用型”还是“通用型”否则后面一锅端搬到全局反而会把不该扩散的东西扩散出去。4.2 备份永远不要省迁移前先打快照移动文件这种操作虽然简单但一旦中途断电、手滑敲错路径损失的就是配置资产。我习惯先打一个带时间戳的备份cp -r .claude/skills ~/.claude-skills-backup-$(date %Y%m%d)备份做完用ls确认备份目录里内容和原目录一致再继续。这一步花不了十秒钟却能让你之后随意试错。4.3 三种迁移方式复制、移动、软链接各有各的适用场景把项目级 Skill 变成全局最直接的无非三种做法我分别说一下它们适合什么情况。复制cp -r .claude/skills/frontend-audit ~/.claude/skills/。结果是两份独立文件之后两边各自演化互不影响。适合你想在项目里留一份“旧版对照”或者只是想临时试用、不想让项目目录空掉的情况。缺点也明显之后改动全局版本时项目里的旧版不会自动同步。移动mv .claude/skills/frontend-audit ~/.claude/skills/。这是最干净利落的方案文件从项目目录消失全局目录多出来。适合我这种已经确认 Skill 通用性足够、不想再维护双份文件的情况。副作用是项目里不再自带这份配置和你协作的同事也看不到了。软链接ln -s /data/webapp/.claude/skills/frontend-audit ~/.claude/skills/frontend-audit。效果是全局目录里出现一个指向项目目录的链接两处其实是同一份文件改一处就是改两处。这个方案最适合正在迭代调试中的 Skill——你还在频繁修改它希望所有项目立即生效最新版同时又想保留项目目录作为“唯一真源”。Windows 用户注意ln -s在原生环境里不一定可用可以用管理员权限的mklink命令或者第三方junction工具效果是等价的。我自己的选择是已经稳定运行的 Skill 用移动还在频繁改的用软链接复制只用在“临时实验”场景。4.4 完整迁移流程示例从项目级切到全局下面给出一套我实际跑通的完整命令序列以 Linux/macOS 为例。假设项目路径是/data/webapp里面有frontend-audit和commit-helper需要迁到全局cd /data/webapp # 1) 备份 cp -r .claude/skills ~/.claude-skills-backup-$(date %Y%m%d) # 2) 确保全局目录存在 mkdir -p ~/.claude/skills # 3) 迁移用移动方式 mv .claude/skills/frontend-audit ~/.claude/skills/ mv .claude/skills/commit-helper ~/.claude/skills/ # 4) 清理空目录如果里面已经没有别的文件 rmdir .claude/skills # 5) 验证 ls -la ~/.claude/skills/这里有一个细节要提醒rmdir只会在目录为空时执行成功如果.claude/skills里还留了其他 Skill命令会直接报错这反而是好事——它提醒你项目里还有事情没处理完。.claude/目录下面除了skills往往还有settings.json、commands这些配置别因为迁移就把整个.claude/删了。如果你用的是 Windows把路径换成C:\Users\你的用户名\.claude\skills其余逻辑完全一致。如果你希望迁移的同时保留一个调试中的链接可以把第 3 步的mv换成第 4.3 节里的ln -s命令。4.5 迁移后怎么验证真的生效了文件层面验证过了还要验证 Claude Code 运行时是否真的加载了。我最常用的三种验证方式第一种在 Claude Code 会话里输入斜杠命令查看已加载 Skills比如/skills看列表里有没有刚迁移的那个名字。如果它后面标注了 global说明已经被识别为全局技能。第二种加--debug启动客户端然后观察启动日志里每条 skill 的加载路径claude --debug日志里可以看到类似 “Loading skill ... from ~/.claude/skills/...” 的路径信息。如果路径仍然指向项目.claude说明会话还活在旧上下文里重开一个新会话再看。第三种直接行为验证。找一个和 Skill 描述匹配的任务让 Claude 做比如对frontend-audit就说“按咱们的规范审查一下 src 下的代码”看它的回答是否遵循了 Skill 正文里规定的流程。如果它压根不提 Skill 里的清单说明描述匹配出了问题回到第 1.2 节改描述。迁移完成之后我的建议是把家里所有项目都扫一遍看看还有没有项目级 Skills 其实是通用型但被误装成项目级的顺手清一轮。5. 手写一个前端审查 Skill 并装进全局5.1 一个通用型前端审查 Skill 应该长什么样为了把上面的理论落到地上我手写了一个通用型frontend-auditSkill然后直接装进全局目录。它的使用场景很明确在提交 PR 之前让 Claude 按一套固定清单审查前端代码重点检查语义化、性能隐患和常见安全问题。目录结构是这样的~/.claude/skills/frontend-audit/ ├── SKILL.md └── scripts/ └── scan.shSKILL.md是核心指令scripts/scan.sh是一个可选辅助脚本用来快速统计代码文件分布。这样设计的好处是Skill 不只是给模型看的文本还能让模型在执行过程中调用脚本获取项目实际情况指令更落地。5.2 编写 SKILL.md 的操作要点打开~/.claude/skills/frontend-audit/SKILL.md写入以下内容--- name: frontend-audit description: 当用户要求审查 HTML/CSS/JavaScript 代码质量、性能和安全问题时使用。适用场景包括提交 PR 前的代码检查、定位可能影响页面加载速度的写法、排查明显的 XSS 风险写法。输出为按严重程度排序的审查报告。 --- # 前端代码审查技能 你是一名资深前端工程师请按以下步骤审查用户提供的代码 1. 先识别项目技术栈原生 / React / Vue 或其他框架。 2. 按清单逐项检查 - 语义化标签是否使用正确 - 图片是否缺少 alt 属性、是否指定尺寸 - 关键路径上是否有同步脚本阻塞渲染 - 内联事件处理器是否引入了 XSS 风险 - CSS 选择器是否存在明显的性能隐患。 3. 如需统计代码文件分布运行 scripts/scan.sh。 4. 输出审查报告按严重程度排序严重问题 建议优化 可忽略。每项必须给出具体文件位置和示例修复代码。写这个文件时有三个细节值得注意。第一name字段要用小写短横线格式不要用空格和下划线否则可能解析不了。第二正文里的步骤要写得可执行避免“分析代码质量”这种模糊指令要写“检查图片是否缺少 alt 属性”这种能直接判定的条目。第三描述部分必须把触发场景写得具体这是整个 Skill 里最值得花时间打磨的部分。5.3 加点辅助脚本让 Skill 真的能干“体力活”我接着在scripts/scan.sh里放了一个统计脚本#!/usr/bin/env bash # 统计项目中前端文件的分布供 frontend-audit 技能使用 echo HTML ; find . -name *.html -not -path ./node_modules/* | wc -l echo JS ; find . -name *.js -not -path ./node_modules/* | wc -l echo CSS ; find . -name *.css -not -path ./node_modules/* | wc -l然后给脚本加执行权限chmod x ~/.claude/skills/frontend-audit/scripts/scan.sh为什么加这个脚本因为模型在审查代码之前先知道项目的文件规模和类型分布能够更合理地安排审查节奏。比如发现 JS 文件数量很大它就会优先检查打包和异步加载相关的问题如果 HTML 数量很少它就知道大概率是个重 JS 应用。这个小脚本把模型从一项不必要的猜谜游戏中解放出来。5.4 把 Skill 装进全局并实测因为这个 Skill 我直接建在了~/.claude/skills/frontend-audit所以它天生就是全局的不需要再做迁移。装完后我在一个 React 项目里开了一个新会话输入“帮我审查一下 src 下的组件代码重点看性能和 XSS 问题”观察 Claude 的响应。第一次测试它确实按照 SKILL.md 里的清单进行了输出报告也做了严重程度分级。但我也注意到一个瑕疵它没有调用scan.sh。原因是这个场景下它判断不需要统计文件分布。如果你想让它强制调用脚本就得在正文里加强语气写成“审查前必须先运行scripts/scan.sh获取文件分布然后再进入审查步骤”。指令的强制性程度会直接影响模型的执行意愿这是写 Skill 时要反复调校的地方。6. 常见问题速查与我的排查方法6.1 装完却“没生效”先对着这张表排查下面这些情况几乎每一个我都遇到过整理成表格方便你对照现象可能原因处理方式目录有文件但/skills看不到SKILL.md的 name 格式不合法或 YAML 头写错检查 name 是否为小写短横线检查 YAML 头是否完整闭合全局装了但在某项目里不生效项目级存在同名 Skill优先级更高查看项目.claude/skills下是否有同名目录Skill 始终不触发description 写得太宽泛或太窄模型匹配不上重新打磨描述写清场景和输出官方市场安装失败或超时网络不稳定、仓库地址无法访问改用 git clone 后手动放入 skills 目录换机器后 Skills 全丢了全局 Skills 没有做版本管理把~/.claude/skills初始化为 git 仓库并推送远端修改后行为没变化会话没有重新加载重启会话或用--debug确认加载路径6.2 我的万能排查四步排查 Skills 问题我有一个固定套路绝不乱试。顺序严格按“文件是否存在 → 内容是否合法 → 描述是否命中 → 会话是否重载”来。第一步看文件系统。ls -la确认 Skill 目录在正确位置全局在~/.claude/skills项目级在.claude/skills。目录位置错了后面全免谈。第二步看语法。把SKILL.md打开确认 YAML 头没有语法错误。YAML 对冒号和缩进敏感name:后面少个空格都会导致解析失败。我遇到过最离谱的一次是一个不可见字符混进了 name 字段导致 Claude 一直不识别。第三步看描述。假设你现在是个不知道有这个 Skill 的模型读一遍描述能不能准确判断“该不该用”这步最好隔一天再回头看新鲜感过去之后的判断才客观。第四步重启会话。Claude Code 对 Skills 的加载发生在会话初始化阶段如果你装了新 Skill 后没重开会话它确实可能感知不到。别急着怀疑配置先重开一个会话再测。6.3 强烈建议把整个全局 Skills 目录交给 git 管理最后分享一个极大减轻未来负担的技巧把~/.claude/skills/本身变成一个 git 仓库。cd ~/.claude/skills git init git add . git commit -m init skills然后在 GitHub 或你的私有 Git 服务上建一个空仓库把本地目录推上去。以后每新增或修改一个 Skill就提交一次。换新电脑时git clone下来几分钟之内你的全部技能库就恢复了。这套玩法最大的价值不是备份而是留下历史版本——哪天你改坏了一个 Skillgit diff能帮你精确看到哪里出了问题git checkout能一键回退。对我来说这个仓库已经变成了比任何配置记录都重要的个人资产。我个人在实际操作中还有一个强烈倾向不要贪多。把全局目录控制在十个以内每个都是真正高频使用的技能。技能一多模型在选择时会更容易混淆反而降低命中率。定期清理无效、合并重复比不断新增更有意义。迁移这件事本身不难难的是顺手整理出一套真正属于自己的工作流。如果你也刚装完一两个 Skill我建议你从把第一个通用型技能放进全局开始。