企业官网建设流程全解析

如果你已经在用 Claude Code 写代码，大概率遇到过这样的场景：看别人分享了一套很顺手的 frontend skills，克隆到本地之后愣了几秒——这一步该放到哪？是项目根目录的.claude下，还是用户主目录的.claude下？我最早入坑的时候也在这卡过，后来把项目级 skills 切到全局之后，才算真正把这东西用明白。这篇就聊清楚：skills 怎么装，项目级和全局级到底什么区别，以及怎么从项目级切到全局。

先说结论：Claude Code 的 skills 本质上是一份给 Claude 看的"岗位说明书"，不是传统意义上的插件。它通过SKILL.md文件告诉 Claude"你什么时候该用我、用了该怎么做"。装的位置决定了它的作用范围：放在项目目录里就是项目级，放到用户主目录里就是全局。很多教程只教你怎么写SKILL.md，却很少讲这层"放哪"的学问，但恰恰是这一步决定了你的 skills 是跟着仓库走、还是跟着你这个人走。

1. Skills 不是插件，是给 Claude 的"岗位说明书"

1.1 为什么 Claude Code 需要 Skills

Claude Code 本身是一个很通用的编码 agent，你给它一个任务，它能自己读代码、改文件、跑命令。但"通用"意味着"不专精"：它知道所有编程语言，但它不了解你的团队规范、你的项目结构、你的代码风格偏好。Skills 就是用来补这层信息的。

打个比方：Claude Code 像一个刚入职的全能实习生，什么都会一点，但不知道你公司的代码规范是什么样的。Skills 相当于是你递给他的几本工作手册——"这是我们前端组的要求，你照着这个来"；"这是部署流程，你按这个步骤走"；"这是日志格式规范，你输出的时候遵守"。这样一来，Claude 就不再是"什么都懂的门外汉"，而是"懂你们团队规矩的自己人"。

1.2 SKILL.md 的组成和触发逻辑

一个标准的 skill 是一个目录，目录里必须有一个SKILL.md，旁边可以跟着脚本、模板、参考文档。SKILL.md的结构是 YAML frontmatter 加 Markdown 正文，最关键的字段是name和description：

--- name: frontend-review description: 审查前端代码时使用。检查 React/Vue 组件结构、样式规范、可访问性与基础性能问题。当用户要求 review 前端代码、检查组件质量或进行代码评审时触发。 --- # Frontend Review ## 执行步骤 1. 梳理被审查文件的组件树，确认数据流方向 2. 检查样式方案是否与项目规范一致 3. 检查可访问性：img 是否有 alt、按钮是否有可读文本 4. 输出问题清单，按严重程度排序

Claude 读取这个文件的逻辑很直接：每次对话开始或任务变化时，它会把当前可用的 skills 的name和description放进上下文，当作"候选工具清单"。当你的任务描述和某个 skill 的description匹配度高时，它就会加载这个 skill 的完整正文，按照里面的步骤执行。

所以description写得好不好，直接决定了 skill 会不会被触发。写得越具体、越贴近用户真实说法，命中率越高。你要是只写一句"用于前端审查"，Claude 很可能在你需要它的时候想不起来用。

1.3 Skills、MCP、Subagent 到底什么关系

很多人第一次接触 skills 时会把它们和 MCP（Model Context Protocol）搞混。我用一张表把三者的区别捋清楚：

实际使用中，三者的边界没有那么死。复杂场景经常是 skills 里写清楚流程，流程中用 MCP 工具查数据，遇到大块独立任务再拆给 subagent。但如果你只是想给 Claude 注入"某个领域的做事方法"，那 skills 绝对是性价比最高的切入点，不需要写服务、不需要管协议，一个目录一个文件就搞定。

2. 装之前先搞清楚两个 .claude 目录

2.1 环境检查：确认 Claude Code 可用

动手装 skills 之前，先确认 Claude Code 已经正确安装。终端里执行：

claude --version

能正常输出版本号就说明环境没问题。如果提示找不到命令，说明 CLI 还没装好或者没进入当前 shell 的 PATH。

装好的前提下，你会发现系统里有几个.claude相关的目录，容易混淆的就两个：

• 项目根目录下的.claude/：当前仓库专属。
• 用户主目录下的~/.claude/：当前操作系统用户专属。

Skills 就放在这两个目录下的skills/子目录里。目录结构的完整形态是这样的：

项目根目录/ ├── .claude/ │ ├── skills/ │ │ └── frontend-review/ │ │ ├── SKILL.md │ │ └── rules/ │ │ └── style-guide.md │ └── settings.json └── ... ~/.claude/ ├── skills/ │ └── commit-message/ │ ├── SKILL.md │ └── templates/ │ └── conventional.md └── settings.json

2.2 项目级和全局级到底差在哪

一句话说明：项目级 skills 跟着仓库走，任何 clone 这个仓库的人都会看到；全局 skills 跟着用户走，你在任何项目里都能看到。

这两个级别都不难理解，难的是判断"该放哪"。我的判断标准很简单：

• 项目级：和当前仓库强相关的东西。比如"本项目的前端规范""本项目的部署流程""本项目数据模型的增删改查约定"。这些内容对别的项目没有意义，甚至可能有冲突，放进全局反而是污染。
• 全局级：和生产工具、个人习惯、通用能力相关的东西。比如"如何写规范的 conventional commit"、"如何生成项目 README"、"代码 review 检查清单"。这些在任何项目里都用得上，应该跟着人走。

如果你把一套通用 review skills 放进某个项目的.claude/skills/，那换下一个项目你就得再装一次；更尴尬的是，团队里其他人 clone 仓库时也会看到你的个人 review 习惯，这不一定是他们想要的。所以"通用能力放全局，项目私有放项目级"这个原则，值得刻在脑子里。

2.3 一个 npm 视角的类比

如果你用过 npm，这个模型其实非常好懂。npm 区分dependencies（项目依赖）和全局包（npm install -g）：项目依赖装在某个仓库的node_modules里，随着package.json被团队共享；全局包装在系统目录里，是"我这台机器上有、你未必有"的东西。卸载全局包用npm uninstall -g xxx，卸载项目依赖则在项目目录里执行npm uninstall xxx。

Claude Code 的 skills 两级机制几乎是同一个思路。项目级可以类比为项目依赖，进仓库、随团队走；全局级可以类比为全局包，是个人环境的一部分。只是 npm 全局包需要用-g参数显式安装，Claude Code 的全局 skills 则是把目录放到~/.claude/skills/下，更接近"文件即安装"。

理解了这层类比之后，很多操作就顺理成章了：项目装了一半想共享，其实就是把文件从项目级目录复制到全局目录；想给某个项目临时禁用一个全局 skill，用项目级同名 skill 覆盖就行。后面我会细讲。

3. 项目级安装：从目录到验证的完整链路

3.1 最朴素可靠的装法：手动放目录

虽然现在有不少第三方工具能帮你管理 skills，但最可靠、最不会出问题的永远是手动放置，因为你完全掌控目录结构和最终状态。

假设我想给当前项目装一个 frontend-review skill：

# 1. 进入项目根目录 cd ~/work/my-frontend-project # 2. 创建 skill 目录 mkdir -p .claude/skills/frontend-review # 3. 把 SKILL.md 放进去 cp ~/Downloads/frontend-review/SKILL.md .claude/skills/frontend-review/

如果你的 skill 还带辅助文件（模板、脚本、参考文档），一样复制进去：

cp -r ~/Downloads/frontend-review/rules .claude/skills/frontend-review/

这里有个很容易踩的坑：SKILL.md必须直接放在 skill 目录的根上，不能多套一层子目录。也就是说下面这种结构是无效的：

.claude/skills/ └── frontend-review/ └── frontend-review/ └── SKILL.md

Claude 扫描时只认skills/<skill-name>/SKILL.md这个固定层级，套多了它就找不到。我第一次装别人的 skill 时就犯过这个错，克隆下来的压缩包自带一层目录，我没解压处理直接丢进去，结果/skills里什么都看不见。

3.2 从零写一个前端 review skill

如果你没找到现成的，自己写一个也不难。我以"前端代码 review"为例，给你一份可以直接用的骨架：

--- name: frontend-review description: 执行前端代码审查。当用户要求 review 前端代码、检查 React/Vue 组件、评估代码质量或进行代码评审时触发。如果任务涉及修改而非审查，不要触发本 skill。 --- # Frontend Code Review ## 审查维度 1. **组件结构**：组件是否过大（超过 200 行）？是否拆分为职责清晰的小组件？ 2. **样式规范**：是否使用项目统一的样式方案？是否存在内联样式滥用？ 3. **可访问性**：img 是否有 alt？交互元素是否有键盘可访问性？色彩对比是否达标？ 4. **性能**：是否存在不必要的重渲染？列表项是否有稳定 key？ 5. **可维护性**：命名是否清晰？是否存在魔法数字？是否有重复逻辑？ ## 输出格式 按以下格式输出审查结果： - 严重问题（必须修复） - 建议改进（推荐修复） - 可选优化（有时间再处理） 每个问题附上文件路径、行号、问题描述和修改建议。

有几个写的时候需要留意的细节：

• name用连字符小写命名，不要用空格和中文。
• description里最好写明"什么情况下不要触发"，这能显著降低误触率。比如上面写的"如果任务涉及修改而非审查，不要触发"，就是因为审查和修改完全是两件事，Claude 很容易混淆。
• 正文里的步骤要写得像"标准作业程序"，而不是泛泛的原则。你写得越具体，Claude 的执行结果越稳定。

3.3 验证：怎么看 skills 有没有真正生效

装完之后别急着让 Claude 干活，先在会话里输入/skills。这会列出当前会话可见的所有 skills，带路径说明是从哪个级别加载的。如果你在/skills里看到了frontend-review，说明装载成功。

更进一步的验证是实际触发一次。开一个新的对话，输入类似"帮我 review 一下 src/App.tsx 这个组件"，正常情况下 Claude 会回答"我会按 frontend-review 的流程来检查"，然后按照你定义的审查维度逐项输出。如果它只是泛泛地看了一眼就给出评论，说明 skill 的 description 写得不够精确，回去优化它。

我在这一步还有个小经验：验证时故意用口语化指令，比如"帮我瞅瞅这个组件有没有问题"，而不是规规矩矩说"请执行代码审查"。因为用户日常说话往往不那么正式，如果 skill 只对"官方说法"有反应，那实际使用率会大打折扣。description 里建议把用户可能的多种说法都覆盖进去。

4. 从项目级切到全局：三条路线怎么选

4.1 为什么需要把项目级切到全局

最常见的场景是：你在项目 A 里精心配了一套 skills，用了两周发现效果不错，开项目 B 的时候希望也能直接用。这时候两个选择：要么把文件再复制一遍到项目 B，要么直接把 skills 提为全局，让所有项目共享。

我的建议是：只要这套 skills 不是和项目 A 深度绑定的，一律提全局。因为 skills 是有迭代成本的——你改了新版，项目 B 里的旧版不会自动同步，时间一长就出现"不同项目行为不一致"的问题。提到全局之后，你只维护~/.claude/skills/这一份就够。

具体操作有三条路线，我逐个说清楚利弊。

4.2 路线一：直接复制，项目保留副本

# 把项目里所有 skills 复制到全局 cp -r .claude/skills/* ~/.claude/skills/ # 如果只想复制某一个 cp -r .claude/skills/frontend-review ~/.claude/skills/

复制是信息最安全的方式：项目里的那份还在，万一全局出了问题可以回退。缺点也很明显：以后你改了全局版本，项目里的旧版本就和新版本脱节了。如果你希望各个项目表现一致，下次记得回到项目里同步，或者干脆这么做之前先想清楚。

我的判断标准是：如果这套 skills 本身就是全局共享的，复制之后建议把项目里那份删掉，避免下次打开项目时出现重复加载的感觉（同一套东西有两份，版本还不一样）。

4.3 路线二：移动，彻底迁移

mv .claude/skills/frontend-review ~/.claude/skills/

移动的本质是"剪贴"，源目录里不再保留。好处是一份文件、一个真相源，以后只改全局那份就行；坏处是项目 clone 给别人时，这套 skills 不会跟着走，毕竟它已经属于个人环境了。

这条路线最适合"个人开发、多项目复用"的工作流：skills 是"我的工具"，不属于任何单一仓库。

4.4 路线三：软链接，集中维护分散展现（我的首选）

如果你在项目里既想保留这层目录（比如团队协作时其他人需要看到），又不想真的维护两份，可以用软链接：

# 全局放真实文件 mkdir -p ~/.claude/skills/frontend-review # 真实文件放到全局 vim ~/.claude/skills/frontend-review/SKILL.md # 项目里建立软链接 ln -s ~/.claude/skills/frontend-review .claude/skills/frontend-review

这样项目里的.claude/skills/frontend-review只是全局目录的一个入口，你改全局文件，项目里立刻生效。团队其他人 clone 后看到目录存在，但如果不做同样的链接动作，他们本地不会有内容——这其实是可控的，因为链接本身一般不会提交进 git。

我自己现在就是用这种方式管理大部分通用 skills。唯一的坑是：如果哪天你把整个项目目录打包发给别人，软链接解压后可能失效，对方会看到一个空的 skill 目录。所以正式交付仓库时，要么把真实文件放进去，要么在 README 里写清楚"需要执行 ln 命令建立链接"。

4.5 切换后的验证清单

不管你选哪条路线，切完之后建议按这套清单检查一遍：

1. 在全局目录下执行ls ~/.claude/skills/，确认目录结构正确。
2. 随便进入一个新项目，打开 Claude Code 会话，输入/skills，确认这些 skills 能跨项目看到。
3. 实际触发一次，确认行为和项目级时一致。
4. 如果选择了复制或移动，顺手把项目.claude/skills/下多余的文件清理干净，避免以后产生混淆。

5. 切到全局之后：冲突、更新与清理

5.1 同名冲突：项目级优先还是全局优先

切到全局之后，迟早会遇到一个问题：某个项目的.claude/skills/里有一个frontend-review，全局~/.claude/skills/里也有一个frontend-review，两个内容还不一样。Claude 加载时优先用哪一个？

根据 Claude Code 的约定，项目级 skills 会覆盖全局同名 skills。理由是项目级通常代表了这个仓库的特殊约定，比个人通用习惯更具体，所以优先。

这个设计平时很省心，但也是隐藏的问题源：你在全局改进了一套通用 review 规范，某项目里躺着一份两年前的旧版项目级 review，Claude 在该项目里表现的还是旧版行为。排查时很难想到根因是"那里有份旧的项目级文件"。

我的建议是：不做特殊处理的情况下，项目根目录的.claude/skills/里只放真正项目相关的东西，别图方便把通用 skills 都复制进去。宁可让 Claude 加载慢一点，也不要让多份同名文件互相打架。

5.2 更新迭代：别让全局 skills 变成僵尸版本

全局 skills 最大的风险不是装不上，而是"装了再也不更新"。比如你在网上看到一篇很好的 skill 分享，复制进来之后，原作者的仓库迭代了好几个版本，你本地还躺着初版。

解决思路分两种：

一种是手动更新：定期去~/.claude/skills/下检查，如果某个 skill 来自公开仓库，直接把仓库 clone 到临时目录再覆盖过去。另一种是自建统一管理：如果你攒的 skills 多了，建议把所有 skill 源文件放到一个独立 git 仓库里，比如my-claude-skills/，然后用脚本一键同步到~/.claude/skills/。脚本代码不复杂，核心就是：

#!/usr/bin/env bash # 同步脚本：把仓库里的技能同步到全局目录 set -euo pipefail for skill_dir in my-claude-skills/*/; do skill_name="$(basename "$skill_dir")" cp -r "$skill_dir" "$HOME/.claude/skills/$skill_name" done echo "Synced $(ls -d my-claude-skills/*/ | wc -l) skills to ~/.claude/skills/"

用 git 管理的好处是你能看到每个 skill 的变更历史，哪天改出问题了可以 diff 回滚，这比无版本管理的复制要职业得多。

5.3 清理：删掉不用的 skill

时间一长，全局目录里总会有一些装完就再也没用过的 skills。判断标准很简单：某个 skill 已经超过一两个月没触发过，或者你看到名字都想不起来是干嘛的，那就删。删除操作：

rm -rf ~/.claude/skills/obsolete-skill

删除前建议先整个压缩包备份一次：

tar -czf claude-skills-backup-$(date +%Y%m%d).tar.gz ~/.claude/skills

这样删错了也能恢复。我在清理时还会顺手做一件事：把每个保留下来的 skill 的 description 重新读一遍，看看有没有过时的工具名、失效的路径。因为很多 skill 会引用绝对路径的脚本，路径一变，skill 就废了，但 Claude 不会主动告诉你"这个 skill 引用的文件不存在"。

6. 值得装的 skills 方向与自建注意事项

6.1 优先推荐的方向

结合我实际使用的经验，给几个最容易见效的方向：

前端开发相关。包括组件审查、样式规范检查、可访问性审计等。前端项目规范通常很琐碎，正好是 Claude 容易"凭感觉发挥"的地方，有个 skill 做约束，输出质量立刻不一样。

Git 提交信息规范。让 Claude 按 Conventional Commits 规范帮你生成 commit message。这属于典型的"任何项目都用得上"的全局 skill，值得第一时间装上。

代码 review 流程。定义审查维度、输出格式、严重程度分级，适合团队统一 code review 口径。但注意，这类 skill 如果涉及团队特定规范，更适合放项目级，通用审查放全局。

文档生成。根据代码生成 README、更新 API 文档、整理 CHANGELOG，都属于重复性高、需要固定格式的活，交给 skill 做最稳。

测试生成。让 Claude 按你的测试框架约定自动补测试，可以定义测试文件命名、mock 方式、断言风格。这个需要对团队规范做定制，一般放项目级。

6.2 自建 skill 的四个注意点

看了很多"如何写 skill"的教程，但实际踩过坑之后，我觉得有四点是真正决定成败的：

第一，description 要写"用户会怎么说"，而不是"你想让 Claude 做什么"。用户说"帮我看看这个函数有没有问题"，不会说"请对该函数执行静态代码质量评估"。你写的时候多想想真实对话里的措辞，触发率能提高一大截。

第二，步骤要可执行，不要写空话。"分析代码质量"和"检查是否存在重复逻辑、命名是否清晰、是否有魔法数字、函数是否超过 50 行"是完全不同的两段描述，后者的执行结果稳定得多。

第三，善用allowed-tools字段约束行为。如果 skill 内部需要读取某个项目目录或运行特定脚本，可以在 frontmatter 里声明允许的工具，避免 Claude 因为权限不足而中途放弃。但要克制，尽量遵循最小权限原则，别把所有工具都放开。

第四，skill 不是越详细越好。一个 SKILL.md 写了上千行，Claude 在匹配时反而会犹豫——它需要判断哪些内容适用。理想的长度是：能讲清楚触发条件和执行步骤，剩下细节放到附加文件里，让 Claude 按需加载。

收尾再补两个实操细节

作为补充，最后说两个我在实际操作中发现的小细节，都是文档里不太会写的。

第一个是关于/skills命令的。有时候你装好了一个 skill，重启会话后/skills里却没有。别急着怀疑目录结构，先看看是不是缓存问题。Claude Code 对 skills 的索引并不是每次会话都全量刷新，有缓存机制。遇到这种情况，完全退出当前会话重新打开，基本都能解决。实在不行就检查一下文件权限，确保~/.claude/skills/和项目.claude/skills/的目录权限可读。

第二个是关于"项目级切到全局"的心理包袱。我见过不少朋友觉得把项目级 skills 提全局，会污染自己所有的项目。但实际上，只要你按照"通用能力放全局、项目专属留本地"的原则规划，全局目录再乱也乱不到哪去。真正让全局目录失控的，从来不是切过来的 skill 太多，而是那些"当时觉得有用、后来再没碰过"的僵尸 skill。所以定期清理、定期更新，比纠结"该不该切全局"重要得多。

从第一次手动往.claude/skills/里放文件，到现在用软链接统一管理大部分通用技能，我对 skills 的态度也变了不少：它不只是"给 Claude 加技能"，更像是在给自己沉淀一套可复用的工作方法。所有踩过的坑都会变成下一套 skill 里的规则，而规则越多，Claude 的表现就越接近你理想中的那个"靠谱同事"。