企业官网建设流程全解析

1. Skills 装的是什么？先搞懂 SKILL.md 机制

1.1 Skills 不是插件，是一份“说明书 + 工具包”

先说个我自己的经历。上个月我接手一个老项目，代码里全是没有注释的 React 组件，页面状态管理乱成一锅粥。我本来想手写一份代码审查规范，一条条贴给 Claude Code，后来发现直接把规范写成一个 Skill，让它自己读、自己按规范审，效果完全不一样。

Claude Code 的 Skills 机制，说穿了就是给模型额外准备一批“专用工作手册”。每个 Skill 本质是一个文件夹，里面放着一个核心的SKILL.md文件，以及这个技能可能用到的脚本、模板、参考文档。模型在对话过程中会根据你的任务描述，自动判断要不要调用某个 Skill，一旦调用，就会读取这个SKILL.md，然后按照里面写的步骤、规则、示例来执行任务。

它不是传统意义上的“插件”，不需要改 Claude Code 本身的内部逻辑，也不需要写复杂的 API 接口。它更像是给模型一份“说明书”，让模型知道“在这种场景下，你应该按这样的流程做”。比如你写了一个“前端代码审查 Skill”，那SKILL.md里会写明：审查时先看组件拆分，再看状态管理，最后检查样式和可访问性，每一项列出检查点和常见反模式。模型读完这份说明书，再用自己已有的编程能力去执行，相当于一个资深工程师拿着 checklist 在帮你做 review。

我见过很多新手用户一上来就问“Skills 要不要写代码”，答案是大部分情况下只要会写 Markdown 就行。复杂一点的 Skill 会配合scripts/目录里的 Python 或 Node 脚本完成特定操作，比如读取配置文件、扫描文件依赖、生成测试用例，但脚本只是辅助工具，真正的“灵魂”是那份结构化说明书。

1.2 一个 Skill 的标准目录结构：少一层或多一层都识别不了

Docs 的规范其实不复杂，目录结构是固定的：

skill-name/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── generate_report.js ├── assets/ │ ├── prompt_templates.md │ └── examples.json └── references/ └── coding_standards.md

其中SKILL.md是唯一必须存在的文件，它顶部有一段 YAML frontmatter，大概长这样：

--- name: frontend-review description: 用于对 React 项目做代码审查，检查组件拆分、状态管理、样式规范与可访问性问题。 ---

name是 Skill 的唯一标识，description尤其重要，模型就是靠这个描述来判断“现在这个任务该不该用这个 Skill”。描述写得越具体，触发就越准确。如果你只写“用于代码审查”，模型可能在三四种场景下都犹豫要不要调用；如果你写“用于 React 项目的前端代码审查，重点检查……” ，那模型在遇到相关任务时基本会第一时间加载。

SKILL.md正文部分是实际的指令，通常包括：适用场景、执行步骤、必须遵守的规则、输入输出格式、示例。为了让模型稳定复现，步骤要写得像操作手册，而不是散文。下面是一段实际可用的SKILL.md简化示例：

--- name: commit-message-helper description: 根据 git diff 生成符合 Conventional Commits 规范的提交信息 --- # Commit Message Helper ## 适用场景 当用户要求生成 git commit message、改写提交信息、批量处理多个提交时使用。 ## 执行步骤 1. 运行 `git diff --cached` 获取暂存区改动。 2. 若无暂存内容，提示用户先执行 `git add`。 3. 根据改动类型判断 type：feat / fix / docs / style / refactor / perf / test / build / chore。 4. 生成不超过 50 字的标题行，可附加 scope。 ## 规则 - 标题行必须小写开头，禁止句号结尾。 - 正文按“为什么改 / 怎么改 / 影响范围”三段组织。

你可能会问：这些东西不写进 Skill，直接把文字贴在对话里不也一样吗？不一样。Skill 的优势在于它是“可复用、可沉淀、可共享”的文件资产。你把这段逻辑写成SKILL.md放进对应目录，下次在任何一个项目里，只要提到“帮我提交一下代码”，模型就会自动加载这份规则，不需要你重新长篇大论教一遍。这才是它真正的价值。

2. 项目级与全局：它们到底有什么区别

2.1 三种存放位置，作用范围完全不同

Claude Code 的 Skills 存放位置并不只是一个，按作用范围可以分为项目级、用户级（通常叫全局）以及组织级。实际用下来，绝大多数人只需要搞清楚前两个。

项目级的位置是项目目录下的：

your-project/ ├── .claude/ │ └── skills/ │ ├── frontend-review/ │ │ └── SKILL.md │ └── api-doc-generator/ │ └── SKILL.md

全局的位置则是在用户主目录下的.claude目录：

~/.claude/ └── skills/ ├── commit-message-helper/ │ └── SKILL.md ├── frontend-review/ │ └── SKILL.md └── weekly-report/ └── SKILL.md

注意这里的“全局”指的是对当前用户所有项目生效，而不是对操作系统所有用户生效。理解了这个层级关系，你就明白为什么很多人会纠结“这个 Skill 到底该放项目级还是全局”。

我把两类目录的区别总结成一张表，你一眼就能看明白：

一个常见误区是以为全局技能会自动出现在项目代码里，其实不会。Claude Code 启动时会在启动目录找到项目级 skills 目录，同时加载用户全局目录中的技能，两边互不冲突。

2.2 怎么选才不后悔：别把每个 Skill 都塞进全局

我在刚接触 Skills 时犯过一个很典型的错误：看到一个不错的 Skill 就复制到全局，导致~/.claude/skills/里存了几十个技能，真正常用的却不到五个。模型每次开新对话都要扫描一遍这些说明文档，虽然不至于拖慢速度，但触发准确率反而降低了——有些描述模糊的技能会“抢戏”，在明显不适合的场景下被错误加载。

我的建议是遵循“三放三不放”原则。

放项目级的场景：

• 团队内部独有的代码规范或接口约定，比如“调用支付网关必须经过统一封装”。
• 项目专属的文档模板、目录结构要求。
• 该项目的技术栈特有检查项，比如只在这个项目里用的 GraphQL 实践约定。

放全局的场景：

• 通用的 git 操作助手，比如“生成 Conventional Commits 提交信息”。
• 跨项目复用度高的代码审查、调试排错、性能分析技能。
• 个人工作效率工具，比如“整理周报”“生成每日站会纪要”“批量重命名文件”。

不放全局的场景：

• 和特定项目绑定的技术规则，放全局反而会让其他项目误触发。
• 包含敏感信息的技能，比如写死了某个服务的 token，一旦全局生效，所有项目只要满足触发条件就可能读到内容。
• 还没验证过可靠性的实验性技能，先放项目级跑几次再说。

这个取舍没有绝对正确，核心标准就一条：你会不会在超过两个项目里用到它。如果不会，就别放全局。

3. 安装：从找到 Skill 到让它跑起来

3.1 去哪里找现成的 Skills：官方市场与社区清单

很多人问“Skills 到底去哪下载”，答案并不只有 GitHub。目前比较靠谱的途径有这么几条。

第一是 GitHub 直接搜索。搜索关键词很有讲究，不要只搜 “Claude Skills”，那样出来的结果太杂。我常用的搜索词是awesome claude skills、claude code skills、agent skills，再加具体领域词，比如claude skill react、claude skill backend。GitHub 上有不少整理好的 Awesome 列表，比如一些仓库专门汇总社区里高质量的 Skill，按“前端、后端、运维、写作、数据分析”分类整理，看到合适的直接复制目录内容到本地。

第二是官方商城和第三方社区平台。随着 Skills 生态成熟，已经有专门发布和下载 Skills 的站点，可以在网页上浏览技能介绍、预览SKILL.md内容，再一键复制安装。不同平台的规则略有差别，但本质上拿到手都还是一堆文件夹。

第三是直接看别人的配置仓库。很多开发者会把自己整套~/.claude/skills/目录开源出来，你浏览他们的配置仓库比看单个 Skill 收益更高，能看到真实使用场景下的目录命名、层级组织方式、以及哪些技能会搭配使用。比如有人会同时装“代码审查”“提交信息生成”“CHANGELOG 自动维护”三个技能组合使用，这种搭配思路非常值得借鉴。

3.2 安装实操：项目级和全局各自的命令

安装的本质就是“把一个 Skill 文件夹放到正确的位置”。很多网传的 “claude skills add” 命令在不同版本里并不通用，我建议你直接掌握文件操作，这样在任何环境都不会被卡住。

先看项目级安装。假设你下载了一个api-doc-generator技能，目录名字叫api-doc-generator/，里面是完整的SKILL.md和辅助脚本。在项目根目录执行：

# 确保项目级技能目录存在 mkdir -p .claude/skills # 把技能复制到项目级目录 cp -R api-doc-generator .claude/skills/ # 查看最终结构 find .claude/skills -maxdepth 2 -type f

这样这个 Skill 就只对当前项目生效。如果你的项目还没有.claude目录，上面的命令会自动创建。

再看全局安装。全局目录是~/.claude/skills/，操作基本相同：

# 确保全局技能目录存在 mkdir -p ~/.claude/skills # 把技能复制到全局目录 cp -R api-doc-generator ~/.claude/skills/ # Windows 用户注意：主目录路径通常是 C:\Users\你的用户名\.claude\skills # macOS / Linux 用户注意：~ 已经代表当前用户主目录

如果你使用的是 git 克隆方式，可以直接把仓库克隆到对应目录，再删掉仓库里多余的说明文件和.git目录：

git clone https://github.com/example/api-doc-generator.git ~/.claude/skills/api-doc-generator # 删除 git 元数据，避免多余干扰 rm -rf ~/.claude/skills/api-doc-generator/.git

有些技能包是压缩包格式，先解压再放进目录，道理一样。安装完后，强烈建议你回头看一眼SKILL.md的 frontmatter 里name字段，确认它和文件夹名一致。不一致的话可能引发一些玄学问题，虽然大部分场景下模型能容忍，但既然规范摆在那里，保持一致总归更稳。

如果用的是 VS Code 的 Claude Code 扩展，你也可以在扩展面板里找设置入口，配置里通常有 skills 目录路径的自定义项，不过默认情况下依然读的是项目级和用户级这两个标准位置。

3.3 安装完怎么确认加载成功

很多朋友装完 Skill 后心里没底：“它到底加载了没有？”我给你几个验证思路。

最简单的方法是直接在 Claude Code 对话里输入：

你当前加载了哪些 skills？请列出所有可用的 skill 名称和描述。

如果模型能清清楚楚列出一串技能名，说明管理机制正常。如果某个新装的技能没出现在列表里，那就得排查目录结构了。

第二种方法是直接触发式提问。比如你想验证frontend-review有没有生效，就直接针对一个文件问“用 frontend-review 技能帮我审查这个组件的代码”。模型如果正确加载了技能，它会按照 SKILL.md 里的步骤和检查项逐条执行，而不是自由发挥。你可以从它的回答结构里看出来——遵循了技能模板的输出格式，就说明加载成功。

第三种方法是看调试日志。在 Claude Code 中开启详细日志模式，启动时会打印加载了多少个 skills、每个技能来自哪个路径。不同版本日志开关不一样，通常可以在配置里打开 debug。这个方法适合排查疑难问题，日常验证用前两种就够了。

装完第一个 Skill 后，我建议你立刻做一件事：在项目里新建一个测试文件，故意制造一个能触发该技能的场景，完整跑一遍。这一步能帮你确认“技能描述触发”这条链路是通的，而不是等到真实项目里才发现技能根本没被调用。

4. 从项目级切到全局：迁移的正确姿势

4.1 为什么要迁移：几个典型场景

迁移需求通常在两种情况下出现。

第一种是技能在项目 A 里验证效果好，你想在项目 B、C、D 里复用。比如我在一个 React 项目里写了state-management-review技能，专门检查 Redux 状态拆分是否合理，后来发现同样的问题在另一个 Vue 项目里也存在，只是检查点要微调。这时候与其在三个项目里各复制一份，不如把通用部分提炼出来放到全局，再分别编写每个项目的局部规则。

第二种是团队项目和个人配置混在一起，你想把它们拆开。项目级技能会进入 Git 仓库，别人克隆项目就会同步拿到。如果你的项目级目录里混着纯个人工作习惯的技能，比如“总结今天工作并生成日报”，队友会很困惑为什么提交代码的项目里会有这种东西。拆开之后，项目级只留团队共享规范，个人工具统一放全局，双方互不打扰。

还有一种比较隐蔽的场景：你在多个项目里维护同一套技能的多份副本，每次修改都要一个个同步，漏改一个就出现两个项目行为不一致。迁移到全局后，单一副本就成为唯一来源，修改一次所有项目生效，维护成本直线下降。

4.2 迁移实操：复制、检查、测试三件套

迁移不是简单地把文件夹拖过去，我总结了一套“复制、检查、测试”三件套流程。

第一步，复制。把项目级技能目录里的技能拷贝到全局目录：

# 假设当前在项目根目录 mkdir -p ~/.claude/skills # 复制单个技能 cp -R .claude/skills/state-management-review ~/.claude/skills/ # 前端代码审查、提交信息助手这类通用技能，可以批量复制 cp -R .claude/skills/frontend-review ~/.claude/skills/ cp -R .claude/skills/commit-message-helper ~/.claude/skills/

注意这里用的是cp而不是mv，原因后面细说。

第二步，检查。复制完成后，检查三件事。一是目录层级，打开~/.claude/skills/，确认每个技能文件夹下确实有SKILL.md，而不是嵌套了一层同名目录：

错误：~/.claude/skills/frontend-review/frontend-review/SKILL.md 正确：~/.claude/skills/frontend-review/SKILL.md

二是检查 frontmatter 里的name是否和文件夹名一致。三是有没有引用项目里的相对路径，比如某个脚本写死了../config.json，复制到全局后这个路径就失效了。

第三步，验证加载。启动一个新的 Claude Code 会话，用上一节说的“列出所有技能”法确认它出现在全局技能列表中，再到另一个无关项目里测试触发，确保没有依赖原项目的特殊配置。如果技能内部使用了环境变量或外部命令，记得确认这些依赖在当前环境同样存在。

4.3 迁移后优先级问题：项目级和全局重名了怎么办

迁移过程中最容易踩的坑就是重名冲突。比如你原来在项目里放了commit-helper，现在又把全局同名技能也放上了，两边都叫commit-helper，那 Claude Code 会怎么办？

根据我这段时间的实际观察，不同版本对冲突的处理策略并不完全一致，但总原则是“更具体的范围优先”。也就是说项目级技能通常优先于全局技能，因为项目目录是模型启动时的当前上下文，更贴近当前任务环境。不过每个版本更新都可能调整行为，所以最稳妥的做法还是主动避免重名。

我的建议是：迁移时先查看项目级目录里有没有同名技能，有的话先决定保留哪一份。如果你想保留全局版本，就把项目级版本重命名或者删掉；如果你想保留项目级版本，就不要把它复制到全局，否则后续修改时容易搞混“我改的到底是谁”。这里我再补一句个人体会：我一般会给全局技能起名时加个人前缀，比如my-commit-helper，这样即使和团队的项目级技能重名，也不会出现行为覆盖的混乱。

4.4 为什么不用 mv：团队协作视角下的考量

我在教别人的时候，发现一个非常普遍的操作：update 命令用mv .claude/skills/xxx ~/.claude/skills/。这个操作放在个人项目里没问题，但在团队项目里会埋雷。

项目级技能通常是要提交到 Git 仓库里的，团队成员克隆项目后，git status会显示你删掉了这个技能文件，下一次提交时其他人可能不小心把这个删除操作提交上去，导致整个团队都失去了这个技能。即使是你自己的项目，如果这个技能还在被 CI 流程引用，直接移动也会让流程中断。

所以迁移的标准动作一定是“复制到全局，再决定项目级去留”。你可以先让全局和项目级共存跑几天，确认全局版本工作正常，再把项目级版本移除。移除方式建议用git rm -r .claude/skills/xxx而不是直接rm，这样版本历史清晰可控，后面想找回也更方便。

5. 常见问题与排查实录

5.1 Skill 没有被识别的最常见原因

我踩过的坑里，最经典的就是目录层级不对。有一次我解压一个技能包，发现里面套了一层同名目录，直接把它放到~/.claude/skills/下后，Claude 完全没有反应。原因就是SKILL.md不在预期的位置。你下载到带嵌套目录的压缩包时，先看看目录结构，再决定是整体放进去还是剥掉一层外壳放进去。

第二高频的问题是 description 写得不够明确。模型的触发逻辑就是拿你的问题描述和技能的description做匹配，如果你写的是“用于前端开发”，那模型可能久久不触发；如果你写成“用于审查 React 函数组件的 props 类型、状态提升和性能优化问题，在用户提出代码审查请求时使用”，触发的概率会明显提升。我把这看作“给模型的路标”——路标越具体，模型越容易找过来。

第三类是权限问题。如果某个 Skill 依赖脚本文件，而脚本没有执行权限，模型调用时就会报错。在 Linux/macOS 下，记得给scripts/下的文件加执行权限：

chmod +x ~/.claude/skills/xxx/scripts/*.sh chmod +x ~/.claude/skills/xxx/scripts/*.py

Windows 用户则需要确认脚本能被当前环境直接调用，比如 Python 是否在 PATH 中。

第四类是缓存问题。Claude Code 会缓存技能信息，有时候新装的内容不会立即出现在当前会话中。遇到这种情况，重启一个新的对话即可，大多数情况都能解决。

5.2 使用姿势避坑：别让技能变成“一次性说明书”

很多人以为把 Skill 放进去就完事了，其实使用方式也有讲究。

先说触发方式。你可以直接说“用某个技能做某事”，这是强制指定；也可以不指定，让模型根据上下文自动选用。自动触发依赖 description 写得够不够具体，如果你的描述像“会帮我做一些事情”这种废话，那基本不会被自动选中。我建议在项目初期多尝试强制指定，观察技能是否按预期执行，稳定后再试自动触发，这样能更快迭代出高质量的技巧。

第二个坑是“把所有步骤都写死在 SKILL.md 里”。有些人为了让模型严格照做，把每一个细小动作都写进去，结果反而限制了模型的判断力。Skills 的正确姿态是“给定目标、规则、边界和检查点”，而不是“逐字逐句指导怎么敲键盘”。比如写“审查时关注组件是否超过 200 行”，这叫作可执行的规则；写“第一行应该输出一个标题，第二行输出一个列表”，这叫作过度设计。前者提高模型表现，后者只会让输出变得机械。

第三个坑涉及安全。SKILL.md文件里不要写任何密钥、token、密码。因为你可能在某个项目里用了项目级技能，后来把它复制到全局，那这份敏感信息就随着你的全局目录扩散了。更危险的是，如果你从网上下载别人共享的技能，其中可能包含恶意脚本，安装前一定要打开SKILL.md和scripts/里的文件快速看一遍，确认没有访问第三方接口、上传数据、执行可疑命令的行为。我见过有人分享“自动挖洞”之类的技能，这类技能如果加一点私货，你根本察觉不到。

5.3 快速排查表：一张表定位常见问题

结合我实际操作中踩过的坑，整理成一张排查表，你按这个顺序查，基本能解决 90% 的问题：

5.4 为什么“必装 Skills”这么火：生态现状与我的观察

最近社区里关于“必装 Skills”的讨论非常多，一方面是因为 Claude Code 的 Skills 生态已经积累了一批经过验证的高质量技能，另一方面也是因为很多人开始意识到，Skills 机制的价值不在于“装一个工具”，而在于“把团队的最佳实践沉淀成可复用的标准流程”。

我注意到现在讨论的方向已经越来越细了。有人专门研究如何为 Claude Code 接入不同的第三方模型服务，比如通过统一配置工具管理不同模型的调用方式，让同一个 Skills 资产在不同模型下都能跑起来。也有人在做类似“技能市场”的聚合平台，尝试把分散在 GitHub 各处的技能按类别、质量、下载量排序，帮助用户更快找到想要的资产。这些方向都说明这个生态正在从“扔一个 SKILL.md 就完事”的阶段，往“工程化管理、跨环境复用、质量控制”的方向走。

以我自己的经验看，现阶段最值得做的并不是追求装几十个技能，而是挑三四个高频场景反复打磨。比如前端开发人员，可以先装一个代码审查技能、一个提交信息生成技能、一个接口文档生成技能，每个技能认真调一版，让描述、步骤和规则都贴合自己的项目，跑顺之后再逐步扩展。技能贵精不贵多，一套用得顺手的工作流，比一百个落灰的说明书有价值得多。

最后再分享两个实用技巧

第一个技巧：给全局技能做“每周清理”。我每周末会花两分钟看一眼~/.claude/skills/，把超过两周没用过的技能移到archive/目录，而不是直接删除。这样既不污染正常加载，又能保留后续想用时的可能性。时间一长，留下来的都是经过真实项目验证的高频技能，目录越来越薄，但每个都能打。

第二个技巧：把description当成“搜索文案”来写。想象你的技能是一个页面，模型是搜索引擎，description就是它的 SEO 标题和摘要。好的描述要包含任务场景、具体对象、推荐时机、预期结果，不要写空泛的形容词。我经常会迭代这个字段，观察到某段时间技能总是没被触发，第一反应不是改 SKILL.md 正文，而是改 description。很多时候，光改这一段，触发率就能翻一倍。

说到底，Claude Code 的 Skills 就是一个“沉淀经验、复用流程”的机制，项目级和全局的切换也只是选择资产作用范围的问题。关键在于想清楚这个技能服务谁、给谁用、用多久。把这些基础问题想明白了，安装和迁移都只是顺手的事。