企业官网建设流程全解析

最近我把 Claude Code 的 Skill 管理方式彻底重构了一遍。起因很现实：手上一堆仓库，每个项目的.claude/skills里都塞了几套自己写的技能，单独看每个项目没什么问题，可一旦要改某个公共技能，比如调整代码审查规则、统一 git 提交信息格式，就得跑到每一个仓库里同步一遍。漏掉一个，换个目录工作就会发现行为完全不一致，特别影响状态。

后来我发现，这件事真的可以只用 1 个配置文件修改就解决：把 Skill 从"项目私有"提升为"全局可用"。改完之后，我进入任意一个新项目，打开/skills，之前积累的所有技能都在。这篇文章就专门拆解这个操作，包括配置文件怎么改、已有的 Skill 怎么迁移、以及实测中我会踩的一些坑。适合已经接触过 Claude Code、但还在用"项目里复制粘贴 Skill"这种方式的同学。

1. Skill 不生效的真相：项目级目录才是元凶

先说 Skill 是什么。在 Claude Code 里，Skill 是一类可以复用的指令包，通常是一个目录，里面有入口文件SKILL.md，目录里还可以带脚本、模板、知识库文本。模型在对话中会通过/skills查看有哪些可用技能，也可以根据自然语言自动匹配调用。

一个典型的 Skill 目录长这样：

conventional-commit/ ├── SKILL.md ├── rules.md └── scripts/ └── check_commit.sh

SKILL.md的开头有一段 YAML frontmatter，声明name和description，正文才是真正的指令内容。我见过很多同学把SKILL.md写成了纯 Markdown 说明，没有 frontmatter，结果技能始终加载不出来。这就是第一个容易被忽略的基础知识。

1.1 项目级和用户级 Skills 的加载差异

Claude Code 的 Skill 分成两类来源：

• 项目级：放在当前仓库的.claude/skills/下，只有进入这个仓库才会被加载。
• 用户级：放在用户主目录的~/.claude/skills/下，对所有项目生效。

按我目前的体验，项目级目录是很多人默认的选择，因为跟着仓库走、随项目提交，看起来挺方便。但问题也在这里：不同仓库之间互相看不到对方的 Skill。

打个比方：就像每个办公室自己配了一台复印机，A 办公室的机器能复印，B 办公室什么都没有。你在 A 办公室学会了怎么用复印机，但换到 B 办公室，面对的是空白墙面。

很多人第一次遇到"技能不见了"时，第一反应是重新写一份，或者把整个.claude目录复制过去。这当然能救急，但它解决的是表象，不是本质。只要 Skill 放在项目级目录里，它就天然被限制在单一项目的作用域内。复制粘贴多少次，下次新建项目还是要再复制一次。

1.2 多项目并行时，复制粘贴模式必然翻车

如果你只维护一两个项目，把 Skill 复制进项目里问题不大。但项目一多，复制粘贴模式就会出现几个很典型的症状：

1. 版本分叉：同一个 Skill 在项目 A 改了 description，项目 B 还停留在旧版。
2. 漏更：新增了技能只装进当前项目，其他项目的/skills里根本看不到。
3. 仓库噪音：.claude/skills里经常混着个人习惯，不适合提交到团队仓库。
4. 排查成本高：行为不一致的时候，你根本不知道是配置问题、版本问题还是技能根本没加载。

我踩得最深的是第二个症状。某个周末我专门优化了一套"代码审查"Skill，放进正在做的仓库里，用得挺爽。下周换到另一个项目，发现/skills里根本没有它，那一刻的挫败感相信不少人能体会。

所以问题的本质不是"Skill 没写好"，而是"我把 Skill 放在了错误的作用域里"。接下来要解决的，就是把它搬到所有项目都能看到的位置。

2. 核心操作：改 1 个全局配置文件，打通所有项目

现在说正题。我要改的这个配置文件，是用户级配置文件：~/.claude/settings.json。Claude Code 在启动时会读取这份文件，把它作为所有项目共享的公共配置基底，项目自己的配置会叠加在上面。

2.1 找到并备份配置文件

在 macOS / Linux 下，路径是~/.claude/settings.json；Windows 下通常在%USERPROFILE%\.claude\settings.json。如果你从来没改过，文件可能不存在，那直接新建一个即可，这个文件就是标准的 JSON 格式。

动手之前我建议先做一件事：如果文件已经存在，先备份一份。

cp ~/.claude/settings.json ~/.claude/settings.json.bak

这不是多余操作。JSON 写错一个逗号，Claude Code 启动时可能直接读不到配置，届时排查起来比改文件本身还费时间。备份能让你随时回滚。

2.2 在配置里声明全局 Skill 根目录

打开文件，加上一个skills配置块。以我现在使用的版本为例，写法是这样的：

{ "skills": { "roots": [ "/Users/yourname/.claude/skills" ], "autoDiscover": true } }

简单解释一下这两个字段：

• roots：一个数组，告诉 Claude Code 除了默认扫描位置之外，还要去哪些目录找 Skill。这里填的/Users/yourname/.claude/skills就是用户级技能目录。
• autoDiscover：是否在每次会话启动时自动扫描这些目录。打开以后，新项目里直接就能看到全部技能。

不同版本的 Claude Code，字段名可能略有差异。如果你打开配置后发现没有skills块，也不必慌：兜底方案就是把 Skill 直接放到默认的~/.claude/skills/目录里，这个目录本身就是用户级默认扫描路径，不需要额外配置也能生效。这里我把roots写显式路径，主要是为了照顾那些想用独立技能仓库或自定义目录的人。

2.3 为什么这一处修改能覆盖所有项目

关键在于加载顺序。Claude Code 每次打开一个项目，会先在用户级目录里找配置和技能，再叠加项目级配置。用户级配置文件里声明的roots是每个项目会话共用的，所以只要在这里指对路径，所有项目的会话都会把这个目录纳进技能列表。

也就是说，你不用再去每个项目里复制SKILL.md了。项目里可以继续保持自己的.claude/skills做个性化技能，但它不再是唯一入口。公共技能统一放在外面。

我最初担心的一个问题是：项目如果也有同名 Skill，到底听谁的？实测下来，项目级会覆盖同名用户级技能，至少在我的使用场景里是这样的。这是个很有用的特性：你想对某个全局技能做项目定制时，直接在当前项目里放一个同名版本就能覆盖，改完不污染其他项目。

改完配置文件之后，已经开着的 Claude Code 会话不会自动重新加载，需要退出重进。这个细节我一开始没注意，改完配置立刻在旧会话里敲/skills，发现列表没变，还以为是配置写错了，白折腾了十分钟。

3. 把已有 Skill 迁到全局目录的三种姿势

配置指向了全局目录，下一步就是把分散在项目里的 Skill 归拢过去。迁移有三种常见姿势，我按场景说一下怎么选。

3.1 直接复制：适合已经稳定的技能

如果你有一套 Skill 已经打磨好了，短期内不会大改，直接复制最简单：

mkdir -p ~/.claude/skills cp -r /path/to/project/.claude/skills/code-reviewer ~/.claude/skills/

复制完检查一下目录结构：

ls -la ~/.claude/skills/code-reviewer

看到SKILL.md在里面就对了。这种方式的优点是快、无依赖；缺点是以后源仓库如果改了，全局副本不会跟着变。所以复制只适合"定稿"型技能。

3.2 软链接：适合还在快速迭代的技能

如果你打算长期维护某个技能，源仓库可能还在演进，那软链接比复制更合适。在全局目录里创建一个指向原始位置的链接：

ln -s /path/to/project/.claude/skills/code-reviewer ~/.claude/skills/code-reviewer

这样全局目录里看到的是软链接，实际内容还在原仓库。以后你在原仓库里改了SKILL.md，全局立即生效，不用重复同步。

需要注意一点：软链接如果指向的仓库被移动或删除，会变成断链。检查的时候用ls -l ~/.claude/skills/，链接指向目标路径，如果目标不存在，Claude Code 加载时会静默跳过，看起来就像技能丢了。我见过有人排查了半天配置文件，最后发现只是软链接断了。

3.3 把整个全局技能目录做成 Git 仓库

如果像我一样在好几台设备之间切换，或者需要把技能共享给团队，我强烈建议把~/.claude/skills做成一个独立 Git 仓库（或者至少用子模块组织）。

cd ~/.claude/skills git init git add . git commit -m "init global skills"

之后每台机器都 clone 这个仓库，配合配置文件里的roots指向它，大家的技能库就是同一份。Git 的分支、版本回退都能用在技能管理上，谁改了 description、谁加了新技能，全部有迹可循。这个方案前期稍微麻烦一点，但长期收益很高。

跳出来看，复制适合一次性的场景，软链接适合仍在迭代的场景，Git 仓库则适合需要协作的场景。三者并不互斥：我现在的全局目录里，既有直接复制进来的稳定技能，也有几个软链接指向正在开发的技能，外层整个目录则是一个 Git 仓库。

4. 实测验证与高频踩坑记录

改完配置、迁完目录，最怕的是发现还是加载不了。我发现大部分问题都集中在SKILL.md本身和目录结构上，所以单独列一节。

4.1 验证清单：新开一个临时项目测一下

先别急着去繁忙的项目里试。找一个空的临时目录：

mkdir /tmp/skill-test cd /tmp/skill-test claude

进入会话后输入/skills，应该能看到全部新技能。如果一时想不起来命令，也可以直接在对话里说"你有哪些技能可以用"，看模型怎么回答。

建议按这个顺序排查：

1. ~/.claude/skills/下每个技能目录里都有SKILL.md。
2. settings.json是合法 JSON，没有多余逗号或注释。
3. 新开的会话确实重启了，而不是复用旧会话。
4. 技能名有没有和现有系统命令冲突。

4.2 坑一：SKILL.md 的 frontmatter 写错，静默失效

这是我见过最多的失败原因。SKILL.md开头的 YAML 块如果格式有问题，技能可能会被直接跳过，而且不报错。

一个能正常识别的 frontmatter 示例：

--- name: commit-checker description: 检查 git 提交信息是否符合规范，在用户准备提交代码时自动调用。 --- 你是一个提交信息检查助手，按下面的规则逐条检查……

常见错误是name用了大写、空格或中文，比如Commit Checker。尽量不要这么写，统一用commit-checker这种形式。description 也很重要，它决定了模型什么时候调用这个技能，写得太笼统，模型可能根本想不到用它。

4.3 坑二：目录名与技能名对不上

Claude Code 识别技能时，目录名和name字段最好保持一致。比如目录叫code-reviewer，name就别写成code_quality_checker。不一致时，有的版本能识别，但调用时容易出现路径错乱；有些版本直接找不到。我自己的习惯是目录名、name、还有 Git 仓库名全部用同一套命名，省去所有心智负担。

4.4 坑三：权限不足导致技能被忽略

如果你用软链接指向团队共享目录，注意目标目录的读权限。常见的是~/projects/shared-skills这个目录权限是700，但 Claude Code 进程用的是另一个用户，或者目标目录挂在特殊挂载点上，就会读不到。排查时可以手动执行：

cat ~/.claude/skills/<skill>/SKILL.md

如果 cat 都读不出来，问题基本就定位了。

4.5 坑四：autoDiscover 开太大，反而干扰上下文

把所有技能一次性塞进每个会话，听起来很爽，但并不是越多越好。模型每次可能在上下文里看到一大堆技能描述，既占 context，又可能让它在简单任务里犹豫选哪个。我的建议是：全局目录里放那些跨项目通用的核心技能，数量控制在 5 个以内；那些特定场景才用的东西，比如"给 Kubernetes 集群做故障演练"，更适合放在对应项目的.claude/skills里按需加载，或者靠 description 触发而不是依赖自动加载。

5. 全局 Skill 的进阶组合拳：团队协作与按需加载

做到这里，单机体验已经很顺畅了。再往下走，就是如何让这套机制在团队里真正发挥作用。

5.1 配置文件随技能库一起版本化

我见过不少团队共享了 skills 目录，却忘了共享配置文件。别人 clone 了技能库，但本地 settings.json 里的roots还是旧路径，技能自然加载不出来。

解决办法很简单：把 settings.json 的模板也放进技能仓库，或者写一个install.sh，一键把配置写入~/.claude/settings.json。我在团队里就是这么做的，新人加入时跑一次脚本，配置文件、技能目录、CLAUDE.md 全部就位，不需要手动折腾。

5.2 用全局 CLAUDE.md 把技能触发场景写清楚

配置文件只解决"技能存在"的问题，解决不了"模型什么时候想到用它"的问题。这一步要靠~/.claude/CLAUDE.md。这个文件可以理解为 Claude Code 的全局记忆，每次会话都会读。

我习惯在全局 CLAUDE.md 里写一段"技能使用约定"：

- 当用户要求检查代码规范性时，使用 code-reviewer 技能。 - 当用户要求分析 Git 提交信息风格时，使用 commit-checker 技能。 - 除非用户明确提出，否则不要主动把所有技能解释一遍。

这样模型在模糊指令下也知道该调哪个技能，而不是天马行空。这个文件配合 skills 目录，等于把"全局技能库"和"全局调用守则"放在了一起，整个系统的可用性会上升一大截。

5.3 按需加载和自动加载的平衡

最后聊一下平衡。自动加载所有全局技能听上去省心，但 Skill 的定位从来不是"常驻内存"，而是"需要时再取"。Claude Code 本身对按需加载支持得不错：模型看到 description 后，会在恰当的时候读取对应 SKILL.md。所以真正合理的配置不是把 autoDiscover 开到最大，而是：

• 全局只放核心、高频、稳定技能。
• 把每一个技能的 description 写得足够具体，讲清楚触发条件。
• 低频或重型技能留在项目级目录，或者干脆由用户手动/skill指定。

我自己现在的全局目录只有三个：代码审查、提交信息规范、项目初始化脚手架。其他技能都留在各自项目里。这个组合用了大半年，没再出现"技能找不到"或者"上下文被无关技能挤占"的情况。

给你一个真切的建议：如果你现在还在一家家复制 SKILL.md，可以先从"公共技能清单"开始整理，把两三个最常用的技能抽到全局目录，跑通后再慢慢扩大。不要一次把所有技能全塞进全局配置，否则你只会得到一堆互相干扰的东西。改配置本身五分钟，但规划哪些技能真正属于"全局"才值得花时间。我是在经历过一次技能大混乱之后才想明白这点的，希望这篇能帮你少走点弯路。