企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底在解决什么问题

最近半年，不管是在技术社区还是开发者群聊里，“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表，能看到claude code skills、codex skills、agent skills测试、skills开发、skills推荐这些词扎堆出现。很多人第一反应是：这不就是个“技能”吗，有什么好聊的？但如果你真的动手用过 Claude Code、Codex 或者类似的 AI 编程助手，就会发现一个很现实的问题——这些工具默认状态下，其实并不知道你的项目长什么样、你的团队用什么规范、你的代码库有哪些“祖传约定”。它们就像一个刚入职的聪明新人，脑子好使但完全不了解你们公司的内部流程。

skills要解决的，就是这个“最后一公里”的问题。你可以把它理解成给 AI 助手写的一份“岗位操作手册”：告诉它遇到什么场景该调用什么工具、遵循什么步骤、输出什么格式。比如你有一个前端项目，每次新建组件都要遵循特定的目录结构和命名规范，那就可以写一个component-scaffold的 skill，让 AI 在你说“帮我建个按钮组件”的时候，自动按你的规范生成文件，而不是随便丢一个Button.jsx给你。

这篇文章适合谁看？如果你是刚接触 Claude Code 或 Codex 的新手，想搞清楚 skills 到底是什么、怎么装、怎么用，那这篇内容能帮你少走很多弯路。如果你已经用过一段时间，但总觉得 AI 助手“不够听话”，那问题很可能就出在 skills 的配置上。我会从核心思路、实操步骤、常见坑三个层面，把这件事讲透。

提示：本文提到的所有操作均基于公开的开发者工具和本地环境配置，不涉及任何网络访问相关的特殊设置。所有命令和配置都可以在正常开发环境中复现。

2. 核心思路拆解：skills 为什么这样设计

2.1 从“提示词”到“技能包”的演进逻辑

早期大家用 AI 编程助手，基本就是靠聊天框里打一段提示词，比如“帮我写一个 React 组件，用 TypeScript，样式用 CSS Modules”。这种方式的问题很明显：每次都要重复描述，而且描述得再详细，AI 也可能漏掉某些细节。更麻烦的是，当项目变大、规范变多的时候，提示词会变得又长又乱，维护成本极高。

skills的设计思路，本质上是一次“关注点分离”。它把“AI 该怎么做事”这件事从对话中抽出来，变成一个独立的、可版本管理的文件。这个文件通常放在项目的特定目录下，比如.claude/skills/或者.codex/skills/，每个 skill 是一个独立的文件夹或文件，里面包含触发条件、执行步骤、输出格式等信息。当你在对话中提到相关关键词时，AI 会自动加载对应的 skill，按照里面定义的流程来执行。

这样做的好处有三个。第一是可复用：写一次，团队所有人都能用。第二是可维护：规范变了，改 skill 文件就行，不用去翻聊天记录。第三是可组合：多个 skill 可以串联使用，比如先调用code-review再调用test-generator，形成一条完整的流水线。

2.2 不同工具的 skills 机制差异

目前市面上支持 skills 机制的工具主要有几类，它们的实现方式各有侧重。Claude Code 的 skills 更偏向“自然语言描述 + 工具调用”，你写一段 Markdown 说明这个 skill 是干什么的，Claude 会根据上下文判断是否触发。Codex 的 skills 则更强调“结构化配置”，通常需要你定义明确的输入输出格式和依赖关系。还有一些插件化的方案，比如通过plugin机制把 skills 打包分发，方便在不同项目之间共享。

这里有一个很容易踩的坑：很多人以为 skills 是“写一次就一劳永逸”的东西，但实际上不同工具对 skills 的解析方式差异很大。你在 Claude Code 里写的一个 skill，直接复制到 Codex 里可能完全不起作用，因为触发机制和参数格式都不一样。所以我的建议是，先确定你主要用哪个工具，然后针对性地写 skills，不要一开始就想着“跨平台通用”。

2.3 为什么现在 skills 突然火了

说白了，是因为 AI 编程助手已经从“玩具阶段”进入了“生产阶段”。以前大家用 AI 写代码，主要是图个新鲜，生成一段能跑就行。现在不一样了，很多团队真的把 AI 助手接入了日常开发流程，这时候“可控性”就变成了刚需。你不可能让 AI 每次生成代码都靠运气，你需要它稳定地按照你的规范来输出。skills就是实现这种可控性的关键手段。

另外，随着agents概念的普及，大家开始意识到：一个 AI 助手的能力上限，不仅取决于模型本身，还取决于它能调用哪些工具、遵循哪些流程。skills本质上就是在扩展 AI 助手的“能力边界”，让它从一个“会聊天的模型”变成一个“能干活的小助手”。

3. 核心细节解析与实操要点

3.1 skill 文件的基本结构

一个标准的 skill 文件，通常包含以下几个部分。我用一个前端项目的例子来说明，假设我们要写一个“生成 React 组件”的 skill：

--- name: react-component-generator description: 当用户要求创建新的 React 组件时触发 trigger: 创建组件、新建组件、生成组件 --- # React 组件生成规范 ## 步骤 1. 询问组件名称和用途（如果用户未提供） 2. 在 `src/components/` 下创建同名文件夹 3. 生成以下文件： - `index.tsx`：组件主文件 - `styles.module.css`：样式文件 - `types.ts`：类型定义 4. 组件使用函数式写法，导出默认组件 5. 样式使用 CSS Modules，类名采用驼峰命名 ## 输出示例 ...

这个结构看起来简单，但有几个细节非常关键。trigger字段决定了 AI 什么时候会加载这个 skill，写得太宽泛会导致误触发，写得太窄又可能该触发的时候没反应。我的经验是，trigger里至少放三个不同表述的关键词，覆盖用户可能的不同说法。description要一句话说清楚这个 skill 的用途，方便 AI 在多个 skill 之间做选择。

3.2 触发条件的写法与调试

触发条件是 skills 里最容易出问题的地方。我见过很多人写了一个 skill，测试的时候怎么都不触发，最后发现是trigger里写的是“新建组件”，但自己测试时说的是“帮我创建一个组件”。AI 的匹配机制虽然有一定的语义理解能力，但并不是万能的。比较稳妥的做法是，在trigger里同时包含动词和名词的多种组合，比如“创建组件、新建组件、生成组件、添加组件”。

另外，不同工具对触发条件的处理方式不同。有些工具是“精确匹配优先”，有些是“语义相似度优先”。如果你发现 skill 经常误触发，可以在description里加一些排除条件，比如“仅在用户明确要求创建新文件时触发，不适用于修改现有组件”。

注意：调试 skill 触发时，建议先用最简单的测试用例，比如直接输入触发词，看 AI 是否加载了对应的 skill。确认触发没问题后，再测试复杂的自然语言场景。

3.3 参数传递与上下文管理

Skills 的一个高级用法是参数传递。比如你有一个code-review的 skill，可以接受一个file_path参数，AI 在触发时会自动把当前编辑的文件路径传进去。这样你就不需要每次都说“帮我 review 一下 src/utils/format.ts 这个文件”，直接说“帮我 review 一下”就行。

参数传递的实现方式因工具而异。在 Claude Code 里，通常是通过自然语言描述来约定参数格式，比如“当用户提到文件名时，将其作为target_file参数”。在 Codex 里，可能需要更明确的结构化定义。这里的关键是，参数名要清晰、一致，不要用arg1、param2这种无意义的命名。

上下文管理是另一个容易被忽视的点。Skills 在执行过程中，可能会产生一些中间结果，比如生成的代码片段、调用的工具输出等。这些内容如果全部塞回对话上下文，会导致上下文迅速膨胀，影响后续对话的质量。比较好的做法是，在 skill 里定义“输出摘要”的规则，只把关键信息返回给主对话，详细内容写入文件或日志。

3.4 多个 skills 的协作与优先级

当项目里有很多 skills 的时候，它们之间的协作和优先级就变得很重要。比如你同时有code-generator和code-review两个 skill，用户说“帮我生成一个组件并 review 一下”，这时候应该先触发哪个？如果两个都触发，执行顺序是什么？

我的建议是，在 skill 的description里明确写出依赖关系和执行顺序。比如code-review的 description 里可以写“本 skill 应在代码生成完成后触发”。另外，可以设置一个“主控 skill”，专门负责协调其他 skill 的执行顺序。这种方式在复杂的开发流程里特别有用，比如“先生成代码，再跑测试，最后做 review”这样的流水线。

4. 实操过程与核心环节实现

4.1 环境准备与工具安装

在开始写 skills 之前，你需要先确保基础环境是通的。这里我以 Claude Code 为例，讲一下从零开始的安装和配置过程。首先，你需要有一个可用的开发环境，Windows、macOS、Linux 都可以。然后按照官方文档的指引完成 Claude Code 的安装。安装完成后，在项目根目录下创建一个.claude文件夹，再在里面创建skills子文件夹。这个目录结构是 Claude Code 默认会扫描的路径。

如果你用的是 VS Code，可以安装对应的扩展，这样在编辑器里就能直接调用 Claude Code 的功能。安装完成后，在 VS Code 的设置里找到 Claude Code 相关的配置项，确认 skills 目录的路径是正确的。有些版本默认会去用户主目录下找 skills，如果你希望 skills 跟随项目走，需要手动改成项目相对路径。

提示：不同版本的 Claude Code 对 skills 目录的默认路径可能不同。建议安装完成后先创建一个测试 skill，确认工具能正确加载，再批量添加正式内容。

4.2 编写第一个可用的 skill

我们来写一个实际能用的 skill，场景是“为现有函数生成单元测试”。这个 skill 的触发词是“生成测试、写测试、补充测试”。文件放在.claude/skills/test-generator.md：

--- name: test-generator description: 为指定的函数或模块生成单元测试 trigger: 生成测试、写测试、补充测试、添加测试用例 --- # 单元测试生成规范 ## 前置条件 - 确认目标文件路径 - 确认项目使用的测试框架（Jest / Vitest / Mocha） ## 执行步骤 1. 读取目标文件，识别所有导出函数 2. 为每个函数生成至少 3 个测试用例： - 正常输入 - 边界条件 - 异常输入 3. 测试文件命名规则：`原文件名.test.ts` 4. 测试文件放在与原文件同级的 `__tests__` 目录下 5. 使用 `describe` 和 `it` 组织测试结构 ## 输出要求 - 不修改原文件 - 测试用例要有明确的描述信息 - Mock 外部依赖时使用项目已有的 mock 工具

写完之后，在 Claude Code 里输入“帮我给 src/utils/format.ts 生成测试”，观察它是否加载了这个 skill。如果加载成功，它会按照你定义的步骤去读取文件、识别函数、生成测试用例。第一次可能不会完美，比如它可能漏掉了某个边界条件，这时候你可以调整 skill 里的步骤描述，让它更明确。

4.3 参数计算与选择过程

Skills 里经常需要做一些参数计算，比如根据文件大小决定是否分片处理、根据函数数量决定生成多少个测试用例。这些计算逻辑最好在 skill 里写清楚，而不是让 AI 临时发挥。举个例子，假设你有一个batch-processor的 skill，需要根据输入文件的行数决定批处理的大小：

## 批处理大小计算规则 - 文件行数 < 1000：单批处理 - 1000 <= 文件行数 < 10000：每批 500 行 - 文件行数 >= 10000：每批 1000 行，并启用并行处理

这种明确的规则，比让 AI “自己看着办”要可靠得多。AI 在遇到模糊指令时，往往会选择最保守的方案，导致效率低下。你把计算规则写清楚，它就能按照你的预期来执行。

4.4 实操现场记录：一次完整的 skill 调试过程

我拿一个真实的调试过程来举例。当时我在写一个api-doc-generator的 skill，目标是让 AI 读取项目里的 API 路由文件，自动生成 Markdown 格式的接口文档。第一次测试，AI 确实读取了文件，但生成的文档格式完全不对，把所有的接口都堆在一个表格里，没有分组也没有层级。

我检查了 skill 文件，发现问题出在“输出格式”部分写得太笼统，只写了“生成 Markdown 文档”，没有具体说明结构。于是我改成：

## 输出格式 - 按模块分组，每个模块一个二级标题 - 每个接口包含：路径、方法、请求参数、响应示例 - 请求参数用表格展示，包含字段名、类型、是否必填、说明 - 响应示例用代码块展示，标注语言类型

改完之后重新测试，生成的文档结构就清晰多了。这个经历告诉我，skill 里的输出格式描述，一定要具体到“用什么元素、什么层级、什么顺序”，不能只说“生成文档”。

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

5.1 skill 不触发怎么办

这是最高频的问题。排查思路可以按以下顺序来：

我遇到过一次很典型的情况：skill 文件明明写好了，但怎么都不触发。后来发现是文件名里带了空格，工具在解析时把文件名当成了 skill 名称的一部分，导致匹配失败。所以文件名尽量用英文、小写、连字符，不要用空格或特殊字符。

5.2 skill 执行结果不符合预期

如果 skill 触发了，但执行结果不对，通常是因为步骤描述不够具体。比如你写“读取文件并分析”，AI 可能只读了前 100 行就停了。这时候需要把步骤拆得更细：“读取文件的全部内容，如果文件超过 500 行，分三次读取，每次读取 200 行”。

另一个常见原因是上下文干扰。如果对话历史里有很多无关内容，AI 可能会被带偏。解决办法是在 skill 里加一句“忽略对话历史中与当前任务无关的内容，仅根据本 skill 的步骤执行”。

5.3 多个 skills 互相干扰

当项目里 skills 多了之后，可能会出现“该触发 A 却触发了 B”的情况。这通常是因为两个 skill 的触发词有重叠。比如code-generator和code-review都包含“代码”这个关键词，用户说“帮我看看这段代码”时，可能触发的是生成而不是 review。

解决办法是在description里写清楚适用场景和不适用场景。比如code-review的 description 可以写“适用于对已有代码进行审查和优化建议，不适用于生成新代码”。另外，可以给 skill 设置优先级，在 frontmatter 里加一个priority字段，数值高的优先触发。

5.4 独家避坑技巧

第一个技巧是“渐进式细化”。不要一开始就写一个很复杂的 skill，先写一个最简版本，测试通过后再逐步添加细节。这样出问题的时候，容易定位是哪一步导致的。

第二个技巧是“保留调试日志”。在 skill 里加一个可选的debug参数，开启后把每一步的执行结果都输出到日志文件。这样当结果不对时，你可以回看每一步到底发生了什么。

第三个技巧是“版本管理”。Skills 文件一定要纳入 Git 管理，每次修改都提交。因为 skill 的调整往往需要多次迭代，没有版本记录的话，改着改着就忘了之前为什么那么写。

注意：Skills 的调试是一个反复迭代的过程，不要指望一次就能写出完美的 skill。我的经验是，一个中等复杂度的 skill，通常需要 5 到 10 次调整才能稳定工作。

6. 进阶玩法：把 skills 组合成工作流

6.1 用 skills 搭建自动化开发流水线

单个 skill 解决的是单点问题，但真正的效率提升来自于把多个 skill 串起来。比如你可以设计这样一条流水线：需求解析→代码生成→测试生成→代码审查→文档更新。每个环节是一个独立的 skill，通过一个“主控 skill”来协调执行顺序。

主控 skill 的写法是这样的：

--- name: dev-pipeline description: 完整的开发流水线，从需求到文档 trigger: 走流水线、完整开发、全流程 --- # 开发流水线 ## 执行顺序 1. 调用 `requirement-parser` 解析需求 2. 调用 `code-generator` 生成代码 3. 调用 `test-generator` 生成测试 4. 调用 `code-review` 进行审查 5. 调用 `doc-updater` 更新文档 ## 异常处理 - 任何一步失败，暂停流水线并报告错误 - 审查不通过时，回到代码生成步骤重新执行

这种流水线式的用法，特别适合重复性高的开发任务，比如“新增一个 CRUD 接口”这种有固定套路的场景。

6.2 skills 的分享与团队协作

Skills 写好了，怎么让团队其他人也能用？最直接的方式是把.claude/skills/目录提交到代码仓库，团队成员拉取后就能直接使用。但这里有一个问题：不同人的开发环境可能不同，比如有人用 Windows，有人用 macOS，路径分隔符不一样。解决办法是在 skill 里使用相对路径，并且用正斜杠/作为分隔符，大多数工具都能正确识别。

如果团队规模比较大，可以考虑把通用的 skills 抽出来，做成一个独立的仓库，通过plugin机制分发。这样不同项目可以按需引入，避免每个项目都复制一份。不过这种方式需要额外的配置工作，适合 skills 数量超过 20 个的团队。

6.3 从 skills 到 agents 的演进

当你积累了一定数量的 skills 之后，会自然产生一个想法：能不能让 AI 自己决定什么时候用什么 skill？这就是agents的概念。一个 agent 本质上是一组 skills 的集合，加上一个决策逻辑，能够根据当前任务自动选择合适的 skill 来执行。

比如你可以定义一个frontend-agent，它包含component-generator、style-helper、test-generator等 skills。当你对它说“帮我做一个登录页面”时，它会自动拆解任务：先用component-generator生成页面组件，再用style-helper添加样式，最后用test-generator补充测试。整个过程你只需要说一句话，剩下的由 agent 自动完成。

这种玩法目前还在早期阶段，不同工具的支持程度不一样。但方向是明确的：skills 是基础能力，agents 是能力编排。先把 skills 写好、调稳，再考虑往 agent 方向走，是比较务实的路径。

7. 我个人的一些实操体会

写了这么多 skills，踩过的坑确实不少。最大的一个体会是：skill 的质量取决于你对流程的理解深度。如果你自己都说不清楚一个任务应该分几步做、每步的输入输出是什么，那写出来的 skill 大概率也不好用。所以我现在写 skill 之前，会先拿纸笔把流程画一遍，确认每一步都清晰了，再动手写文件。

另一个体会是，不要追求大而全的 skill。我一开始写了一个“万能代码助手”的 skill，想把所有场景都覆盖进去，结果就是什么都不精。后来拆成了五六个小 skill，每个只做一件事，反而效果好得多。这跟写代码是一个道理：单一职责原则在 skills 设计里同样适用。

还有一个很实用的技巧：给 skill 加一个“自检”步骤。比如在生成代码的 skill 最后，加一步“检查生成的代码是否符合项目的 lint 规则”。这样即使 AI 在生成过程中有些小偏差，也能在自检环节被发现并修正。这个技巧帮我省了很多手动检查的时间。

最后说一个关于触发词的经验。我发现把触发词写成“用户可能会说的原话”比写成“规范术语”效果更好。比如用户更可能说“帮我搞个组件”而不是“请生成一个 React 函数式组件”。所以我现在写触发词的时候，会刻意加入一些口语化的表达，覆盖不同用户的说话习惯。