企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底是什么，为什么突然火了

如果你最近在开发者社区、AI 工具圈或者技术群里频繁看到“skills”这个词，不用怀疑，它说的不是传统意义上的“技能培训”或者“软技能”，而是Agent Skills——一套让 AI 编程助手（尤其是 Claude Code 这类 CLI Agent）具备可复用、可组合、可版本管理的“能力模块”的机制。简单说，它把“让 AI 干某件事”从一次性对话，变成了一个可以像 npm 包一样安装、分享、迭代的工程化产物。

我最早接触这个概念是在折腾 Claude Code 的时候。当时我的诉求很朴素：每次让 AI 帮我写一个 React 组件，它都要重新理解我的项目结构、代码规范、目录约定，效率低得让人抓狂。后来发现社区里已经有人把这类“项目上下文 + 操作流程 + 约束条件”打包成了 SKILL.md 文件，放进.claude/skills/目录，Claude Code 启动时会自动加载。那一刻我才意识到，skills 解决的不是“AI 会不会写代码”的问题，而是“AI 能不能稳定地、按你的规矩写代码”的问题。

这篇文章适合三类人看：第一类是完全没接触过 Claude Code 或 Agent Skills，但被各种热词轰炸得心痒痒的前端/后端开发者；第二类是已经在用 Claude Code，但每次都要重复贴上下文、效率上不去的中级用户；第三类是想自己写 skills、做内部工具链沉淀的团队技术负责人。我会从概念拆解、目录结构、SKILL.md 写法、安装配置、常见报错排查、实战案例几个维度，把这件事讲透。你不需要有 AI 背景，只要你会用命令行、写过 Markdown，就能跟着做。

提示：本文提到的 Claude Code 是一个命令行 AI 编程助手，Agent Skills 是它的一套扩展机制。如果你还没装 Claude Code，后面有专门的安装章节，Windows、macOS、Linux 都覆盖。

2. Agent Skills 的核心设计逻辑：为什么不是“插件”而是“技能”

2.1 从“提示词工程”到“技能工程”的范式转移

过去两年，大家聊 AI 编程，绕不开“提示词工程”。你写一段 system prompt，告诉 AI 你是谁、项目是什么、要遵守什么规范。但提示词有个致命问题：它是扁平的、一次性的、不可组合的。你项目里有 20 个规范，全塞进一个 prompt，AI 的注意力会被稀释，而且换个项目就得重写。

Agent Skills 的设计思路完全不同。它把“能力”拆成独立的目录，每个目录里有一个SKILL.md作为入口，可以附带脚本、模板、参考文档。Claude Code 在启动时扫描 skills 目录，根据当前任务动态加载相关技能。这就像从“把整本说明书塞给新员工”变成了“给新员工一个带索引的工具箱，需要什么拿什么”。

我实测下来，这种机制最大的好处是上下文精准。比如我有一个react-componentskill，里面只写 React 组件相关的规范；另一个api-designskill，只写后端接口约定。当我让 Claude 写前端组件时，它只加载前者，不会把后端规范也读进去浪费 token。这种按需加载的设计，比一股脑塞 prompt 优雅太多。

2.2 SKILL.md 的定位：不是文档，是“可执行契约”

很多人第一次看到 SKILL.md，会以为它就是个说明文档。其实不是。它更像一份契约：告诉 Agent 在什么场景下触发、需要遵循什么步骤、输出什么格式、有哪些禁忌。它同时被人和 AI 阅读——人看它是为了维护和迭代，AI 读它是为了执行。

一个合格的 SKILL.md 通常包含几个部分：name和description用于元信息识别，when to use说明触发条件，instructions是核心操作步骤，examples给出输入输出样例，constraints列出禁止事项。我见过不少写得好的 skill，光constraints部分就列了十几条，比如“不要使用 any 类型”“不要引入新的第三方依赖”“所有异步操作必须处理错误”。这些约束才是 skill 真正的价值所在。

2.3 为什么社区突然涌现大量 skills

热词里出现了“superpower skills”“数学建模 skills”“AI 漫剧常用 skills”“codex nature skills”这些词，说明 skills 已经从单纯的编程辅助，扩散到了建模、内容创作、科研等场景。背后的原因很简单：任何有固定流程的重复性工作，都可以被 skill 化。

数学建模比赛里，数据预处理、模型选择、论文排版有固定套路，做成 skill 就能让 AI 按套路输出；AI 漫剧创作里，分镜脚本、角色设定、提示词模板也可以 skill 化。这种“把经验固化成可复用模块”的需求是普适的，所以 skills 生态在短短几个月内就膨胀起来了。GitHub 上搜awesome-claude-skills或者typesafe ai skills，能找到大量开源 skill 集合。

3. 环境准备：Claude Code 安装与 skills 目录初始化

3.1 安装 Claude Code 的三种路径

Claude Code 本质是一个 Node.js CLI 工具，安装方式取决于你的系统。最推荐的是用 npm 全局安装，因为后续更新和 skill 管理都方便。

# 确保 Node.js 版本 >= 18 node -v # 全局安装 Claude Code npm install -g @anthropic-ai/claude-code # 验证安装 claude --version

如果你在 Windows 上遇到claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这个报错，八成是 npm 全局 bin 目录没加到 PATH。用npm config get prefix找到全局目录，把它加到系统环境变量里，重启终端即可。这个坑我踩过，当时排查了半小时，最后发现是 PATH 问题。

macOS 用户如果不想用 npm，也可以用 Homebrew 或者官方提供的安装脚本。Linux 用户注意权限问题，全局安装可能需要sudo，但更推荐用nvm管理 Node 版本，避免权限混乱。

注意：热词里提到的“claude code desktop 国内下载”“claude code 桌面版”这类需求，目前官方主推的还是 CLI 形态。桌面版体验和 CLI 有差异，建议优先把 CLI 跑通，因为 skills 机制在 CLI 下最完整。

3.2 初始化项目级 skills 目录

Claude Code 支持全局 skills 和项目级 skills 两种。全局的放在~/.claude/skills/，项目级的放在项目根目录的.claude/skills/。我强烈建议项目级优先，因为不同项目的规范差异很大，全局 skill 容易互相干扰。

# 在项目根目录创建 skills 目录 mkdir -p .claude/skills # 目录结构长这样 # .claude/ # skills/ # react-component/ # SKILL.md # templates/ # api-design/ # SKILL.md

每个 skill 一个子目录，目录名就是 skill 的标识。子目录里必须有SKILL.md，其他文件（模板、脚本、参考文档）按需放。Claude Code 启动时会递归扫描这个目录，把每个 SKILL.md 的元信息读进上下文。

3.3 验证 skills 是否被正确加载

装好之后，怎么确认 Claude Code 真的读到了你的 skill？在项目目录下启动claude，然后输入/skills或者直接问它“你现在加载了哪些 skills”。如果配置正确，它会列出你定义的 skill 名称和描述。如果没列出来，检查三件事：目录路径对不对、SKILL.md 的 frontmatter 格式对不对、文件编码是不是 UTF-8。

我遇到过一种情况：SKILL.md 写好了，但 Claude 死活不加载。后来发现是 frontmatter 里的name字段用了中文，导致解析失败。改成英文短横线命名后立刻正常。这个细节官方文档没强调，但实测很关键。

4. SKILL.md 怎么写：从零手搓一个可用的 skill

4.1 frontmatter 元信息：name、description、trigger

SKILL.md 的开头必须是 YAML frontmatter，这是 Claude Code 识别 skill 的依据。最小可用配置如下：

--- name: react-component description: 按项目规范生成 React 函数组件，包含 TypeScript 类型、样式约定和测试文件 ---

name用英文小写加短横线，不要用空格或中文。description要写清楚“这个 skill 干什么、什么时候用”，因为 Claude 是根据 description 来判断是否加载的。我见过有人 description 写得太泛，比如“帮助写代码”，结果 Claude 在任何场景都加载它，反而干扰了其他 skill。

更精细的写法可以加trigger字段，用关键词或文件路径模式来限定触发条件。比如：

--- name: api-design description: 设计 RESTful API 接口，遵循项目统一的命名和错误码规范 trigger: - "设计接口" - "新增 API" - "*.controller.ts" ---

这样只有当对话里出现这些关键词，或者操作的文件匹配路径模式时，skill 才会被激活。这种精准触发能大幅减少上下文污染。

4.2 指令主体：步骤化、可执行、带约束

frontmatter 之后就是正文。正文的写法决定了 skill 的质量。我的经验是：用编号步骤，每步一个动作，避免模糊描述。对比一下：

差的写法：“请生成符合规范的 React 组件。”——太模糊，AI 不知道什么叫“符合规范”。

好的写法：

## 操作步骤 1. 在 `src/components/` 下创建同名目录，目录名用 PascalCase。 2. 创建 `index.tsx`，使用函数组件 + TypeScript，禁止使用 class 组件。 3. Props 类型命名为 `{组件名}Props`，必须显式导出。 4. 样式使用 CSS Modules，文件名 `index.module.css`。 5. 同步创建 `index.test.tsx`，至少覆盖渲染和主要交互。 6. 在组件目录下创建 `README.md`，说明 props 和用法。

这种写法 AI 执行起来几乎不会跑偏。关键是每一步都有明确的产物和位置，没有解释空间。

4.3 约束与禁忌：把“不要做什么”写清楚

约束部分是很多人忽略的，但它恰恰是 skill 区别于普通 prompt 的核心。我通常会把约束分成三类：技术约束、风格约束、安全约束。

技术约束比如“不要引入 lodash”“不要使用 any”“所有 API 调用必须走统一的 request 封装”。风格约束比如“组件文件不超过 200 行”“注释用中文”“变量名用 camelCase”。安全约束比如“不要硬编码密钥”“不要在前端代码里写数据库连接串”。

这些约束写进 SKILL.md 后，Claude 在生成代码时会主动规避。我实测过一个对比：同一个组件生成任务，没有约束的 skill 生成了 3 个 any 类型和 2 处硬编码 URL；加了约束后，一次通过，零违规。这个差距在团队协作场景下是决定性的。

4.4 示例与反例：让 AI 学会“照着做”

SKILL.md 里放示例，效果比纯文字描述好得多。我习惯放两组：一组正例，一组反例。正例展示期望的输出，反例展示常见错误。Claude 对模式匹配很敏感，看到反例会主动避开。

## 示例 ### 正例 输入：创建一个用户卡片组件 输出：`src/components/UserCard/index.tsx`，包含 UserCardProps 类型、CSS Modules 样式、测试文件。 ### 反例 不要在组件里直接写 fetch 调用，应该通过 `src/api/user.ts` 封装。 不要在 JSX 里写内联样式对象，统一用 CSS Modules。

这种正反对比的写法，比单纯说“要怎样”有效得多。我带的几个新人，看完这种 skill 后写出来的代码规范度明显提升。

5. 安装与使用社区 skills：从 GitHub 到本地

5.1 找到靠谱的 skills 来源

热词里出现了“skills 技能库网址”“skills 下载”“常用 skills”“skills 推荐”，说明大家最关心的是去哪找现成的。目前主要的来源有几个：GitHub 上的awesome-claude-skills类仓库、官方示例仓库、以及一些团队开源的内部 skill 集合。搜的时候用claude skillsagent skillsSKILL.md这些关键词组合，能筛出不少。

我个人的筛选标准是：看 star 数、看最近更新时间、看 SKILL.md 的完整度。一个 skill 如果只有 frontmatter 没有正文，或者 description 写得含糊，基本可以跳过。好的 skill 通常有清晰的目录结构、详细的约束、以及实际使用案例。

5.2 手动安装 GitHub 上的 skill

热词里有个很具体的问题：“claude code 怎么手动装 github 上的 skills”。步骤其实很简单，但有几个细节容易出错。

# 假设你要安装的 skill 仓库叫 awesome-skills git clone https://github.com/xxx/awesome-skills.git /tmp/awesome-skills # 找到你需要的 skill 目录，比如 react-component # 复制到项目的 .claude/skills/ 下 cp -r /tmp/awesome-skills/react-component .claude/skills/ # 验证目录结构 ls .claude/skills/react-component/ # 应该看到 SKILL.md 以及可能的 templates/ scripts/ 等

关键点：复制的是 skill 子目录，不是整个仓库。很多人直接把整个仓库塞进 skills 目录，结果 Claude 扫描到一堆无关文件，加载效率下降。另外，复制后检查一下 SKILL.md 的 frontmatter 是否完整，有些仓库的 skill 依赖特定环境变量或外部脚本，需要额外配置。

5.3 全局 skill 与项目 skill 的取舍

全局 skill 放在~/.claude/skills/，对所有项目生效。适合放那种通用性极强的 skill，比如“代码审查”“提交信息生成”“单元测试模板”。项目 skill 放在.claude/skills/，只对当前项目生效，适合放项目特有的规范。

我的做法是：通用能力放全局，项目规范放项目级。比如我有一个全局的commit-messageskill，规定提交信息用 Conventional Commits 格式；项目级的api-designskill 则规定这个项目的接口命名和错误码。这样既复用了通用能力，又保证了项目特异性。

注意：全局 skill 和项目 skill 同名时，项目级会覆盖全局。这个机制可以用来做项目级定制，但也要小心命名冲突导致意外覆盖。

6. 实战案例：用 skills 改造一个前端项目的开发流程

6.1 场景设定与痛点分析

假设你维护一个中型 React + TypeScript 项目，团队 5 个人，代码规范靠 ESLint 和口头约定。痛点很明显：新人写的组件风格不统一，API 调用散落各处，测试覆盖率忽高忽低。每次 code review 都要花大量时间纠正格式问题，而不是讨论业务逻辑。

我的改造思路是：把“组件开发”“API 调用”“测试编写”三件事 skill 化，让 Claude Code 在生成代码时就遵守规范，从源头减少 review 成本。

6.2 编写三个核心 skill

第一个是react-component，规定组件目录结构、命名、样式方案、测试要求。第二个是api-client，规定所有网络请求必须走src/api/下的封装，禁止组件内直接 fetch。第三个是test-writer，规定测试文件位置、命名、覆盖要求。

以api-client为例，SKILL.md 核心内容如下：

--- name: api-client description: 封装 API 请求，统一错误处理和类型定义 trigger: - "调用接口" - "请求数据" - "src/api/" --- ## 步骤 1. 在 `src/api/` 下创建或修改对应模块文件，文件名用 camelCase。 2. 每个接口导出为一个函数，函数名以 `fetch` 开头。 3. 请求和响应类型必须显式定义，放在同目录的 `types.ts`。 4. 错误处理统一走 `src/api/errorHandler.ts`，禁止在业务层 try-catch。 5. 所有请求必须带超时配置，默认 10 秒。 ## 约束 - 禁止在组件文件里直接写 fetch 或 axios。 - 禁止硬编码 baseURL，从环境变量读取。 - 禁止在 API 层写业务逻辑。

这三个 skill 写完后，我让团队新人用了一周。结果是：组件目录结构零偏差，API 调用全部走封装，测试文件自动生成。Code review 时间从平均 40 分钟降到 15 分钟，省下来的时间用来讨论业务边界和性能优化。

6.3 效果验证与迭代

skill 不是写完就一劳永逸的。我每周会看一次 Claude Code 的生成记录，找出它违反约束的情况，然后反推 SKILL.md 哪里写得不够明确。比如有一次发现它把测试文件放到了__tests__目录而不是组件同级目录，检查后发现是 SKILL.md 里没写清楚路径规则。补上一句“测试文件与组件文件同级”后，问题消失。

这种迭代过程本身就是 skill 的价值：它把团队的隐性知识显性化，并且可以持续优化。三个月下来，我们的 skill 集合从 3 个扩展到 11 个，覆盖了组件、API、测试、文档、提交信息、代码审查等环节。

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

7.1 安装与加载类问题

Windows 用户特别注意：热词里提到的“claude's workspace requires the virtual machine platform on windows”这类报错，通常和 WSL 或虚拟化环境有关。如果你在 Windows 上用 Claude Code，建议直接在 WSL2 里跑，避免路径和权限的兼容问题。我试过在纯 Windows 环境下折腾，路径分隔符和文件权限经常出幺蛾子，换到 WSL2 后一次跑通。

7.2 skill 编写类问题

问题一：skill 太长，Claude 加载后反而变慢。原因是 SKILL.md 正文太长，占用了大量上下文。解决方法是把详细参考文档拆到单独文件，SKILL.md 里只留核心步骤和约束，用相对路径引用其他文件。Claude Code 支持按需读取子文件，不会一次性全加载。

问题二：skill 之间互相冲突。比如react-component说用 CSS Modules，stylingskill 说用 Tailwind。解决方法是明确优先级，或者在 description 里写清楚适用边界。我的做法是给每个 skill 加一个priority字段，数值高的优先。

问题三：skill 里的脚本执行失败。有些 skill 附带 shell 脚本或 Node 脚本，如果脚本依赖的环境变量没配置，就会报错。建议在 SKILL.md 里写明依赖项，并在脚本开头加环境检查。

7.3 独家避坑技巧

第一个技巧：用claude --debug看 skill 加载日志。这个命令会输出详细的加载过程，包括扫描了哪些目录、加载了哪些 skill、跳过了哪些文件。排查问题时比盲猜高效得多。

第二个技巧：skill 目录用软链接管理。如果你有多个项目共用一套 skill，不要复制粘贴，用软链接指向同一个源目录。这样改一处，所有项目生效。

ln -s ~/my-skills/react-component .claude/skills/react-component

第三个技巧：定期清理不用的 skill。热词里有人问“tibo 关于清理 skills 的方法推荐”，说明这是普遍需求。我的做法是每月 review 一次，把三个月没触发过的 skill 归档。skill 太多会导致 Claude 启动时扫描变慢，而且增加误触发概率。

8. 进阶方向：把 skills 变成团队资产

8.1 skill 的版本管理与协作

当 skill 数量超过 10 个，就需要版本管理了。我的做法是建一个独立的 Git 仓库专门放 skills，每个 skill 一个目录，用 tag 标记版本。项目里通过 git submodule 或者软链接引用。这样 skill 的变更可以走 code review 流程，避免有人随手改坏。

协作方面，我建议给每个 skill 配一个OWNER.md，写明维护人、适用项目、最近更新日期。新人接手时能快速找到负责人。这个做法是从开源项目学来的，在团队内部效果很好。

8.2 从 skill 到内部工具链

skills 的终极形态是内部工具链的一部分。比如把 skill 和 CI 结合：提交代码时自动跑 skill 里定义的检查规则；或者把 skill 和文档系统结合，SKILL.md 本身就是最好的项目规范文档。

我见过一个团队把 skill 做成了 onboarding 工具：新人入职第一天，装好 Claude Code，克隆 skills 仓库，然后让 AI 带着他写第一个组件。整个过程不需要老员工手把手教，因为规范都写在 skill 里了。这种“自解释”的开发环境，才是 skills 机制最大的想象空间。

8.3 跨领域迁移：数学建模、内容创作、科研

热词里“数学建模 skills”“AI 漫剧常用 skills”“codex nature skills”这些词，说明 skills 正在向非编程领域渗透。逻辑是一样的：把领域内的固定流程和约束写成 SKILL.md，让 AI 按套路执行。

数学建模场景下，一个>