企业官网建设流程全解析

我先说个真实感受：一开始接触 Claude Code 的 Skills 功能时，我把它想复杂了，以为是什么高深的插件框架。实际用下来，它其实就是"给 AI 提前写好的工作手册"——你把自己处理某类任务的标准步骤、注意事项、输出格式整理成一个 Markdown 文件，放到指定目录里，Claude Code 遇到对应场景就会主动去翻手册、照着执行。就这么个机制，能解决很多实际问题：代码审查规范不统一、文档风格飘忽不定、重复性任务每次都要重新描述需求。

而且这里有个非常容易踩的坑：很多教程只教你怎么在项目里建.claude/skills目录，但没告诉你这套目录其实是"项目级"的——换一个项目就全失效了。如果你写过十来个 Skill 之后想把它们沉淀成自己的通用技能库，就会遇到从项目级切换到全局的问题。这篇文章不绕弯子，直接讲清楚 Skills 是什么、项目级和全局两种安装方式怎么操作、从项目级切到全局的具体办法、以及我在切换过程中踩过的坑。

1. Skills 到底是什么，值不值得装

1.1 一次搞懂 Skills 的运行机制

Skills 在 Claude Code 里的定位比较特殊。它不是独立运行的脚本，也不是常驻后台的服务，而是一份结构化的 Markdown 文档。文档里用自然语言写明：这个技能适合处理什么任务、执行时应该遵循哪些步骤、最终要产出什么格式的结果。Claude Code 会在对话过程中根据用户的请求和 Skill 的描述自动判断"当前是否适合调用某个技能"，一旦命中，它就会读取对应的 SKILL.md 全文，再结合当前项目上下文来执行。

理解这个机制的关键在于"描述触发"。也就是说，Skill 的触发并不靠用户手动输入固定命令，而更多靠 Claude 对当前任务意图的判断。比如你写了一个"代码审查"的 Skill，描述里写明"适用于检查改动文件的 bug 风险、命名规范、遗留调试代码"，那么当你让 Claude 审查代码时，它就有较大概率主动调用这个 Skill。这也是为什么很多人说"Skill 写得好不好，一半在描述写得清不清楚"。

从实用角度看，Skills 解决的核心痛点是重复劳动。比如你每次希望 Claude 生成数据库迁移脚本时都遵循特定格式，没有 Skill 的情况下你需要复制粘贴一大段规范说明；有了 Skill 之后，一句"帮我做数据库迁移"就够了，规范说明由 SKILL.md 自动补全。这种效率提升对于经常使用 Claude Code 做固定类型开发任务的场景非常明显。

提示：一个 Skill 目录内不一定只有 SKILL.md，还可以放参考文档、脚本模板、示例文件等辅助资源。Claude Code 会把整个目录视为技能的一部分，技能文档里可以引用同目录下的其他文件。

1.2 项目级和全局，到底差在哪里

接着上文的机制继续说。SKILL.md 放在.claude/skills/目录下，就只对当前项目生效；放在用户主目录的~/.claude/skills/目录下，则对你本机上的所有项目生效。这两者官方都没有给出优先级说明，但实际测试下来，查找顺序是"先项目级、后全局"。也就是说，同一个 Skill 如果两个位置都存在，项目级的版本会优先被加载。

这就要聊到两种模式各自适合什么场景了。项目级适合放那些和当前代码库强相关的技能，比如"本项目的接口文档生成规范""本项目的前端组件测试模板"，这类技能换一个项目就失去意义，放全局反而是垃圾文件。全局则适合放那些跨项目通用的技能，比如"生成符合 conventional commits 规范的提交信息""做一个不依赖具体框架的技术方案调研"，这类技能希望你在任何时候都能随时调用。

从维护角度看，项目级 Skills 更适合放进 Git 仓库，因为它们是"项目资产"的一部分，团队成员在另一个环境 clone 代码后能自动获得这些技能；全局 Skills 则是个人环境配置，通常不进仓库。这个差异直接决定了你后续切换时要考虑迁移范围：到底是只复制几个文件，还是需要同步更新团队协作约定。

2. 项目级 Skills 的完整安装过程

2.1 目录结构和 SKILL.md 的最小格式

项目级安装非常简单，核心就是建目录加写文档。首先是创建一个名为.claude/skills的目录（注意开头的点），然后在这个目录下为每个技能建立一个子目录，子目录名就是这个技能的标识。每个子目录内必须有一个名为SKILL.md的文件，这个文件名是固定的，不能随意更改。

一个最小可用的目录结构是这样的：

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

SKILL.md的内容由两部分组成：YAML 格式的 frontmatter 元信息和 Markdown 正文。frontmatter 里最核心的字段是name和description，前者是技能名称，后者是给 Claude 看的触发说明。下面是一个我实际用过的 SKILL.md 骨架：

--- name: code-review description: 审查项目代码改动，重点检查潜在 bug、未清理的调试代码、命名规范问题，以及测试覆盖遗漏点。当用户要求"帮我审查代码"或"code review"时使用。 --- # 代码审查 ## 执行步骤 1. 先查看当前分支相对主分支的变更文件列表。 2. 按文件逐项审查，重点关注： - 新增代码里是否有 console.log 等调试残留 - 命名是否清晰，禁止使用拼音缩写 - 是否有明显无用的重复逻辑 3. 输出审查报告，按严重程度分级列出问题，并给出修改建议。 ## 输出格式 使用如下格式输出： - 变更概览（文件数、增删行数） - 问题列表（按 P0/P1/P2 分级） - 修改建议

这里最关键的是description字段。很多新手会写得很随意，比如"审查代码"，结果 Claude 在对话中很难判断什么时候该触发这个技能，于是经常出现两种情况：让 Claude 做代码审查时它完全没想起这个 Skill，或者写文档时反而误触发了。我试过几次之后总结出一个规律：description里要写清楚"适用于什么任务类型"和"用户一般会怎么表述这件事"，把常见触发词都放进去。触发词不是魔法，它就相当于给 Claude 的一个提示词，命中率自然会高很多。

2.2 从零建一个技能并验证生效

建完目录和文件只是第一步，重要的是确认 Claude Code 真的认出了这个技能。我建议按下面的顺序做一次完整验证。先用命令创建项目级技能目录（以 bash 为例）：

cd /path/to/your/project mkdir -p .claude/skills/commit-helper vi .claude/skills/commit-helper/SKILL.md

然后编写 SKILL.md 内容，写完保存。接下来在项目根目录启动 Claude Code，输入/skill命令。正常情况下，你会看到一个技能列表，里面应该包含commit-helper。如果没看到，大概率是 frontmatter 格式问题，常见的有两种：name字段不能有空格，尽量使用小写字母和连字符；description字段的引号或换行处理不当会导致 YAML 解析失败。还有一种情况是目录名字和name字段不一致，虽然不太影响使用，但容易造成混淆，建议保持两者完全一致。

验证通过之后，你可以直接用自然语言测试。比如输入"帮我根据当前的改动生成规范的 commit message"，如果 Claude 开始按照 SKILL.md 里的步骤来工作，说明触发成功。如果它完全不理会技能文档，就回去检查description里的触发条件是不是写得足够具体。

注意：Claude Code 通常只在启动时扫描一次 Skills 目录。你在它运行过程中新增或修改了 SKILL.md，可能需要重启会话或重新进入项目才能生效。

3. 全局 Skills 的安装方法

3.1 全局目录在不同系统上的位置

全局 Skills 的安装逻辑和项目级几乎一样，唯一的区别是目标目录从项目内的.claude/skills换成了用户主目录下的.claude/skills。具体路径取决于操作系统：在 macOS 和 Linux 上通常是~/.claude/skills/，在 Windows 上是%USERPROFILE%\.claude\skills\。

我建议在正式安装前先用命令确认一下目录是否存在。比如在 macOS 或 Linux 上：

mkdir -p ~/.claude/skills ls -la ~/.claude/skills

后面这个命令能让我们看清楚当前全局技能目录里已经有哪些技能。如果你看到目录下已经有其他工具或插件写入的文件，不用慌，只要不覆盖同名文件就行。全局目录的目录结构规范和项目级完全一致：一个技能一个子目录，每个子目录里至少一个 SKILL.md。

3.2 手动创建和从第三方复制两种途径

全局技能的来源通常有两种：一是你完全手写自己的技能，二是从网上或者团队内部拿到别人整理好的技能包直接复制进去。手写的过程和上一节项目级安装没有本质区别，只是把目录路径换掉。第三方技能包则更关注"怎么放进来"，因为很多技能包会附带额外的脚本文件或模板目录。

假设你下载了一个名为api-doc-generator的技能包，里面除了 SKILL.md 还有template.md和scripts/两个辅助资源。正确的操作是把整个api-doc-generator目录复制到~/.claude/skills/下，而不是只复制 SKILL.md。因为 SKILL.md 里很可能引用了同目录下的模板文件，只复制主文档会导致技能执行时找不到辅助文件而报错。

复制完成后同样用/skill命令验证，只不过这时候需要在一个任意项目中测试——因为全局技能理论上对所有项目生效。如果测试项目里之前已经存在同名项目级技能，那就属于冲突场景了，这个我在下一节详细讲。

4. 核心操作：从项目级切到全局

4.1 切换前先想清楚：该切还是不该切

说句实在话，不是所有项目级 Skills 都值得切到全局。我在实际使用中给自己定了一条规则：只有那些"和具体项目无关、换了任何一个代码库都成立"的技能才往全局放。比如"生成规范 commit message""按统一格式输出代码审查结果""帮你构建一个技术方案对比表"这类，它们的行为不依赖特定项目结构，放全局能最大化复用。

反过来，那些和项目强绑定的技能，比如"为本项目的微服务生成 API 文档""按团队的接口错误码规范生成异常处理代码"，就不建议切到全局。这类技能里往往写入了项目特定的目录约定、术语表、命名规则，一旦全局化，你在其他项目触发它时，它反而会按一套完全不相关的规范来工作，制造误导。如果团队约定了非常通用的开发规范，那可以考虑把通用部分提取成一个新技能放全局，把项目特有部分留在项目级，分而治之。

另外还要考虑团队协同问题。如果技能是团队资产，项目级版本放在 Git 仓库里，新成员拉代码就能同步获取；一旦你把技能移到全局，团队其他人并不会自动拥有它。这种迁移就变成了一次"个人环境改造"，需要额外自己和团队同步。我见过只把项目级 Skill 删掉、没有同步到全局的案例，结果其他人拉取最新代码后技能直接消失，影响还挺大的。

4.2 两种切换方法：复制迁移和符号链接

确认某个技能确实适合全局化之后，有两种具体操作方式：复制迁移和符号链接。复制迁移比较好理解，就是把整个技能目录从项目级复制到全局目录，然后在项目级目录里删掉原文件。以项目.claude/skills/code-review为例：

cp -r .claude/skills/code-review ~/.claude/skills/ rm -rf .claude/skills/code-review

这种方式的优点是干净、彻底，项目里以后不再保留这套技能，也不会出现"项目级版本和全局版本不一致"的隐患。缺点是你失去了针对单个项目的定制能力。如果你在某个项目里对这个技能有特殊的补充性要求，比如"代码审查时额外检查依赖版本升级问题"，就没法直接在项目级做增量覆盖了。

另一种方式是符号链接（symlink）：把项目级目录变成指向全局目录的软链。这样做的好处是技能配置只有一处，你修改全局的文件，所有项目的同名链接立即生效。这个思路有点类似"CommonJS 里软链 node_modules"的感觉，省去了同步文件的麻烦。

提示：macOS 和 Linux 上创建软链用ln -s，例如：

cd /path/to/your/project/.claude/skills ln -s ~/.claude/skills/code-review code-review

在 Windows 上则需要用管理员权限运行终端，执行mklink /D code-review "%USERPROFILE%\.claude\skills\code-review"，路径带空格时要小心引号转义。

符号链接最大的问题在于团队协作。Git 默认是可以跟踪符号链接的，但团队成员在 Windows 和 macOS 上拉取代码后，软链指向的绝对路径不一定是同一个全局目录，经常导致链接失效。所以如果你在团队仓库里使用符号链接方式，需要提前约定好全局技能的安装方式，否则不同人的环境里技能会静默失效。

4.3 切换后的验证清单和冲突处理

无论用哪种方式切换，完成后都应该做一次完整验证，别急着关终端。我一般按下面四步走。

第一步看列表：进入项目根目录启动 Claude Code，输入/skill，确认技能列表里仍然能看到code-review。如果用了复制迁移且删除了项目级文件，列表里显示的就是全局版；如果用了软链，列表效果一样，但你看不到"来源"的区别。

第二步测触发：直接用自然语言让 Claude 执行一次这个技能，比如"帮我 code review 一下当前的改动"。这一步骤非常关键，因为复制迁移最容易出问题的点在于全局目录的 SKILL.md 内容虽然没变，但触发环境变了。如果 SKILL.md 里写了相对路径引用，从全局执行时可能找不到项目里的辅助文件。

第三步确认优先级：如果你还没有删除项目级原目录，此时项目级和全局同名技能同时存在，Claude Code 会优先使用项目级版本。换句话说，你切换到全局这件事其实并没有生效。想要验证"项目级已经被覆盖掉"，必须确保项目级目录里已经不存在同名技能。

第四步做个 Git 检查：运行git status，看.claude/skills目录里是否还有遗留文件。如果你删除或软链了项目级技能，Git 会显示对应的变更，这时候记得提交，让项目仓库保持干净状态。切到全局后，团队其他人也不会再通过仓库获得这个技能，要同步给团队成员全局技能包的更新方式。

5. 常见问题与排查技巧实录

5.1 技能列表不出现或者时有时无

这是遇到最多的一个问题。通常原因有三个：SKILL.md 的 frontmatter 写坏了、目录结构不对、Claude Code 没有重新扫描。

frontmatter 写坏的情况很经典，比如description字段里用了英文冒号配合长文本，YAML 解析直接失败。我建议写完 SKILL.md 后用任意 YAML 校验工具检查一遍，或者至少确认name和description字段下方的正文之间有一个空行。目录结构不对的情况主要是把 SKILL.md 直接放进了skills/根目录，而忘记为每个技能单独建一个子目录。Claude Code 的规范要求一级子目录下才识别技能。至于重新扫描的问题，上文已经提过，修改技能后需要重启 Claude Code 或重新进入项目目录。

5.2 项目级和全局同名冲突，到底谁赢

虽然前面已经提过"项目级优先"，但实操中很多人还是会困惑：为什么我把全局技能更新了一版，项目里调用时还是旧行为？原因就是项目级目录里仍然残留着同名技能，Claude Code 永远先读它。

这种情况的排查思路很清晰：先在项目里用/skill查看列表，如果列表中的技能名旁有特殊标记或来源提示，就能判断加载的是哪个版本；如果看不出区别，就手动检查项目.claude/skills下是否有同名目录。解决冲突的办法也很直接：要么删除项目级版本，要么保留两个版本但把全局版本改名避免混淆。我一般不推荐同名共存，因为后续维护时你很容易忘记哪个才是"主人"，改文件时改错地方简直是家常便饭。

5.3 切换后技能执行报错：路径与权限问题

从项目级切到全局后，经常出现一种奇怪的现象：技能能被正常列出、触发也没问题，但执行到某一步就报错"文件不存在"或"权限不足"。绝大多数情况下是因为 SKILL.md 里写了硬编码的相对路径，比如./scripts/analyze.py，在项目级目录下这个路径存在，切到全局后 Claude Code 会把当前工作目录作为基准，于是找不到全局目录里的脚本。

解决方案有两个：一是在 SKILL.md 中明确使用$CLAUDE_SKILL_DIR这类环境变量来拼接辅助文件路径，这样无论技能放在哪里，Claude 都能准确找到它同目录下的脚本；二是把所有辅助脚本放在操作系统能全局执行的位置（比如/usr/local/bin），技能文档里只写命令名。第一种方式更符合技能构造的天然习惯，也便于技能包整体移动。第二个常见报错是权限问题，尤其在全局目录里放了可执行脚本时，需要保证脚本有+x权限。

注意：Claude Code 在执行 Skill 时通常会以对话工作目录为基准调用命令。如果脚本文件本身放在全局技能目录，而 SKILL.md 里用相对路径引用，就会出现找不到文件的误报。遇到"脚本明明在却执行失败"的情况，先检查引用方式，别急着重装技能。

5.4 技能加载速度变慢：description 写得太宽泛

当你的全局技能数量积累到十几个以后，会明显感觉 Claude Code 在每次对话时的响应决策变得慢了一些，这是正常的，因为 Claude 似乎需要把当前需求和可用技能做匹配。如果技能数量不算多但依然很慢，问题多半出在description里：写得太宽泛，导致每个技能都像是候选，匹配成本变高。

我后来的优化方式是刻意把 description 缩短且聚焦：只写明任务类型、触发词和适用条件，不要在这里长篇大论介绍执行细节。执行细节放正文里，触发判断只看简介。这就像给技能做一个"电梯演讲"，说得越清楚，Claude 越容易快速排除无关技能，整体响应速度也会上来。

5.5 一个隐藏很深的坑：软链在 Windows 上失败

之前在某开发者那里遇到一个案例：他在 Windows 上把项目级 Skills 改成全局软链后，发现 Claude Code 在项目里完全识别不到这个技能。排查到最后，是他在命令里写的是mklink /D code-review %USERPROFILE%\.claude\skills\code-review，没有加引号，导致路径中的空格被拆分成了多个参数。修改为带引号的完整路径后恢复正常。

另外 Windows 上创建符号链接需要管理员权限，普通终端执行时会报"你没有权限执行此操作"。如果你不想每次用管理员终端，可以考虑改用目录联接（junction），mklink /J类型，它不需要管理员权限，兼容性也更好。但需要注意的是，目录联接在语义上和符号链接有细微差异，在 Git 等工具里可能被识别为特殊的链接类型，提交到仓库后团队其他人 clone 的效果和软链不完全一致。

6. 实际使用中积累的心得和经验

先说说我的分类习惯。我把自己的 Skills 分成三层：第一层是"个人效率类"，比如上面的 commit-helper、review-helper，这些都放全局，因为它们不依赖任何特定项目的技术栈；第二层是"技术栈通用类"，比如"Python 项目单元测试助手""React 组件脚手架生成器"，这些我也放全局，但会在 description 里写明"当且仅当项目使用 Python/React 时触发"，避免在无关项目中误调用；第三层是"业务专属类"，一律放项目级目录并提交到 Git 仓库，比如某个项目的"数据迁移脚本规范""针对旧代码库的兼容性检查"，这类技能换一个代码库就是垃圾信息。

关于从项目级切到全局的另一个经验是：不要贪多求全。我早期恨不得把所有项目级技能全部升级为全局技能，结果全局目录越来越臃肿，每次对话的决策速度都开始让人着急。后来我控制了一个节奏：同一时间全局技能尽量保持在十五个以内，这个数量既覆盖大部分通用场景，又不至于拖慢整体响应。一个技能如果连续两周没有触发一次，我就会考虑它是否真的值得放在全局，或者是不是 description 写得不够好导致触发率低。

最后再分享一个写 SKILL.md 时很容易忽略的点：给技能配上"不做什么"的说明。在正文中写清楚"这个技能不做权限校验""不生成测试代码""不修改已有文件的格式"，能帮 Claude 在关键时刻避免执行过头。我在做代码审查技能时特意加了"不要直接改代码，只输出建议"这一条，实测下来能减少很多不必要的文件改动。这一个细节看起来简单，但能让你后期维护体验提升非常多，也建议你在自己的技能里加上。