Claude Code 用久了就会发现决定它上限的往往不是模型本身而是你往它身上挂了哪些 Skills。别人能一条指令把 PDF 整理成结构化笔记你还在手敲文档别人一句话让它在某个代码库里做规范检查你要花半小时描述上下文。差距通常就藏在.claude/skills这个目录里。这篇文章只围绕一个问题展开Skills 到底怎么装以及当你把某个技能从一个项目里挪到全局时该注意些什么。适合两类读者一类是刚接触 Claude Code、想给它加技能的新手另一类是已经在项目级装了一堆技能、想统一迁到全局管理的进阶用户。1. Skills 的两层配置体系先搞清楚项目级和全局到底差在哪1.1 一个 Skill 的物理结构目录、SKILL.md 与依赖资源一个 Skill 本质上就是存放在特定目录下的一整套指令包。标准结构长这样skills/ └── pdf-engine/ ├── SKILL.md ├── scripts/ │ └── extract.py └── reference/ └── format-guide.mdSKILL.md是这个技能包的启动文件顶部有一段 YAML 元信息下面是你希望模型在调用时读到的操作说明。除了SKILL.md目录里还可以放脚本、模板、示例文件等资源模型会按照SKILL.md里的引导去按需读取这些资源。最简单的技能也可以只有一个SKILL.md把步骤全部写在里面但一旦涉及多文件、多步骤流程把资源拆出来会让技能更容易维护。1.2 项目级与全局的三个核心差异Claude Code 的配置分两层Skills 也对应两个存放位置项目级项目根目录/.claude/skills/全局~/.claude/skills/两者的核心区别在于作用范围和数据生命周期。项目级目录随代码仓库走clone 下来就能看到适合团队里的业务技能全局目录在用户主目录下跟你开了几个项目无关适合你个人平时沉淀下来的通用技能。我习惯用一个简单的判断标准这个技能绑不绑定当前项目绑定就放项目级不绑定就放全局。维度项目级 .claude/skills全局 ~/.claude/skills生效范围仅当前项目所有项目传播方式提交进 git 仓库需要手动同步或备份适合场景团队规范、业务专用、项目相关个人高频、跨项目通用更新节奏跟随代码库变更个人主动维护主要风险仓库体积噪音、密钥易被误提交换机器时容易忘多机不一致两边可以同时存在不是二选一。会话启动时Claude Code 会把两边的目录合并扫描项目级通常会优先被加载。这个优先级细节到后面迁移章节会专门讲。1.3 别把 Slash Commands 和 Skills 混为一谈跟 Skills 长得有点像的是 Slash Commands它们也按目录组织都能做成斜杠触发。但两者定位明显不同Command 是一个轻量 prompt 模板适合保存一段固定指令、将来重复调用Skill 是带资源文件的结构化技能包适合要加载多个文件、执行多步骤任务的场景。如果你手上只是几段提示词先考虑 Command一旦涉及脚本、文档模板、多文件流程就应该用 Skill。装的时候要注意别把文件放错目录否则在/列表里什么都看不到。2. 装 Skill 前的环境体检版本、目录位置和常见误解2.1 确认当前版本和更新方式在装任何东西之前先确认手头的 Claude Code 能识别 Skills。旧版本可能只支持 commands 和 plugins对新的技能目录无感。一条命令查版本claude --version如果版本偏老先跑客户端自带的更新命令不同客户端的更新方式略有差异以本机帮助提示为准。我碰到过不少装完技能完全没反应的求助一问版本对方用的是半年前的旧版那问题根本不在技能本身而在客户端版本太老。技能加载机制是跟随客户端版本的遇到新下载的技能包完全没反应第一反应应该是查版本而不是反复重装。2.2 预检目标目录是否就绪然后确认目标目录存在ls -la .claude/skills # 项目级 ls -la ~/.claude/skills # 全局不存在就创建mkdir -p .claude/skills mkdir -p ~/.claude/skills很多新手在这里踩的第一个坑是把技能目录建成了~/.claude/skills/xxx/SKILL.md但实际上多套了一层目录或者把SKILL.md直接扔在了 skills 目录的根上。正确做法是 skills 下面每一层是一个技能目录技能目录里才是SKILL.md。Windows 下全局目录通常在用户目录里路径类似%USERPROFILE%\.claude\skills。如果你用的终端工具或系统用户不一致HOME环境变量可能指向不同位置最容易出现明明装了为什么没有的诡异现象。2.3 先确认技能包的来源和格式接着检查拿到的技能包长什么样。正规技能包应该是一个目录里面含有SKILL.md。如果你只拿到一段 Markdown 文本、一个脚本或一个 zip 压缩包都需要先解压并整理成标准结构再放进目录。我会在会话里直接问 Claude Code当前加载了哪些 skills它通常会列出已识别的技能名。如果列表里没有你刚放的目录说明格式或路径有问题不必等真正用的时候才发现。3. 项目级 Skills 的安装全流程拷贝与链接两条路3.1 从远程仓库拉取技能包拿到技能包的方式主要有三种从远程仓库 clone 或下载压缩包复制别人分享的目录自己新建目录写SKILL.md。以从远程仓库拉取为例git clone https://example.com/some-repo.git /tmp/some-repo然后进去看看技能目录的结构ls /tmp/some-repo/skills如果拿到的是 zip就解压之后找到含SKILL.md的那一层目录。这里最容易出问题的是层级搞不清有的仓库把技能直接放在根目录有的放在skills/子目录里还有的压缩包外层再包了一层文件夹。统一原则只有一个必须找到能直接看到SKILL.md的那一层这一层才是技能目录本身。3.2 拷入项目级目录接下来把技能目录完整拷贝到项目里的.claude/skillscp -r /tmp/some-repo/skills/pdf-engine .claude/skills/ ls .claude/skills/pdf-engine注意这里用的是-r因为技能目录里通常有脚本、参考文档等子文件。只拷贝SKILL.md而丢掉同目录资源是技能装上以后运行失败的最常见原因。我自己第一次装某个文档处理技能时就图省事只复制了一个主文件结果模型能识别技能但一到真正调用就报找不到脚本排查半天才发现是资源目录没跟上。3.3 用符号链接做原地引用如果你不想把技能物理复制进项目也可以对一个技能仓库做符号链接ln -s /tmp/some-repo/skills/pdf-engine .claude/skills/pdf-engine好处是原仓库更新后项目里立即生效坏处是这个项目就依赖了仓库的本地路径别人 clone 项目后不会自动得到这个技能。所以链接方式只适合个人环境或者适合把技能仓库固定放在某个稳定路径的情况。用链接之前先想清楚一个问题这个技能要不要进 git 仓库共享给同事要共享就不要用链接只是自己本机用链接反而省事。3.4 装完如何验证生效装完不需要重启机器新开一个 Claude Code 会话即可。在对话框里输入/会看到可用的命令列表里面应该出现技能目录名。也可以直接发起一个有明确意图的任务比如使用 pdf-engine 技能解析这份 PDF 并输出摘要看它能否按预期触发。如果/列表里没出现大概率是目录层级不对或技能格式不受当前版本支持。可以再跑一次目录结构检查find .claude/skills -name SKILL.md这个命令会列出所有技能包的主文件每一行对应的父目录都应该是一个技能包目录。如果 find 能扫到但客户端列表里没有就回到版本和格式检查。4. 从项目级切到全局迁移实操与优先级坑4.1 为什么需要切到全局迁移这个动作背后通常对应一个真实场景某个技能在 A 项目里打磨得很好换到 B 项目、C 项目也想用不想每个项目重新复制一遍。又或者是团队项目里放了一批与业务无关的通用技能比如文档转换、PDF 解析、代码审查模板想把这些东西收拢回个人环境让项目仓库更干净。判断标准就一句话这个技能和具体项目绑定吗业务数据接口、专属代码规范、特定框架的脚手架模板这些跟项目绑定留在项目级通用技能和项目无关迁到全局。4.2 迁移步骤复制、清理、复验我一直建议的顺序是先复制后删除避免中途出问题把原技能弄丢。完整五步确认项目级技能目录名ls .claude/skills复制到全局cp -r .claude/skills/pdf-engine ~/.claude/skills/验证全局目录结构ls ~/.claude/skills/pdf-engine/SKILL.md删除项目级副本rm -rf .claude/skills/pdf-engine如果项目在用 git记得提交删除操作git rm -r .claude/skills/pdf-engine如果只是想试试效果、不想动原目录可以先跳过第 4 步在全局放一份验证后再删。这样最稳。我通常还会在迁移后立刻看一次两边的目录列表确认源和目标都没有残留迷之文件ls -la .claude/skills ls -la ~/.claude/skills4.3 同名冲突时谁说了算这里要特别提醒如果项目级和全局各有一个同名技能实测下来项目级目录的优先级更高也就是说在当前项目里会触发项目级那个版本全局的同名版本会被暂时忽略。这意味着你从项目级搬到全局时如果项目级旧副本没删你看到的可能还是旧行为。这个设计其实合理项目级更贴近当前上下文适合做项目专属定制。但迁移时它很容易坑人——明明更新了全局技能回到原来的项目里测怎么都不生效。处理方式就一条迁移完立刻检查项目级目录里是否还有同名残留有就清掉再重新开一个会话验证。4.4 用脚本管理全局技能集技能多起来以后手工一个个cp不是办法。我的做法是把全局技能统一放在一个独立目录里用一个同步脚本批量更新rsync -av --delete ~/dev/my-skills/ ~/.claude/skills/注意--delete会删除目标端多余目录相当于以源为绝对基准。这个命令适合在你有完整技能库时使用如果只想添加某个技能不建议带--delete。也可以在技能仓库里维护一个安装脚本每次 pull 之后自动同步这样就不会出现装了十几个技能过三个月自己都记不清哪些在用的失控状态。5. Skill 不生效时的定位链路五步排查法5.1 从入口查起先说最常见的情况对话里输入/看不到这个技能。这时从三个层面检查目录路径对不对确认它放在.claude/skills而不是.claude/commands注意大小写和拼写。目录层级对不对SKILL.md必须出现在技能目录的直接子层不能多套一层不能直接躺在 skills 根目录。当前会话有没有重新加载客户端通常是在会话启动时扫描技能目录的如果你放技能时终端一直开着旧会话可能没扫到新开一个会话再试。也可以在会话里直接问现在加载了哪些 skills让它自己列出来。这一步能快速区分问题是出现在加载阶段还是出现在后续的内容解析阶段。5.2 检查 frontmatter 与描述写法如果技能出现在列表里但正常描述任务时它没有被触发多半是SKILL.md的元信息写得不好。一个常见失败 pattern 是 description 过于笼统比如PDF 处理技能。你觉得很清楚了但对模型来说不够它没法判断当前用户的这个任务是否和这个技能匹配。更好的写法是描述触发场景--- name: pdf-engine description: 当用户提到 PDF、扫描件、电子书或需要从 PDF 里提取文字、生成摘要、转为 Markdown 时使用。 ---关键差别在于写什么时候用而不是它是什么。另外 frontmatter 必须保证 YAML 格式正确name和description字段都齐全闭合符号完整。如果 frontmatter 解析失败整个技能会被静默忽略这是最隐蔽的一类问题。5.3 检查资源路径与执行权限技能能被调用、却在执行中途报错最常见的三类原因资源文件没跟着走SKILL.md里写的是scripts/extract.py但你只拷贝了SKILL.mdscripts目录丢了。复制技能包时应该整目录操作。脚本没有执行权限Linux/macOS 下脚本默认可能不可执行需要手动加权限chmod x scripts/*.py权限不对时模型会提示 Permission denied。绝对路径问题技能包在 A 机器上写死了/tmp/some-repo/...换到别处就失效。好的技能包内部引用应该用相对路径并且以SKILL.md所在目录为基准。5.4 日志与 debug 定位上面几层都查完还没结果就打开日志看错误。Claude Code 的日志一般在~/.claude/logs或项目下的.claude/logs里按日期命名。查日志时重点看两类信息技能目录扫描相关的错误以及 YAML 解析报错。如果客户端支持 debug 模式可以开 debug 重跑一次把输出和日志放在一起对照。多数情况下问题要么是路径残留要么是格式问题真的需要重装的情况很少。重装是最后的办法而且重装前先备份现有技能目录别把写了一半的SKILL.md覆盖掉。6. 用下来的选型建议与维护习惯6.1 该进全局的技能该满足什么条件我对全局技能的要求是高频、跨项目、低定制、小而稳。全局装十几个技能没问题但从模型匹配效果来看技能越多description 之间越容易互相干扰。原本该被触发的技能可能因为另一个描述写得更宽泛而抢先命中。所以我会定期做清理把长时间没被触发的技能移到仓库的 archive 目录只在需要时手动放回。高频跨项目的好例子包括文档转换、PDF 处理、Markdown 排版检查、代码风格审查。而业务相关的技能比如某个系统专属的数据接口说明留在项目级更合理。6.2 团队协作里项目级 skills 的版本控制如果团队想共享技能最推荐的做法是把技能放到项目仓库的.claude/skills下直接提交。这样有几个好处技能跟随代码版本走改技能像改代码一样有历史记录新成员 clone 项目后技能自动就位不需要额外配置。但也要注意几条约束技能目录体积不要太大尽量不要提交样例 PDF、模型文件、大二进制资源不要在SKILL.md或脚本里写死密钥、内部接口和本机路径在项目 README 里记录技能列表和适用场景避免后来者不知道这个技能该什么时候用技能更新时跟着常规的变更流程走会有完整记录误改也能回滚。6.3 维护技能库的日常习惯最后分享我目前的维护习惯所有个人技能集中放在一个独立的技能仓库里按文件类、代码类、流程类分类存放。每个技能内部只用相对路径引用资源SKILL.md的 description 控制在三五行以内重点写触发场景。每装一个新技能就在仓库里补一行 changelog。全局目录只是这个仓库的一个 release 副本需要迁移环境时直接 clone 仓库再同步不会出现换台电脑技能全没了的情况。这样一来技能包本身、技能版本、技能说明都归一处管理从项目级切到全局也就不是一次性的手工搬运而是一次常规的发布流程。我自己在这套流程里走通的最大感受是装技能不难难的是维护一套放之四海而皆准的技能包。从项目级切到全局本质上是一次从项目专用到通用能力的提炼它要求你把描述写得足够普适、把资源路径整理得足够健壮。每次迁移都当一次小型打磨你的技能库会越来越耐用。如果你也碰到过装了技能但没效果的怪事不妨按上面五步排查看看十之八九是目录层级或描述写法的问题。
