企业官网建设流程全解析

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

最近一段时间，不管是在开发者社区还是各类技术群聊里，"skills"这个词出现的频率高得离谱。很多人第一次看到它，会下意识以为是某种新的编程语言或者框架，其实不是。这里的 skills，指的是围绕 AI 编程助手（比如 Claude Code、Codex 这类工具）构建的一套可插拔能力扩展机制。你可以把它理解成给 AI 助手装的"技能包"——原本它只会聊天、写代码，装上 skills 之后，它能按照你预设的流程去查数据库、跑测试、生成规范文档、甚至调用外部工具完成一整套操作。

我最初接触这个概念的时候，也是懵的。因为"skills"这个词太泛了，泛到你在搜索引擎里敲进去，出来的结果从"安卓脱壳 skills"到"前任 skills 官方下载"什么都有。但真正有价值的那个方向，是AI Agent 的能力扩展。Claude Code 和 Codex 这两个工具，本质上都是把大模型包装成了一个能在你本地终端或编辑器里干活的"编程搭子"，而 skills 就是教这个搭子"遇到某类任务时该按什么套路出牌"的说明书。

为什么这件事值得单独拿出来讲？因为大多数人用 AI 编程助手的方式还停留在"我问它答"的阶段——你贴一段报错，它给你一段修复建议，然后你自己去改。这种用法效率提升有限，因为真正的瓶颈不在"生成代码"这一步，而在"理解上下文、执行多步操作、验证结果"这一整条链路上。skills 的价值就在于把这条链路固化下来，让 AI 从"顾问"变成"执行者"。

举个我自己的例子。之前每次让 AI 帮我写单元测试，都要反复交代项目用的测试框架、断言风格、mock 方式、目录结构。后来我把这些约定写成了一个 skill，之后只要说一句"给这个模块补测试"，它就能按照我项目里的规范直接产出可用的测试文件，连 import 路径都不会写错。这就是 skills 最朴素也最实用的价值：把重复的上下文交代，变成一次性的能力沉淀。

这篇文章适合谁看？如果你已经在用 Claude Code 或 Codex，但还停留在"聊天式"用法，那这篇能帮你把效率再往上提一个台阶。如果你还没开始用这类工具，也没关系，我会把安装、配置、skill 编写这些环节都拆开讲清楚，你跟着走一遍就能上手。全文会围绕 skills 的核心机制、实际编写方法、常见坑点、以及和 plugin、agents 这些概念的关系展开，尽量做到看完就能动手。

2. skills、plugin、agents 三个概念到底怎么区分

很多人一上来就被这三个词绕晕了。它们确实容易混，因为在实际使用中经常一起出现，而且不同工具的命名习惯还不一样。我用自己的理解方式给你捋一遍，不追求学术严谨，追求的是"你听完能分清"。

2.1 skills 是"怎么做"，agents 是"谁来做"

skills 本质上是一份操作指南。它描述的是"当遇到某类任务时，应该按照什么步骤、用什么工具、遵循什么规范去完成"。它不主动发起任务，也不决定什么时候被调用，它只是静静地躺在那里，等合适的时机被触发。

agents 则更像是一个执行主体。你可以把 agent 理解成一个有自主决策能力的"小助手"，它会根据当前任务判断该调用哪个 skill、该用什么工具、下一步该干什么。一个 agent 可以挂载多个 skills，就像一个人可以掌握多项技能一样。

打个比方：skills 是菜谱，agents 是厨师。菜谱告诉你"红烧肉要先用冰糖炒糖色"，但菜谱自己不会做菜；厨师会看菜谱，也会根据手头食材决定今天做红烧肉还是回锅肉。你给厨师配的菜谱越多，他能做的菜就越丰富。

2.2 plugin 是"装东西的盒子"

plugin 这个词在软件领域用得太久了，它的含义相对固定：一种把功能打包分发的形式。在 skills 的语境下，plugin 通常指的是把一组相关的 skills、配置、依赖打包成一个可安装的单元。你安装一个 plugin，可能一次性获得好几个 skills，外加一些预设的 agent 配置。

这里有个容易踩的坑：不同工具对 plugin 的定义边界不一样。有的工具里 plugin 就是 skill 的集合，有的工具里 plugin 还包含了 UI 扩展、命令注册等更重的东西。所以你在看文档的时候，别默认所有平台的 plugin 都是一个意思，一定要看具体工具的说明。

2.3 三者的协作关系

把这三个概念串起来看，一个典型的运行流程是这样的：

1. 你安装了一个 plugin，里面包含了若干个 skills 和一个预设的 agent 配置。
2. 你在对话里提出一个任务，比如"帮我重构这个函数"。
3. agent 接收到任务，判断这属于"代码重构"类操作。
4. agent 查找挂载的 skills，找到对应的重构 skill。
5. agent 按照 skill 里定义的步骤执行：先读代码、再分析依赖、然后生成新版本、最后跑测试验证。

这个流程里，skill 决定了"质量下限"——只要 skill 写得够细，AI 的输出就不会太离谱；agent 决定了"灵活上限"——好的 agent 能在 skill 覆盖不到的场景里做出合理判断。

理解了这三者的关系，后面讲 skill 编写的时候你就不会迷糊——我们写的每一份 skill，最终都是给某个 agent 用的，而它可能通过某个 plugin 被分发出去。

3. 一个 skill 文件里到底该写什么

这是最核心的部分。很多人第一次写 skill，写出来的东西要么太笼统（"帮我写好代码"），要么太琐碎（把每一行代码都规定死）。这两种都不对。一个好的 skill，应该像一份给聪明新人的交接文档——他知道怎么编程，但不了解你这个项目的特殊约定，你要把那些"只有老员工才知道"的东西告诉他。

3.1 skill 的基本结构

不同工具的 skill 格式略有差异，但核心要素是相通的。一个完整的 skill 通常包含这几块：

• 名称与描述：让 agent 知道这个 skill 是干什么的，什么时候该用它。
• 触发条件：什么情况下应该激活这个 skill。写得太宽会导致误触发，写得太窄会导致该用的时候用不上。
• 执行步骤：具体的操作流程，这是 skill 的主体。
• 约束与禁忌：哪些事绝对不能做，哪些边界不能越。
• 示例：给一两个输入输出的例子，帮助 agent 理解预期效果。

我见过太多 skill 只写了"执行步骤"，结果 agent 在不该用的时候用了，或者用了之后产出不符合预期。触发条件和约束这两块，往往比步骤本身更重要，因为它们决定了 skill 的适用边界。

3.2 描述怎么写才不会被误触发

触发条件这块，我的经验是：用"任务特征"而不是"关键词"来描述。比如你写一个"生成 API 文档"的 skill，如果你写"当用户提到文档时触发"，那用户说"这个文档写得不好"也会触发，这就错了。更好的写法是描述任务特征："当用户要求为某个模块或接口生成结构化说明文档，且需要包含参数、返回值、示例时触发"。

再比如，如果你有多个 skill 都涉及代码修改，那触发条件就要写得更精确，避免 agent 在多个 skill 之间反复横跳。我一般的做法是给每个 skill 加一个"不适用场景"的说明，明确告诉 agent 什么情况下不要用这个 skill。这招很管用，能挡掉大部分误触发。

3.3 执行步骤的颗粒度怎么把握

这是最考验经验的地方。步骤写太粗，agent 会自由发挥，产出不稳定；写太细，agent 会变成机械执行，遇到稍微不同的情况就卡住。

我的建议是：按"决策点"来划分步骤，而不是按"操作"来划分。什么意思？就是每一步应该对应一个需要判断的节点，而不是一个机械动作。

举个例子，写一个"修复 bug"的 skill：

不好的写法（按操作划分）：

1. 读取报错信息
2. 打开相关文件
3. 修改代码
4. 运行测试

好的写法（按决策点划分）：

1. 解析报错信息，判断错误类型（语法错误/逻辑错误/环境问题）
2. 根据错误类型定位相关代码范围
3. 分析根因，确认是代码问题还是配置问题
4. 如果是代码问题，生成修复方案并说明理由；如果是配置问题，给出配置调整建议
5. 修复后运行相关测试，确认问题解决且未引入新问题

看出区别了吗？好的写法里，每一步都包含"判断"和"分支"，agent 在执行时有了思考空间，而不是盲目照做。

3.4 约束与禁忌：那些"绝对不能做"的事

这部分经常被忽略，但它是保证 skill 安全性的关键。比如：

• 不要在没有备份的情况下删除文件
• 不要修改项目配置文件中的敏感字段
• 不要在未确认的情况下执行数据库写操作
• 不要引入项目里没有的新依赖

这些约束看起来是常识，但 AI 在执行任务时很容易"为了达成目标而走捷径"。明确写出来，能挡掉很多麻烦。我自己就遇到过一次，让 AI 帮我清理无用代码，结果它把一段看起来没用但实际上被反射调用的代码删了，导致运行时才报错。后来我在 skill 里加了一条"删除任何代码前，先搜索整个项目确认没有动态引用"，这类问题就再没出现过。

4. 从零写一个能用的 skill：完整实操

光讲理论没意思，我们直接动手写一个。假设你有一个前端项目，用的是 React + TypeScript，团队约定了一些代码规范。你想写一个 skill，让 AI 在帮你写组件时自动遵循这些规范。

4.1 先明确这个 skill 的边界

在动手之前，先问自己几个问题：

• 这个 skill 解决什么问题？——让 AI 生成的 React 组件符合团队规范。
• 什么时候触发？——当用户要求新建组件或修改组件结构时。
• 什么时候不触发？——当用户只是问概念、或者修改的是非组件文件时。
• 产出物是什么？——符合规范的 .tsx 文件，包含类型定义、样式、测试。

把这几个问题想清楚，skill 的骨架就有了。

4.2 写触发条件

触发条件我一般写成这样：

当用户要求创建新的 React 组件、或将现有代码重构为组件时激活。不适用于：纯逻辑函数、工具类、配置文件、样式文件的修改。

这样写的好处是，agent 能清楚知道边界在哪。如果用户说"帮我写个格式化日期的函数"，它就不会傻乎乎地去套组件模板。

4.3 写执行步骤

步骤部分，我按决策点来组织：

1. 确认组件类型：判断是展示型组件（纯 UI）还是容器型组件（含数据逻辑）。展示型组件不引入状态管理，容器型组件需要明确数据来源。
2. 确定文件位置：根据项目目录约定，展示型组件放在components/下，容器型组件放在containers/下。如果项目结构不同，先读取现有目录结构再决定。
3. 生成组件骨架：包含 import 语句、类型定义（Props 接口）、组件函数、导出语句。类型定义必须显式声明，不允许用any。
4. 处理样式：优先使用项目已有的样式方案（CSS Modules / styled-components / Tailwind），不引入新的样式库。
5. 补充测试：如果项目有测试目录，生成对应的测试文件，覆盖渲染和主要交互。
6. 自检：检查是否所有 Props 都有类型、是否有未使用的 import、是否符合命名规范。

每一步都包含判断，agent 执行时不会僵化。

4.4 写约束

约束部分我列了这么几条：

• 不引入项目 package.json 中未声明的依赖
• 不使用any类型，必要时用unknown加类型守卫
• 组件文件名使用 PascalCase，与组件名一致
• 不修改项目根目录下的配置文件
• 生成测试时，不 mock 掉被测组件本身

这些约束都是踩过坑之后总结出来的。比如"不使用 any"这条，是因为之前 AI 为了省事经常用 any 绕过类型检查，导致类型系统形同虚设。

4.5 加一个示例

示例部分我放了一个输入输出对照：

输入："帮我写一个用户头像组件，接收 url 和 size 两个属性"

输出：一个完整的 Avatar.tsx 文件，包含 Props 类型定义、默认 size 值、图片加载失败时的占位处理、以及对应的测试文件。

有了这个示例，agent 对"符合规范"的理解会准确很多。

5. 安装与配置环节最容易卡住的地方

skill 写好了，怎么让它生效？这一步看起来简单，实际上坑不少。我按常见工具分别说一下。

5.1 Claude Code 的 skill 加载机制

Claude Code 加载 skill 的方式，通常是把 skill 文件放在指定的目录下，然后在配置里声明。这里最容易出问题的是路径问题。很多人把 skill 文件放错目录，或者配置里写的路径和实际路径不一致，导致 skill 根本不生效，但工具又不会报错，你就一直纳闷为什么 AI 不按套路出牌。

我的建议是：配置完之后，先用一个明确的测试任务验证 skill 是否被加载。比如你的 skill 是管组件生成的，那就直接让它生成一个组件，看产出是否符合规范。如果不符合，先检查路径，再检查触发条件是不是写得太窄。

另一个常见问题是编码格式。skill 文件如果是中文内容，一定要确保是 UTF-8 编码，否则可能出现乱码导致解析失败。这个问题在 Windows 环境下尤其常见。

5.2 Codex 的 skill 配置

Codex 这边的配置逻辑类似，但它在 skill 的组织方式上可能更偏向于"项目级"配置——也就是 skill 跟着项目走，而不是全局生效。这样做的好处是不同项目可以用不同的 skill 集，不会互相干扰；坏处是你换一个项目就得重新配一遍。

我的做法是维护一个"基础 skill 库"，放在一个公共目录里，然后在各个项目的配置里引用。这样既保证了复用，又保留了项目级的定制空间。

5.3 本地模型接入时的注意事项

有些人会用本地模型来跑这些工具，这时候 skill 的生效情况可能会受影响。因为不同模型对指令的遵循程度不一样，有些小模型对复杂的 skill 描述理解不到位，执行时会打折扣。

如果你用的是本地模型，建议把 skill 写得更直白一些，减少抽象描述，多用具体例子。另外，skill 的长度也要控制，太长的 skill 在小模型上容易被截断或忽略后半部分。我一般会把核心约束放在 skill 的开头，确保即使后面被截断，关键信息也已经传达。

5.4 验证 skill 是否生效的土办法

除了直接跑任务看结果，我还有一个土办法：在 skill 里加一条"激活时输出一行提示"的指令。比如让 agent 在应用这个 skill 时先说一句"正在使用 XX 规范生成组件"。这样你一眼就能看出 skill 有没有被触发。等确认没问题了，再把这行提示去掉。

这个方法虽然笨，但特别有效，尤其是在调试触发条件的时候。

6. 那些让我踩过坑的细节

写 skill 这件事，看别人写觉得挺简单，自己上手才知道坑有多密。我挑几个印象最深的说说。

6.1 触发条件写太宽，导致 skill 到处乱入

我最早写的一个 skill 是管代码格式的，触发条件写的是"当涉及代码修改时"。结果不管我让它干什么，它都要先给我讲一遍格式规范，烦得不行。后来改成"当用户明确要求格式化代码、或生成的代码需要符合项目风格时"，才消停。

这个坑的本质是：AI 对"涉及"这个词的理解比人宽泛得多。你觉得"涉及代码修改"是指"主要任务是改代码"，它理解成"只要提到代码就算"。所以触发条件要用具体的任务描述，别用模糊的动词。

6.2 skill 之间互相冲突

当你装了多个 skill，它们之间可能会打架。比如一个 skill 说"生成代码时要加详细注释"，另一个 skill 说"保持代码简洁，避免冗余注释"。AI 遇到这种情况会随机选一个，或者干脆两个都不听。

解决办法是给 skill 分优先级，或者在触发条件里明确互斥关系。我一般的做法是：把通用性强的 skill 设为低优先级，把场景特定的 skill 设为高优先级，这样特定场景下会覆盖通用规则。

6.3 skill 更新后不生效

这个坑很隐蔽。你改了 skill 文件，但工具可能缓存了旧版本，导致新内容不生效。不同工具的缓存机制不一样，有的需要重启，有的需要手动清缓存。

我的习惯是：每次改完 skill，先重启一次工具，再做验证。虽然麻烦，但能避免"改了跟没改一样"的困惑。另外，如果你用的是版本控制，记得确认改的是当前生效的那个分支的文件，别改了半天改的是另一个副本。

6.4 过度依赖 skill 导致灵活性下降

这是理念层面的坑。skill 用多了，你会不自觉地想把所有事情都流程化，结果遇到 skill 覆盖不到的场景时，AI 反而不知道怎么处理了。

我的经验是：skill 应该覆盖高频、标准化程度高的任务，低频、需要灵活判断的任务还是交给 agent 自由发挥。比如"生成 CRUD 接口"这种高度模式化的任务适合写 skill，"设计系统架构"这种需要权衡的任务就不适合。

7. skill 写得好不好，看这几个信号

最后说说怎么判断一个 skill 的质量。我总结了几个信号，你可以拿来对照自己的 skill。

信号一：AI 的输出是否稳定。同一个任务跑三次，如果产出结构、风格、质量都差不多，说明 skill 约束到位了；如果每次都不一样，说明 skill 写得太松。

信号二：是否减少了你的重复交代。好的 skill 应该让你不用再反复说"记得加类型""记得写测试"这类话。如果你发现还是得每次提醒，说明 skill 没覆盖到这些点。

信号三：是否减少了返工。如果 AI 按 skill 产出的东西你基本不用改，或者只改少量细节，说明 skill 的规范定义得准；如果每次都要大改，说明 skill 里的规范和你实际想要的不一致。

信号四：是否容易维护。skill 不是写完就完了，项目规范变了、工具升级了，skill 都得跟着改。如果一个 skill 写得特别复杂、牵一发动全身，那维护成本就太高了。我倾向于把 skill 拆小，每个 skill 只管一件事，这样改起来影响面小。

信号五：新人能不能看懂。这个信号有点反直觉，但很管用。如果你的 skill 拿给一个不熟悉项目的人看，他能大致明白"哦，原来这个项目是这么干的"，那说明 skill 写得清晰；如果他自己都看不懂，那 AI 大概率也理解不到位。

说到底，skill 的本质是把你的隐性知识显性化。你脑子里那些"我们项目就是这么干的"的约定，通过 skill 变成了 AI 能读懂的文档。这个过程本身就有价值，因为它逼着你把模糊的经验整理成清晰的规则。哪怕你最后不用 AI，这份整理出来的规范对团队也是有用的。

我现在维护着十几个 skill，覆盖了组件生成、接口对接、测试编写、文档产出等场景。它们不是一次写完的，而是每次遇到"AI 又没按我想的来"的时候，就补一条规则进去。慢慢地，AI 越来越像团队里的老成员，而不是一个需要反复调教的新人。这个过程没什么捷径，就是不断用、不断改、不断沉淀。