很多人用 Claude Code第一件事就是把所有要求和背景塞进 CLAUDE.md规则一条条往上加。等文件写到几百行日常对话的上下文已经被吃掉一大截模型反而抓不住重点。后来我把 Claude Code Skills 用起来思路才算理顺Skills 是典型的按需加载机制平时不占上下文遇到对应场景才被触发。这篇文章不说虚的直接讲 Claude Code Skills 怎么装以及如何把一个项目里用着顺手的技能从项目级配置切到全局配置。不管你是刚开始接触还是已经在团队里折腾配置应该都能找到能直接照抄的部分。1. Skills 到底解决什么问题和 CLAUDE.md 有什么不一样1.1 为什么长期塞 CLAUDE.md 会越用越难受CLAUDE.md 的设计初衷是给模型一份常驻的项目背景说明目录结构、技术栈、约定规范。它适合放“这个项目是什么、怎么跑、有什么注意事项”这类长期稳定信息。但很多人把它当成了万能收纳箱连“给函数加注释时要用中文”“提交信息必须遵循某格式”这种零散要求也往里面堆。问题在于Claude Code 在每次会话中都会把这份内容纳入上下文内容越长留给实际代码和对话内容的窗口就越少。规则过多还会互相干扰比如前面写“优先使用某框架”后面又写“项目里尽量不要引入新框架”模型面对冲突时只能靠猜。我见过一个开发者把 CLAUDE.md 写到近千行实际执行任务时模型频繁忘记开头几条规则最后只能靠反复强调治标不治本。Skills 这类按需加载机制就是为解决这个矛盾设计的技能平时不占用上下文当模型判断当前请求可能用到某个技能时才会主动读取对应的 SKILL.md。这相当于把“写在墙上的所有制度”改成“挂在工具柜里、用才拿”的方式。常驻信息仍然放在 CLAUDE.md真正需要大量步骤说明、代码样例、专项约定的事情全部拆进 Skills是更健康的使用方式。1.2 SKILL.md 的结构一个文件夹就是一个技能包Skills 的落地单位很有意思不是单个文件而是一个文件夹。每个技能目录下至少有一个 SKILL.md这是模型的入口开头是 YAML 格式的 frontmatter下面才是正文。一个典型结构长这样my-skill/ ├── SKILL.md ├── references/ │ ├── example1.md │ └── checklist.md └── scripts/ └── generate_report.pyfrontmatter 里最重要的两个字段是name和description。name是在日志、调试信息里标识这个技能的名字要求风格一致比如project-review。description是模型判断“要不要调用这个技能”的依据必须写清楚适用场景、触发条件、输入输出。如果 description 写得太泛比如“处理代码”模型就很容易误判或干脆不调用。正文部分用 Markdown 写具体执行步骤可以引用同目录下的 references 文件作为参考材料也可以在 scripts 里放脚本让技能更接近一个“完整工具”而不是一段说明文字。1.3 项目级和全局技能分别用在什么场景项目级技能放在项目目录下的.claude/skills/跟仓库一起提交团队其他人拉下来就能用。适合放团队约定相关的技能比如“后端接口规范审查”“前端组件验收清单”。全局技能放在用户目录下的~/.claude/skills/或自定义配置目录下的 skills 文件夹对本机所有项目生效适合放个人工作流比如“提交信息生成”“代码自检”这种你不想在每个项目里都复制一份的东西。两者的优先级没有特别复杂同名技能存在时实践上以项目级为准的情况更常见因为项目级更具体。但最好不要依赖这一点真撞名了最稳的办法是给技能起不同名字。我在后面迁移部分会再说。2. 安装 Skills 前先搞清楚这三件事2.1 目录位置项目级和全局的准确路径安装技能其实就是把文件夹放到正确的位置。项目级的路径是当前项目根目录下项目根目录/.claude/skills/技能名/SKILL.md全局级的默认路径是你的用户目录~/.claude/skills/技能名/SKILL.md如果你自定义过 Claude Code 的配置目录比如设置了CLAUDE_CONFIG_DIR/data/claude-config那全局技能目录就变成/data/claude-config/skills。判断自己当前用的是哪个目录最直接的办法是运行配置目录的相关命令或者直接查看环境变量有没有被设置。有人会把技能文件夹直接丢到.claude/下面少套一层skills/。这样是不生效的。我就犯过这个错在.claude/里建了个code-review/文件夹折腾半天模型完全不认最后才发现少了skills这一层。记住必须出现在skills目录下的次级目录里才叫技能。2.2 frontmatter 怎么填description 才是灵魂技能是否生效第一步看路径第二步看 frontmatter 是否规范。最基础的写法--- name: commit-message description: 根据当前 git diff 生成符合项目规范的提交信息。当用户要求写 commit message、提交信息、git 提交说明时使用。输入是 git diff 输出输出是一段结构化的提交信息。 ---name建议用连字符分隔的小写形式比如commit-message不要用空格也不要带标点。description一定要包含这几个要素这个技能处理什么任务、在什么情况下会被触发、输入是什么、输出是什么。白话说就是让模型看到某个用户请求时能一眼判断“这件事该用这个技能”。我习惯在 description 里写两遍触发词一遍放在任务描述里一遍放在使用条件里。比如“当用户要求写提交信息、commit message、git 提交说明时”。这样即使模型没有准确理解任务也能通过显式的触发词匹配到技能。很多人技能不生效八成的锅就出在 description 写得像论文摘要没有动词、没有场景、没有输入输出说明。2.3 先装一个最小可用技能练手第一次接触建议不要直接复制几千行的大技能先写一个最小技能把机制跑通。新建项目临时目录执行mkdir -p .claude/skills/hello-skill cat .claude/skills/hello-skill/SKILL.md EOF --- name: hello-skill description: 当用户要求演示技能加载或测试技能机制时使用。输出当前技能加载成功的信息。 --- 这个技能用于验证 Skills 机制是否生效。当用户提到“测试技能”或“技能加载”时你应该回应技能加载成功当前技能名为 hello-skill。 EOF然后在项目里启动 Claude Code直接说“测试一下技能加载”。如果模型能回应“技能加载成功”说明整个链路已经通了。之后再逐步替换成真实技能心里有底。3. 实操装一个项目级技能再迁移到全局3.1 第一步先确认当前技能到底落在哪个位置折腾“项目级切到全局”之前必须先搞清楚技能现在到底在哪里、叫什么名字。在项目根目录运行ls -la .claude/skills/看当前项目里有哪些技能。再运行ls -la ~/.claude/skills/看全局技能目录。两个目录都查一下你才知道要迁移的对象是什么。如果之前是通过环境变量改了配置目录记得先确认echo $CLAUDE_CONFIG_DIR如果有输出全局技能目录就不是~/.claude/skills而是$CLAUDE_CONFIG_DIR/skills。这一步忽视了后面所有复制操作都会复制错方向。确认完位置后顺手检查一下技能文件夹内部至少有一个SKILL.md文件编码是 UTF-8frontmatter 顶格写---上下没有多余空行。我遇到过技能目录名和 frontmatter 里的name不一致的情况虽然大多数版本的 Claude Code 能工作但排查问题时会非常迷惑建议一开始就让文件夹名和name保持一致。3.2 第二步从项目级切到全局的三种可复制操作第一种直接复制。这是最推荐新手的方式因为安全mkdir -p ~/.claude/skills cp -r .claude/skills/commit-message ~/.claude/skills/复制完项目里那份还在原项目不受影响。团队其他人也仍然能从仓库里拿到这个技能。缺点是你改全局那份之后如果还想维护项目里那份两边会分叉。第二种剪切后放全局。当你确定这个技能只属于个人工作流、不需要留在项目仓库里可以用移动mv .claude/skills/commit-message ~/.claude/skills/注意移动前确认项目里没有其他地方引用这个技能的路径否则会留下坏链。移动后最好重启 Claude Code 会话让模型重新扫描技能目录。第三种用符号链接维护单一源。如果你有一个技能仓库希望项目里也能就近看到这份技能可以在项目目录建一个链接ln -s ~/.claude/skills/commit-message .claude/skills/commit-message这样项目里看起来有技能但内容实际指向全局。修改全局那一份项目里自动同步。Windows 用户要用mklink /D命令注意路径带空格时用引号包住。符号链接的坑是项目换机器、重新克隆后链接会丢失需要重建如果全局目录结构变动项目里就会断链。技术团队用这种方式很灵活但刚上手的人不建议一上来就这么搞。3.3 第三步迁移后怎么验证真的生效了迁移不是复制完就完事必须验证全局技能真的被加载。重启 Claude Code 会话在对话里敲斜杠看菜单里有没有skills相关入口或者直接输入技能名让模型列出当前可用技能。不同版本入口名称可能有差异以实际帮助输出为准。更可靠的方法是触发式测试。比如你迁移的是commit-message技能在项目里先做点改动然后说“帮我写这次改动的提交信息”。如果模型输出的格式明显符合技能里的规范说明已经加载。如果模型回答“没有找到相关技能”就要回到目录检查路径。还有一个小技巧用调试模式看加载日志。如果版本支持启动时带调试参数比如参考claude --help里的相关选项启动后看输出里是否出现技能扫描记录。日志里会打印技能目录和扫描到的技能名常见的问题一眼就能看出来比如目录扫描失败、技能目录被忽略。这一步对排查很有用但平时不用一直开着调试模式噪音太大。4. 常见问题与排查技巧实录4.1 技能装了半天就是不触发这个问题出现频率最高我把它拆成四个小项来排查。第一目录层级错了。技能必须放在.claude/skills/技能名/SKILL.md少一层都不行。最常见的错误是多套了一层目录比如.claude/skills/commit-message/commit-message/SKILL.md模型扫描时找不到入口技能自然不触发。第二frontmatter 写得不规范。name不能有空格description不能空着整个 frontmatter 必须用---包住且要紧贴文件顶部。有些人从富文本编辑器里复制内容YAML 区块里夹带了不可见字符也会导致解析失败。第三description 写得太宽泛或太窄。太宽泛会让模型每次都想用产生大量无效调用太窄则几乎触发不了。比较合适的描述是“当用户要求做 X 时使用输入是 Y输出是 Z可能包含 A、B、C 等场景”。第四会话没重启。Skills 通常在会话启动时扫描旧会话里新增的技能不会立刻出现。我见过有人改完技能不重启就直接追问“为什么没反应”其实重启一下就好。4.2 同名技能冲突、误触发怎么办当全局和项目级存在同名技能时实际作用哪个技能不同版本策略可能不一样依赖这个特性本身就是风险。我的建议是给技能起有区分度的名字比如项目级的叫backend-review全局的叫code-review从名字上就不要冲突。误触发是另一个常见问题。description写得太泛比如“对代码进行审查”模型很可能在用户只是闲聊“这段代码怎么样”的时候就调用了技能白白消耗上下文和 token。解决方法是把 description 写得场景化、任务化加上明确的触发条件比如“当用户要求对未提交的 diff 做完整 code review并输出按严重程度分类的问题清单时使用”。如果多个技能 description 相似模型还可能判断错误、选错技能。解决办法是把技能边界划清楚一个技能只管一类事不要做一个“全能型”技能。技能之间可以通过在 description 里写“这是唯一负责处理提交信息生成的技能其他技能不需要覆盖这个任务”来互相避让。4.3 团队协作时项目级和全局配置怎么配合团队场景下项目级技能尽量提交到仓库任何人克隆后都有同一份技能基线。全局技能不要提交到仓库它属于个人工作流别人机器上不一定需要。这样配合的好处是团队规范跟着项目走个人效率跟着自己走互不干扰。如果你发现某个人技能团队里所有人都想用正确做法不是让每个人复制一遍而是把它从全局收编进项目技能放仓库里统一维护。比如我一开始把“前端可访问性检查”放在全局后来发现前后端同事都要用就迁回项目.claude/skills/并提交大家更新代码后就有最新版本。还要注意.gitignore问题。如果只想保留部分技能在仓库可以用.gitignore排除某些个人技能但这样做团队其他人会困惑不如规则简单一点.claude/skills/全部入库个人技能一律进全局目录。长久下来心智负担最小。5. 让技能更耐用的几个长期习惯5.1 命名和描述一开始就定好规则给技能命名时我建议用统一前缀。个人通用技能用personal-或直接名词团队技能用项目缩写比如xx-h5-review。这种做法在技能数量超过十个之后优势非常明显查看目录、看日志、排查冲突时一眼就能判断技能归属。description 的写法也要形成自己的模板。我常用的结构是技能目标 触发场景 输入输出 示例提示。举例“根据项目提交规范生成 git commit message。当用户要求写提交信息、commit、git 提交说明时使用。输入为 git diff 或暂存区内容输出为符合规范的多行提交信息。”每次写新技能都套这个模板后面维护成本会低很多。5.2 技能保持小而专配合脚本和资源文件我最早写技能时犯过贪全的毛病把一个“代码审查”技能写了两千字从风格、安全、性能到测试覆盖全塞进去。结果模型加载后上下文占用大实际执行时还会遗漏后半段。后来我把它拆成“diff 审查”“安全审查”“性能审查”三个技能每个只管一类事效果反而好得多。技能的正文尽量精炼大段参考材料放到references/子目录需要时才让模型读取。会写脚本的话把可自动化部分放到scripts/里比如生成报告、统计 diff 行数、格式化输出让技能变成一个“说明 工具”的组合而不是纯文字指令。脚本注意写相对路径引用资源不要写死绝对路径否则换机器就废了。5.3 我的经验先项目级验证再决定是否转全局我在实际使用中的习惯是新技能先在项目级跑一阵验证 description 触发时机对不对、正文步骤够不够清晰、输出格式是否符合预期。确认没有问题了再决定是否升到全局。这样即使技能有问题影响范围也被限制在单个项目不会污染你所有项目的工作流。从项目级切到全局我一般用复制而不是剪切因为有些技能虽然是个人习惯但项目历史会话里可能还在用它直接移走会留下坑。全局技能每隔一段时间我会做一次清理没用过的、被新技能替代的、description 明显过时的直接删掉或归档。技能这东西数量不是越多越好能让模型准确找到的那个才是真正有价值的。