Claude Code 用久了你会发现真正拉开配置效率差距的不是模型参数而是 Skills。大多数新手面对“安装 Skills”这种需求时第一反应就是把文件夹往.claude里一丢却没搞清项目级和全局级是两个完全不同的生效范围结果换了仓库之后技能集体消失或者全局技能跟项目自带规则打架。这篇文章就专门说清楚两件事第一技能到底怎么装才能被 Claude Code 识别第二怎么把一个项目里打磨好的技能从项目级切到全局级。最后把我在反复安装、迁移、排错过程中攒下来的经验和坑一并交代清楚方便你照着操作。1. Skills 的存放逻辑与加载机制项目级、全局级必须分清说到 Skills其实不用整什么高深原理你只需要先记住两个目录位置。项目级项目根目录/.claude/skills/只对当前项目生效会跟着代码仓库走全局级~/.claude/skills/在 Windows 上通常是C:\Users\你的用户名\.claude\skills\它对这台机器上所有由你启动的 Claude Code 会话生效。每个 skill 就是这两个目录下的一个子目录子目录里必须有一个文件叫SKILL.md。Claude Code 在会话启动的时候会扫描这两个根目录逐个读取SKILL.md文档头部的 YAML frontmatter把里面声明的name和description注册进当次会话。也就是说真正决定 Claude 什么时候调用这个技能的是description那一句话真正决定技能执行什么动作的才是SKILL.md正文中的步骤说明。我最初犯过一个很蠢的错误把整个技能目录直接扔进~/.claude以为这样就算装好了。结果 Claude 完全不认识它。后来我总结出一个笨但特别有效的自查方法打开技能所在目录看路径是不是严格对应.claude/skills/技能名/SKILL.md中间少任何一层都有概率扫描不到。别笑这个问题在 Windows 上更容易出现因为资源管理器默认帮你隐藏了.claude这种点开头的目录。项目级和全局级的选择可以直接参考这张表维度项目级./.claude/skills全局级~/.claude/skills生效范围仅当前项目当前用户的所有项目跟随代码仓库分发可以提交到 git 后队友也能拿到不行只存在本机适合内容团队规范、项目专属流程个人习惯、通用方法论同名冲突优先级更高项目会盖掉全局更低更新成本每个项目分别改改一处全部生效1.1 为什么 description 决定技能能不能被“想”起来Skill 的触发机制和很多人想象的并不一样。Claude Code 不会把每个技能的全部正文都塞进上下文那样上下文很快就会被几十个 SKILL.md 撑爆。它只把每个技能的name和description作为候选信息注册进系统当你的提问和这段描述足够相关时模型才判断“这个场景应该调用某个技能”然后把对应的SKILL.md全文读入当作一份任务说明书来执行。这个设计的本质是“把工作模板外置”。对话过程中主上下文始终保持轻量技能要承担的具体步骤、规范要求、输出格式全部放在需要时才加载。它的副作用就是如果你把 description 写得像一句很随意的话模型大概率永远想不起来要用它。拿我自己举例。我一开始给某个审查技能写的 description 是“前端审查用”后来发现它几乎不会被自动触发。改成“当用户要求审查前端代码、检查组件交互、评估页面样式是否符合项目规范时使用”之后触发频率明显提升。原因很简单description越能覆盖用户真实提问的各种变体模型把它挑出来的概率就越高。1.2 什么情况下你需要“从项目级切到全局”标题里那个“从项目级切到全局”不是个抽象概念它对应几种非常具体的场景。第一种你在 A 项目里写了一个顺手到不行的代码审查技能结果切到 B 项目、C 项目时发现它不在这才意识到它只属于 A 项目。第二种团队仓库里早就放了一个技能目录但里面混进了你个人的工作习惯你不想用这个版本污染项目希望把自己那版提为全局默认。第三种你想建立一套“个人基础工作流”不管打开哪个仓库Claude 都应具备同样一批基础技能而不是每开一个新项目就得重新复制一遍。这三种场景都指向同一个操作方向把技能从“跟着仓库走”变成“跟着你走”。但我必须提前提醒一句切换不是简单地把文件搬个家。如果搬完之后项目目录里还残留同名技能项目级会覆盖全局级你改了全局版本却不生效到时候更让人摸不着头脑。2. 项目级安装从拿到一个 skill 到让它真正生效项目级安装是所有安装方式的基础。先把它吃透切全局只是多走两步复制和清理的事。2.1 从官方 skills 仓库手动安装一个现成技能我第一次练手用的是 Claude 官方维护的 skills 示例仓库。操作流程并不复杂就是 clone 下来、挑一个目录、复制到项目.claude/skills下。完整命令如下# 1. 先把官方仓库临时克隆到 /tmp git clone --depth 1 https://github.com/anthropics/skills.git /tmp/skills-repo # 2. 看一看仓库里有哪些技能 ls /tmp/skills-repo # 3. 把需要的技能目录复制到当前项目 cp -r /tmp/skills-repo/artifact-analysis .claude/skills/ # 4. 清理临时克隆 rm -rf /tmp/skills-repo执行完之后可以确认一下目录结构是否完整your-project/.claude/skills/artifact-analysis/SKILL.md这一步最重要的问题是你当前项目根目录下有没有.claude文件夹没有的话先mkdir -p .claude/skills再复制不然cp命令会把目录结构复制得乱七八糟。2.2 验证一个 skill 是否被当前会话识别复制完技能之后一定不要在当前会话里继续验证。最可靠的方式是退出当前会话重新打开一个全新的 Claude Code 会话然后直接用一句包含技能用途的话去测试。比如我安装了 artifact-analysis 之后就在新会话里问“你现在注册的技能列表里有没有 artifact-analysis如果没有告诉我你目前有哪些技能。”如果它能够准确报出这个名字并简述用途说明目录层级和SKILL.md都正常如果它说完全没有这个技能那基本可以断定是目录层级不对或者是SKILL.md文件名的拼写问题。2.3 手写一个最小可用的项目级 skill更多时候你要的技能根本找不到现成的。比如你们团队内部有一套独特的代码规范你希望 Claude 能按照这套规范做审查那就得自己写。一个最小可用的 skill 只需要一条命令能创建出来mkdir -p .claude/skills/our-frontend-review cat .claude/skills/our-frontend-review/SKILL.md EOF --- name: our-frontend-review description: 针对本项目前端代码的审查技能。当用户要求 review 前端代码、检查组件问题、评估页面交互是否符合项目规范时使用。 --- # 前端代码审查 执行以下步骤 1. 先读取项目根目录的 docs/frontend-guideline.md了解本项目规范。 2. 按组件结构、样式细节、交互逻辑、可访问性四个维度审查。 3. 每个问题按“严重 / 一般 / 建议”三级输出。 4. 修改意见必须给出具体的文件路径和行号。 EOF这是我在项目里用了很久的一个前端审查技能雏形虽然简陋但它完整踩中了 Claude Code 识别技能的三个关键要求目录名合法、SKILL.md命名规范、frontmatter 的name和description齐全。这里我想重点强调 description 的写法。很多人会把它写成一句名词解释比如“前端审查 skill”但这对模型触发没有任何帮助。触发能力来自一句包含“用户可能怎么表达需求”的描述我的习惯是套用“当用户要求 / 当请求场景包含 / 仅当满足条件时”这类句式。description 不是给你自己看的说明书是给模型的候选匹配信号。手写技能还有几个经验供你参考name字段用英文短横线命名不要用中文也不要包含空格避免在不同操作系统间产生解析差异。action 步骤最好写成有序列表模型执行时天然容易遵守顺序。正文不要堆背景知识第一步应该直接告诉模型“先去读什么、再检查什么”。2.4 项目级与全局级的试用节奏我个人的习惯是任何新技能先在某个真实项目里试用两三天看它触发是否稳定、输出是否符合预期。稳定之后再决定要不要切到全局。这样操作有一个额外好处你顺手就走了一遍“项目级到全局”的完整路径比空想切换逻辑靠谱得多。3. 从项目级切到全局复制、软链与团队仓库策略这节是整个主题的重头戏。切到全局在操作上无非两个要点把技能文件放到全局目录同时处理掉项目目录里的残留。3.1 最直接的搬移先复制、验证、再删除以our-frontend-review为例最直观的命令是这样mkdir -p ~/.claude/skills cp -r .claude/skills/our-frontend-review ~/.claude/skills/ rm -rf .claude/skills/our-frontend-review但这条命令连起来跑有个隐性问题你没办法确认全局那份是否可用就把项目里那份删了。万一复制过程中因为路径或权限问题导致文件不完整原来还能用的技能就彻底没了。我更推荐分成三步走。第一步只复制不删除cp -r .claude/skills/our-frontend-review ~/.claude/skills/第二步开一个全新的 Claude Code 会话在任意一个目录下测试这个技能还能不能被识别和触发。第三步确认全局版本正常工作之后再回到原项目删除项目级副本rm -rf .claude/skills/our-frontend-review这里有一个非常容易踩的陷阱当你复制完还没删除项目级副本时项目级和全局级同时存在同名技能Claude Code 会优先读取项目级那份。如果你此时急着验证“全局是否生效”得到的其实是项目级版本的行为结果会让你误以为切全局成功了。所以删除项目副本之后一定要再开一个新会话验证一次这次看到的行为才真正来自全局目录。3.2 用软链接让项目和全局共用同一份如果你希望某个技能既在全局生效又在当前项目里继续保留入口甚至做到“改动一份、两边同步”可以用软链接。mv .claude/skills/our-frontend-review ~/.claude/skills/ ln -s ~/.claude/skills/our-frontend-review .claude/skills/our-frontend-review执行之后项目目录下那一条就是指向全局目录的符号链接。Claude Code 扫描项目级 skills 目录时会顺着链接读到全局的真实内容。这样做的最大好处是单源维护以后想更新这个技能直接改~/.claude/skills/our-frontend-review/SKILL.md就行不用再比较项目版和全局版哪个新。不过软链接有个明显局限它只对你当前这台机器有效。如果项目提交到了团队的 git 仓库同事 clone 下来之后链接往往在原位失效项目反而少了一个必要技能。所以在个人项目里我会用软链团队项目我基本不用除非我在仓库里同时写清楚这个目录的引用关系。3.3 Windows 里的命令差异Windows 用户如果是在 Git Bash 或者 PowerShell 里操作ln -s的行为和 Linux/macOS 不太一样。Git Bash 在某些权限配置下不会真正创建符号链接而是退化成复制导致你后续改动全局文件时项目里的副本纹丝不动。PowerShell 里创建符号链接可以用New-Item -ItemType SymbolicLink -Path .claude\skills\our-frontend-review -Target $HOME\.claude\skills\our-frontend-review如果嫌麻烦Windows 上最省心的方案还是直接用cp -r把文件复制到全局目录再删除项目目录里的原文件夹。虽然少了一点“自动同步”的好处但在 Windows 上少踩权限坑我认为更划算。3.4 团队仓库里的切换策略切换到全局这件事在个人项目里很简单但放到团队仓库里就需要多些考量。试想一下你把自己常用的审查技能迁到了全局然后从项目目录里删掉了它。同事 pull 代码后会突然发现项目里少了一个团队一直在用的技能而且他们压根不知道这是你个人的迁移操作。我的建议是这样如果某个技能承载的是团队共识比如代码审查规范、接口文档生成规则那它应该继续留在项目级并且提交到 git让全团队共享同一版本如果某技能只是你的个人提效工具那就切到全局同时记得在项目提交说明里注明“已迁移至全局项目内不再内置”。另外可以考虑在项目的.claude/skills/README.md里写几行索引说明哪些技能属于项目、哪些指向全局个人技能免得后来人接手时对着目录猜谜。4. 装完不生效按这条链路排查装技能不生效是社区里出现频率最高的问题。我把实际排查过的案例归纳成一条链路按顺序检查下来基本能覆盖 90% 的情况。4.1 第一步分清是“没识别”还是“没触发”两种不生效对应的原因完全不同。没识别指的是你问 Claude 当前有哪些技能时它根本报不出这个名字这通常是路径、命名、扫描的问题没触发指的是它知道有这个技能但你在对话里提相关需求时它不主动调用这通常指向 description 写得太差。区分方法很简单开新会话先让它列技能列表再按触发场景提问。如果列表里没名字检查目录层级和 SKILL.md如果列表里有名字但不触发去改 description 的措辞不要动目录结构。这两个方向搞反了会浪费大量排查时间。4.2 目录与命名的三个高频错误绝大多数的“新装的技能没反应”最后都归结于三个低级失误少了skills这一层目录。把技能放在了~/.claude/foo或项目/.claude/foo正确的必须是~/.claude/skills/foo或项目/.claude/skills/foo。SKILL.md的大小写或拼写不对。有人写成skill.md有人写成SKILL.MD在大小写不敏感的文件系统上可能正常但换到 Linux 容器或 CI 环境就会失效。技能目录内部根本没放SKILL.md只有一堆说明图片、代码示例。Claude Code 只按SKILL.md这个名字去找入口其他文件再齐也白搭。4.3 frontmatter 解析失败会整包丢弃就算目录和文件名全对frontmatter 解析失败也会让整个技能被忽略。我见到比较多的问题有几个文件开头少了---用了中文全角冒号替代了 YAML 的:description 想换行却直接硬回车导致 YAML 结构破损。最稳的模板就是下面这一版不要发挥直接照抄--- name: my-skill description: 当用户要求……时使用执行……。 ---description 尽量保持一行。如果确实需要多行使用 YAML 支持的|-或折叠语法不要在行中间随手敲回车。4.4 改完技能必须新开会话Claude Code 通常是在会话开始时完成技能扫描的。你中途改了SKILL.md、加了新技能旧会话不一定能感知到这些变化。我经常犯的毛病就是改完 description 继续在同一个会话里测试结果发现行为没变误以为改坏了其实只是旧会话还在用旧状态。规避办法很简单任何技能新增或修改直接退出当前会话重新新建一个会话再验证。这个小习惯能省掉很多无谓的猜测。4.5 全局与项目重名的覆盖陷阱这是“切到全局但始终不生效”最常见的原因。项目级技能的优先级高于全局级当你全局目录里有一份our-frontend-review项目目录里又残留一份同名旧版Claude 读到的永远是项目里那份。你在全局目录里改得再勤也不会反映到当前项目行为里。排查这个情况可以用两条命令find . -type d -name our-frontend-review ls ~/.claude/skills/只要两个位置出现同名技能优先以项目目录里的为准。想彻底切到全局务必清理项目目录下的原文件夹或软链然后再开新会话验证一次。5. 安装后的验收清单与几类值得装的 skill最后给一份可以直接照着做的验收清单以及我长期使用下来认为真正算得上“必装”的技能类型。5.1 一张能直接用的验收表检查项操作方法通过标准目录正确检查路径层级完整出现.claude/skills/名字/SKILL.md命名正确列出技能目录文件文件名严格为SKILL.mdfrontmatter 合法打开文件看首尾格式以---开头和结尾无 YAML 报错已被注册新会话询问技能列表Claude 能报出技能名和用途能被触发用 description 中的场景提问Claude 自动按 SKILL.md 内步骤执行优先级正确项目级与全局级同名时观察项目级内容生效全局不产生干扰切换后无残留检查项目 skills 目录旧目录或软链已清理干净这张表我每次装完新技能都会过一遍没有再被“技能没反应”困扰过。5.2 我认为称得上“必装”的几类技能先说结论我最推荐的并不是某一个具体技能而是一类“流程模板型”技能。这类技能非常适合做成SKILL.md因为它的核心价值就是把分散的、容易被遗忘的步骤固化下来。提交信息生成固定按 Conventional Commits 规范生成提交信息要求模型先读git diff再判断 scope最后输出完整的 message 和 changelog 片段。前端代码审查结合项目内的样式规范、组件库文档输出分级问题清单每个问题附带文件路径和行号。单元测试生成先让模型列出测试计划再逐文件生成测试代码过程中不允许修改业务代码。API 文档生成要求模型先梳理接口定义与数据结构再按统一格式输出说明文档和示例。长任务拆解把一个大需求拆成可逐步验证的里程碑每个里程碑写清楚完成条件和验收方式。这些技能的共同点在于它们不是让模型“会做这件事”而是让模型“每次都按你的既定流程做这件事且不会跳过任何中间步骤”。技能真正解决的就是流程一致性。5.3 给全局技能目录写一份索引 README随着技能数量增长~/.claude/skills会迅速变成一个堆满文件夹的杂物间。我的建议是在全局目录里放一个README.md记录每个技能的用途、依赖的外部命令、最近更新时间。我本地维护了 30 多个技能之后深深觉得这份 README 比技能本身还关键。没有它你半年后再看这些目录根本想不起来某个技能当初是给什么场景用的。从全局删掉一个不再使用的技能不是难事但要判断“这个目录到底能不能删”没有一个好索引就只能靠猜。这一点值得你在技能数量起来之前就做好准备。说实话Skills 在 Claude Code 里的地位被很多人低估了。它不是锦上添花的插件而是把一次性对话变成可持续工作流的关键机制。我的建议始终是先在项目里试用稳定之后把真正通用的技能切到全局切换时记住项目级优先、旧会话不读新配置、清理同名残留这三条规矩基本就不会出问题。这套流程我已经反复跑了许多轮现在它已经是我换新电脑之后必做的一组初始化操作。