企业官网建设流程全解析

Claude Code 用久了你会发现，真正拉开配置效率差距的不是模型参数，而是 Skills。大多数新手面对“安装 Skills”这种需求时，第一反应就是把文件夹往.claude里一丢，却没搞清项目级和全局级是两个完全不同的生效范围，结果换了仓库之后技能集体消失，或者全局技能跟项目自带规则打架。这篇文章就专门说清楚两件事：第一，技能到底怎么装才能被 Claude Code 识别；第二，怎么把一个项目里打磨好的技能从项目级切到全局级。最后把我在反复安装、迁移、排错过程中攒下来的经验和坑一并交代清楚，方便你照着操作。

1. Skills 的存放逻辑与加载机制：项目级、全局级必须分清

说到 Skills，其实不用整什么高深原理，你只需要先记住两个目录位置。

项目级：<项目根目录>/.claude/skills/，只对当前项目生效，会跟着代码仓库走；全局级：~/.claude/skills/，在 Windows 上通常是C:\Users\你的用户名\.claude\skills\，它对这台机器上所有由你启动的 Claude Code 会话生效。

每个 skill 就是这两个目录下的一个子目录，子目录里必须有一个文件叫SKILL.md。Claude Code 在会话启动的时候会扫描这两个根目录，逐个读取SKILL.md文档头部的 YAML frontmatter，把里面声明的name和description注册进当次会话。也就是说，真正决定 Claude 什么时候调用这个技能的，是description那一句话；真正决定技能执行什么动作的，才是SKILL.md正文中的步骤说明。

我最初犯过一个很蠢的错误：把整个技能目录直接扔进~/.claude，以为这样就算装好了。结果 Claude 完全不认识它。后来我总结出一个笨但特别有效的自查方法：打开技能所在目录，看路径是不是严格对应.claude/skills/<技能名>/SKILL.md，中间少任何一层，都有概率扫描不到。别笑，这个问题在 Windows 上更容易出现，因为资源管理器默认帮你隐藏了.claude这种点开头的目录。

项目级和全局级的选择，可以直接参考这张表：

1.1 为什么 description 决定技能能不能被“想”起来

Skill 的触发机制和很多人想象的并不一样。Claude Code 不会把每个技能的全部正文都塞进上下文，那样上下文很快就会被几十个 SKILL.md 撑爆。它只把每个技能的name和description作为候选信息注册进系统，当你的提问和这段描述足够相关时，模型才判断“这个场景应该调用某个技能”，然后把对应的SKILL.md全文读入，当作一份任务说明书来执行。

这个设计的本质是“把工作模板外置”。对话过程中，主上下文始终保持轻量；技能要承担的具体步骤、规范要求、输出格式，全部放在需要时才加载。它的副作用就是：如果你把 description 写得像一句很随意的话，模型大概率永远想不起来要用它。

拿我自己举例。我一开始给某个审查技能写的 description 是“前端审查用”，后来发现它几乎不会被自动触发。改成“当用户要求审查前端代码、检查组件交互、评估页面样式是否符合项目规范时使用”之后，触发频率明显提升。原因很简单：description越能覆盖用户真实提问的各种变体，模型把它挑出来的概率就越高。

1.2 什么情况下你需要“从项目级切到全局”

标题里那个“从项目级切到全局”不是个抽象概念，它对应几种非常具体的场景。

第一种，你在 A 项目里写了一个顺手到不行的代码审查技能，结果切到 B 项目、C 项目时发现它不在，这才意识到它只属于 A 项目。第二种，团队仓库里早就放了一个技能目录，但里面混进了你个人的工作习惯，你不想用这个版本污染项目，希望把自己那版提为全局默认。第三种，你想建立一套“个人基础工作流”，不管打开哪个仓库，Claude 都应具备同样一批基础技能，而不是每开一个新项目就得重新复制一遍。

这三种场景都指向同一个操作方向：把技能从“跟着仓库走”变成“跟着你走”。但我必须提前提醒一句，切换不是简单地把文件搬个家。如果搬完之后项目目录里还残留同名技能，项目级会覆盖全局级，你改了全局版本却不生效，到时候更让人摸不着头脑。

2. 项目级安装：从拿到一个 skill 到让它真正生效

项目级安装是所有安装方式的基础。先把它吃透，切全局只是多走两步复制和清理的事。

2.1 从官方 skills 仓库手动安装一个现成技能

我第一次练手用的是 Claude 官方维护的 skills 示例仓库。操作流程并不复杂，就是 clone 下来、挑一个目录、复制到项目.claude/skills下。完整命令如下：

# 1. 先把官方仓库临时克隆到 /tmp git clone --depth 1 https://github.com/anthropics/skills.git /tmp/skills-repo # 2. 看一看仓库里有哪些技能 ls /tmp/skills-repo # 3. 把需要的技能目录复制到当前项目 cp -r /tmp/skills-repo/artifact-analysis .claude/skills/ # 4. 清理临时克隆 rm -rf /tmp/skills-repo

执行完之后，可以确认一下目录结构是否完整：

your-project/.claude/skills/artifact-analysis/SKILL.md

这一步最重要的问题是：你当前项目根目录下有没有.claude文件夹？没有的话先mkdir -p .claude/skills再复制，不然cp命令会把目录结构复制得乱七八糟。

2.2 验证一个 skill 是否被当前会话识别

复制完技能之后，一定不要在当前会话里继续验证。最可靠的方式是退出当前会话，重新打开一个全新的 Claude Code 会话，然后直接用一句包含技能用途的话去测试。

比如我安装了 artifact-analysis 之后，就在新会话里问：“你现在注册的技能列表里有没有 artifact-analysis？如果没有，告诉我你目前有哪些技能。”如果它能够准确报出这个名字并简述用途，说明目录层级和SKILL.md都正常；如果它说完全没有这个技能，那基本可以断定是目录层级不对，或者是SKILL.md文件名的拼写问题。

2.3 手写一个最小可用的项目级 skill

更多时候，你要的技能根本找不到现成的。比如你们团队内部有一套独特的代码规范，你希望 Claude 能按照这套规范做审查，那就得自己写。

一个最小可用的 skill 只需要一条命令能创建出来：

mkdir -p .claude/skills/our-frontend-review cat > .claude/skills/our-frontend-review/SKILL.md <<'EOF' --- name: our-frontend-review description: 针对本项目前端代码的审查技能。当用户要求 review 前端代码、检查组件问题、评估页面交互是否符合项目规范时使用。 --- # 前端代码审查 执行以下步骤： 1. 先读取项目根目录的 docs/frontend-guideline.md，了解本项目规范。 2. 按组件结构、样式细节、交互逻辑、可访问性四个维度审查。 3. 每个问题按“严重 / 一般 / 建议”三级输出。 4. 修改意见必须给出具体的文件路径和行号。 EOF

这是我在项目里用了很久的一个前端审查技能雏形，虽然简陋，但它完整踩中了 Claude Code 识别技能的三个关键要求：目录名合法、SKILL.md命名规范、frontmatter 的name和description齐全。

这里我想重点强调 description 的写法。很多人会把它写成一句名词解释，比如“前端审查 skill”，但这对模型触发没有任何帮助。触发能力来自一句包含“用户可能怎么表达需求”的描述，我的习惯是套用“当用户要求 / 当请求场景包含 / 仅当满足条件时”这类句式。description 不是给你自己看的说明书，是给模型的候选匹配信号。

手写技能还有几个经验供你参考：

• name字段用英文短横线命名，不要用中文，也不要包含空格，避免在不同操作系统间产生解析差异。
• action 步骤最好写成有序列表，模型执行时天然容易遵守顺序。
• 正文不要堆背景知识，第一步应该直接告诉模型“先去读什么、再检查什么”。

2.4 项目级与全局级的试用节奏

我个人的习惯是，任何新技能先在某个真实项目里试用两三天，看它触发是否稳定、输出是否符合预期。稳定之后再决定要不要切到全局。这样操作有一个额外好处：你顺手就走了一遍“项目级到全局”的完整路径，比空想切换逻辑靠谱得多。

3. 从项目级切到全局：复制、软链与团队仓库策略

这节是整个主题的重头戏。切到全局在操作上无非两个要点：把技能文件放到全局目录，同时处理掉项目目录里的残留。

3.1 最直接的搬移：先复制、验证、再删除

以our-frontend-review为例，最直观的命令是这样：

mkdir -p ~/.claude/skills cp -r .claude/skills/our-frontend-review ~/.claude/skills/ rm -rf .claude/skills/our-frontend-review

但这条命令连起来跑有个隐性问题：你没办法确认全局那份是否可用，就把项目里那份删了。万一复制过程中因为路径或权限问题导致文件不完整，原来还能用的技能就彻底没了。

我更推荐分成三步走。第一步，只复制不删除：

cp -r .claude/skills/our-frontend-review ~/.claude/skills/

第二步，开一个全新的 Claude Code 会话，在任意一个目录下测试这个技能还能不能被识别和触发。第三步，确认全局版本正常工作之后，再回到原项目删除项目级副本：

rm -rf .claude/skills/our-frontend-review

这里有一个非常容易踩的陷阱：当你复制完还没删除项目级副本时，项目级和全局级同时存在同名技能，Claude Code 会优先读取项目级那份。如果你此时急着验证“全局是否生效”，得到的其实是项目级版本的行为，结果会让你误以为切全局成功了。所以删除项目副本之后，一定要再开一个新会话验证一次，这次看到的行为才真正来自全局目录。

3.2 用软链接让项目和全局共用同一份

如果你希望某个技能既在全局生效，又在当前项目里继续保留入口，甚至做到“改动一份、两边同步”，可以用软链接。

mv .claude/skills/our-frontend-review ~/.claude/skills/ ln -s ~/.claude/skills/our-frontend-review .claude/skills/our-frontend-review

执行之后，项目目录下那一条就是指向全局目录的符号链接。Claude Code 扫描项目级 skills 目录时，会顺着链接读到全局的真实内容。这样做的最大好处是单源维护：以后想更新这个技能，直接改~/.claude/skills/our-frontend-review/SKILL.md就行，不用再比较项目版和全局版哪个新。

不过软链接有个明显局限：它只对你当前这台机器有效。如果项目提交到了团队的 git 仓库，同事 clone 下来之后，链接往往在原位失效，项目反而少了一个必要技能。所以在个人项目里我会用软链，团队项目我基本不用，除非我在仓库里同时写清楚这个目录的引用关系。

3.3 Windows 里的命令差异

Windows 用户如果是在 Git Bash 或者 PowerShell 里操作，ln -s的行为和 Linux/macOS 不太一样。Git Bash 在某些权限配置下不会真正创建符号链接，而是退化成复制，导致你后续改动全局文件时，项目里的副本纹丝不动。PowerShell 里创建符号链接可以用：

New-Item -ItemType SymbolicLink -Path .claude\skills\our-frontend-review -Target $HOME\.claude\skills\our-frontend-review

如果嫌麻烦，Windows 上最省心的方案还是直接用cp -r，把文件复制到全局目录，再删除项目目录里的原文件夹。虽然少了一点“自动同步”的好处，但在 Windows 上少踩权限坑，我认为更划算。

3.4 团队仓库里的切换策略

切换到全局这件事，在个人项目里很简单，但放到团队仓库里就需要多些考量。试想一下：你把自己常用的审查技能迁到了全局，然后从项目目录里删掉了它。同事 pull 代码后，会突然发现项目里少了一个团队一直在用的技能，而且他们压根不知道这是你个人的迁移操作。

我的建议是这样：如果某个技能承载的是团队共识，比如代码审查规范、接口文档生成规则，那它应该继续留在项目级并且提交到 git，让全团队共享同一版本；如果某技能只是你的个人提效工具，那就切到全局，同时记得在项目提交说明里注明“已迁移至全局，项目内不再内置”。另外，可以考虑在项目的.claude/skills/README.md里写几行索引，说明哪些技能属于项目、哪些指向全局个人技能，免得后来人接手时对着目录猜谜。

4. 装完不生效？按这条链路排查

装技能不生效，是社区里出现频率最高的问题。我把实际排查过的案例归纳成一条链路，按顺序检查下来，基本能覆盖 90% 的情况。

4.1 第一步：分清是“没识别”还是“没触发”

两种不生效对应的原因完全不同。没识别，指的是你问 Claude 当前有哪些技能时，它根本报不出这个名字，这通常是路径、命名、扫描的问题；没触发，指的是它知道有这个技能，但你在对话里提相关需求时，它不主动调用，这通常指向 description 写得太差。

区分方法很简单：开新会话，先让它列技能列表，再按触发场景提问。如果列表里没名字，检查目录层级和 SKILL.md；如果列表里有名字但不触发，去改 description 的措辞，不要动目录结构。这两个方向搞反了，会浪费大量排查时间。

4.2 目录与命名的三个高频错误

绝大多数的“新装的技能没反应”，最后都归结于三个低级失误：

• 少了skills这一层目录。把技能放在了~/.claude/foo或<项目>/.claude/foo，正确的必须是~/.claude/skills/foo或<项目>/.claude/skills/foo。
• SKILL.md的大小写或拼写不对。有人写成skill.md，有人写成SKILL.MD，在大小写不敏感的文件系统上可能正常，但换到 Linux 容器或 CI 环境就会失效。
• 技能目录内部根本没放SKILL.md，只有一堆说明图片、代码示例。Claude Code 只按SKILL.md这个名字去找入口，其他文件再齐也白搭。

4.3 frontmatter 解析失败会整包丢弃

就算目录和文件名全对，frontmatter 解析失败也会让整个技能被忽略。我见到比较多的问题有几个：文件开头少了---；用了中文全角冒号：替代了 YAML 的:；description 想换行却直接硬回车，导致 YAML 结构破损。

最稳的模板就是下面这一版，不要发挥，直接照抄：

--- name: my-skill description: 当用户要求……时使用，执行……。 ---

description 尽量保持一行。如果确实需要多行，使用 YAML 支持的|-或>折叠语法，不要在行中间随手敲回车。

4.4 改完技能必须新开会话

Claude Code 通常是在会话开始时完成技能扫描的。你中途改了SKILL.md、加了新技能，旧会话不一定能感知到这些变化。我经常犯的毛病就是改完 description 继续在同一个会话里测试，结果发现行为没变，误以为改坏了，其实只是旧会话还在用旧状态。

规避办法很简单：任何技能新增或修改，直接退出当前会话，重新新建一个会话再验证。这个小习惯能省掉很多无谓的猜测。

4.5 全局与项目重名的覆盖陷阱

这是“切到全局但始终不生效”最常见的原因。项目级技能的优先级高于全局级，当你全局目录里有一份our-frontend-review，项目目录里又残留一份同名旧版，Claude 读到的永远是项目里那份。你在全局目录里改得再勤，也不会反映到当前项目行为里。

排查这个情况可以用两条命令：

find . -type d -name "our-frontend-review" ls ~/.claude/skills/

只要两个位置出现同名技能，优先以项目目录里的为准。想彻底切到全局，务必清理项目目录下的原文件夹或软链，然后再开新会话验证一次。

5. 安装后的验收清单与几类值得装的 skill

最后给一份可以直接照着做的验收清单，以及我长期使用下来认为真正算得上“必装”的技能类型。

5.1 一张能直接用的验收表

这张表我每次装完新技能都会过一遍，没有再被“技能没反应”困扰过。

5.2 我认为称得上“必装”的几类技能

先说结论：我最推荐的并不是某一个具体技能，而是一类“流程模板型”技能。这类技能非常适合做成SKILL.md，因为它的核心价值就是把分散的、容易被遗忘的步骤固化下来。

• 提交信息生成：固定按 Conventional Commits 规范生成提交信息，要求模型先读git diff，再判断 scope，最后输出完整的 message 和 changelog 片段。
• 前端代码审查：结合项目内的样式规范、组件库文档，输出分级问题清单，每个问题附带文件路径和行号。
• 单元测试生成：先让模型列出测试计划，再逐文件生成测试代码，过程中不允许修改业务代码。
• API 文档生成：要求模型先梳理接口定义与数据结构，再按统一格式输出说明文档和示例。
• 长任务拆解：把一个大需求拆成可逐步验证的里程碑，每个里程碑写清楚完成条件和验收方式。

这些技能的共同点在于：它们不是让模型“会做这件事”，而是让模型“每次都按你的既定流程做这件事，且不会跳过任何中间步骤”。技能真正解决的，就是流程一致性。

5.3 给全局技能目录写一份索引 README

随着技能数量增长，~/.claude/skills会迅速变成一个堆满文件夹的杂物间。我的建议是在全局目录里放一个README.md，记录每个技能的用途、依赖的外部命令、最近更新时间。我本地维护了 30 多个技能之后，深深觉得这份 README 比技能本身还关键。没有它，你半年后再看这些目录，根本想不起来某个技能当初是给什么场景用的。

从全局删掉一个不再使用的技能不是难事，但要判断“这个目录到底能不能删”，没有一个好索引就只能靠猜。这一点值得你在技能数量起来之前就做好准备。

说实话，Skills 在 Claude Code 里的地位被很多人低估了。它不是锦上添花的插件，而是把一次性对话变成可持续工作流的关键机制。我的建议始终是：先在项目里试用，稳定之后把真正通用的技能切到全局；切换时记住项目级优先、旧会话不读新配置、清理同名残留这三条规矩，基本就不会出问题。这套流程我已经反复跑了许多轮，现在它已经是我换新电脑之后必做的一组初始化操作。