企业官网建设流程全解析

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

最近一段时间，不管是在开发者社区还是各种技术群里，"skills"这个词出现的频率高得离谱。很多人第一次看到它，会以为是某个新出的编程语言特性，或者是某个框架里的功能模块。但如果你真的去翻一翻相关的讨论，会发现大家嘴里的"skills"其实指向一个很具体的东西——给 AI 编程助手（比如 Claude Code、Codex 这类工具）扩展能力的插件化技能包。

我最早接触这个概念的时候也走了弯路。当时我以为 skills 就是普通的插件，装上去就能用。结果折腾了半天才发现，它的设计思路和传统插件完全不是一回事。传统插件往往是往宿主程序里注入代码、挂载钩子，而 skills 更像是一份"给 AI 看的说明书"——它用结构化的方式告诉 AI：在什么场景下、该调用什么工具、按什么步骤执行、输出什么格式。这个区别非常关键，直接决定了你写出来的 skill 到底能不能被正确触发。

为什么这个东西会突然火起来？我的判断是三个原因叠加。第一，AI 编程助手已经过了"能写代码就行"的阶段，大家开始要求它稳定、可控、可复用；第二，通用大模型在面对具体业务时，总是差那么一口气，而 skills 正好是补这口气的低成本手段；第三，社区里已经有人把好用的 skills 沉淀下来，形成了事实上的"技能市场"，后来者可以直接抄作业。

这篇文章我想聊的不是某个具体 skill 怎么装，而是把 skills 这套机制从底层逻辑到落地实操完整拆一遍。包括它和 plugin、agents 的关系，怎么写一个能被稳定触发的 skill，怎么在 Claude Code 和 Codex 里配置，以及我在实际使用中踩过的那些坑。不管你是刚听说这个词的新手，还是已经写过几个 skill 但总觉得触发不稳定的老手，应该都能从里面找到点有用的东西。

2. skills、plugin、agents 三者到底是什么关系

很多人一上来就被这三个词绕晕了。我在群里见过不止一个人问："skills 和 plugin 是不是一回事？agents 又是什么？"要搞清楚这个，得先理解它们各自在系统里扮演的角色。

2.1 用"公司"来类比这三个概念

我习惯用一个类比来解释：把 AI 编程助手想象成一家公司。

agents（智能体）是这家公司的"员工"。每个 agent 有自己的职责范围，比如有的专门负责写前端组件，有的专门负责排查后端 bug，有的专门负责写测试。agent 是执行任务的主体，它有自主决策的能力，会根据当前情况选择下一步做什么。

skills（技能）是员工脑子里的"操作手册"。一个 agent 可能掌握很多技能，比如"如何用 React 写一个表单""如何用 pytest 组织测试用例""如何做数据库迁移"。skills 本身不主动执行，它是被 agent 在需要的时候调用的知识包。

plugin（插件）则是公司给员工配的"工具和设备"。比如给员工配一台更好的电脑、装一个专用的调试器、接一个外部的 API 服务。plugin 扩展的是 agent 的"能力边界"，让它能接触到原本接触不到的东西。

这个类比不一定百分百精确，但能帮你快速建立直觉：agent 是主体，skill 是知识，plugin 是工具。三者配合起来，才能让 AI 助手在复杂任务里表现得像个靠谱的工程师，而不是一个只会背代码的复读机。

2.2 为什么 skills 是三者里最值得投入的

从投入产出比来看，我认为 skills 是普通开发者最应该花时间的地方。原因很简单：

• 写 plugin 门槛高。你得懂宿主程序的扩展机制，要处理生命周期、依赖注入、版本兼容，一不小心就把整个环境搞崩。
• 调 agent 成本大。agent 的行为涉及提示词工程、工具编排、状态管理，调不好就是"看起来很智能，实际上一团乱"。
• 写 skill 门槛低、收益直接。一个 skill 本质上就是一份结构化的 Markdown 加少量配置，你只要把"什么场景触发、按什么步骤做、注意什么"写清楚，就能显著提升 AI 在特定任务上的稳定性。

我自己的经验是，一个写得好的 skill，能把某类任务的返工率从"每次都要手动纠正"降到"基本一次过"。这个提升是实打实的，而且不需要你懂多少底层原理。

2.3 三者的协作流程长什么样

举个具体例子。假设你要让 AI 帮你把一个老项目的构建脚本从 Maven 迁移到 Gradle。

• agent 接到任务，判断这属于"构建系统迁移"类别。
• agent 检索自己掌握的 skills，发现有一个叫maven-to-gradle-migration的 skill 匹配当前场景。
• agent 加载这个 skill，按照里面定义的步骤执行：先分析现有 pom.xml 的依赖树，再生成对应的 build.gradle，然后处理插件差异，最后跑一次构建验证。
• 执行过程中如果需要读取远程仓库信息，agent 调用对应的 plugin 去访问外部服务。
• 整个过程结束后，agent 根据 skill 里定义的输出格式，给你一份迁移报告。

你看，skill 在这里起的是"流程编排 + 知识注入"的作用。它不直接干活，但它决定了 agent 干活的方式和顺序。这就是为什么我说 skills 是最值得投入的一环——它直接决定了 AI 的输出质量。

3. 一个 skill 的内部结构：从触发条件到输出格式

理解了定位，接下来要拆的是 skill 本身长什么样。很多人写 skill 失败，根本原因是没搞清楚一个 skill 到底由哪几部分组成，导致写出来的东西要么触发不了，要么触发了但执行得乱七八糟。

3.1 skill 的四个核心组成部分

根据我的实践，一个能稳定工作的 skill 通常包含四个部分：

第一部分是元信息（metadata）。这部分定义了 skill 的名字、描述、适用场景、触发关键词。名字要短且有辨识度，描述要能让 agent 快速判断"这个 skill 是不是当前任务需要的"。我见过很多人把描述写得特别笼统，比如"帮助处理代码相关任务"，这种描述等于没写，agent 根本没法判断该不该用。

第二部分是触发条件（trigger）。这部分明确告诉 agent：当用户输入包含哪些特征时，应该加载这个 skill。触发条件可以基于关键词、文件类型、任务类型，甚至是上下文状态。写得越具体，触发越精准。

第三部分是执行步骤（procedure）。这是 skill 的主体，用自然语言加结构化格式描述"第一步做什么、第二步做什么"。步骤要足够细，细到 agent 不需要自己发挥就能照着做。但也不能太死板，要留出应对异常情况的空间。

第四部分是输出规范（output spec）。这部分定义 skill 执行完后应该产出什么。是生成一个文件？还是输出一段报告？格式是什么？有没有必须包含的字段？这部分经常被忽略，但它直接决定了结果能不能被后续流程消费。

3.2 触发条件为什么是最容易翻车的地方

我踩过最大的坑就在触发条件上。早期我写了一个专门处理"数据库索引优化"的 skill，描述写得很详细，步骤也很完整。但实际用的时候发现，十次里有七八次它根本不触发，agent 直接用自己的通用知识去回答了。

排查了很久才找到原因：我的触发条件写得太"学术"了。我用的词是"索引选择性分析""查询计划优化"这类术语，但用户实际提问时说的是"这个查询怎么这么慢""数据库卡死了怎么办"。触发词和实际输入对不上，skill 自然就哑火了。

后来我调整了策略，在触发条件里同时包含三类词：

• 专业术语：索引、执行计划、慢查询
• 口语表达：卡、慢、跑不动、等半天
• 场景描述：数据量大了之后、上线之后变慢

调整完之后触发率明显上来了。这个经验告诉我，触发条件要覆盖用户"可能怎么说"，而不是你"希望他怎么说"。

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

另一个常见问题是步骤粒度。写太粗，agent 会自由发挥，结果不可控；写太细，又变成了死板的脚本，遇到一点变化就卡住。

我的经验是采用"目标 + 约束 + 示例"的三层结构：

• 每一大步给出明确目标，比如"分析现有依赖冲突"。
• 给出约束条件，比如"优先保留直接依赖，间接依赖可以升级"。
• 给一个具体示例，比如"如果 A 依赖 B 的 1.x，C 依赖 B 的 2.x，优先尝试统一到 2.x"。

这样 agent 既知道要干什么，又知道边界在哪，还能参考示例处理类似情况。比单纯列步骤要灵活得多。

3.4 输出规范决定了 skill 能不能被复用

输出规范这块我想多说两句。很多人写 skill 只关注"能不能完成任务"，不关注"输出能不能被下一步用"。结果就是每次执行完，还得人工整理一遍结果，效率提升有限。

一个好的输出规范应该包含：

把这张表填清楚，你的 skill 输出就能直接被下游流程消费，比如自动生成工单、自动发通知、自动归档。这才是 skill 真正的价值所在。

4. 在 Claude Code 和 Codex 里落地 skills 的实操路径

理论讲完了，接下来是动手环节。这部分我会分别讲 Claude Code 和 Codex 两个环境下的配置方式，以及一些通用的调试技巧。需要说明的是，这两个工具都在快速迭代，具体命令可能会变，但核心思路是相通的。

4.1 Claude Code 环境下的 skill 安装与配置

Claude Code 对 skills 的支持相对成熟，安装方式主要有两种。

第一种是通过官方市场安装。如果你能访问官方市场，直接搜索 skill 名字安装就行，这是最省事的方式。安装完之后，skill 会被放到用户配置目录下的 skills 文件夹里，Claude Code 启动时会自动加载。

第二种是手动放置。当你从社区拿到一个 skill 包，或者自己写了一个，可以手动放到对应目录。目录结构通常是这样的：

~/.claude/skills/ ├── my-skill/ │ ├── SKILL.md │ ├── config.json │ └── examples/ └── another-skill/ └── SKILL.md

其中SKILL.md是核心文件，里面就是前面说的元信息、触发条件、执行步骤、输出规范。config.json是可选的，用来定义一些参数。examples/目录放示例输入输出，帮助 agent 理解预期效果。

放好之后，重启 Claude Code，用/skills之类的命令（具体命令看版本）查看已加载的 skill 列表，确认你的 skill 出现在里面。

注意：手动放置 skill 时，目录名和 SKILL.md 里定义的名字最好保持一致，否则某些版本会出现加载了但识别不到的情况。我因为这个排查了半小时。

4.2 Codex 环境下的 skill 接入

Codex 这边的机制略有不同。它更强调 skill 和 agent 的绑定关系，也就是说，你需要先定义 agent，再给 agent 挂载 skill。

基本流程是这样的：

1. 在 Codex 的配置目录下创建 agent 定义文件，声明这个 agent 的职责范围。
2. 在 agent 定义里引用需要的 skill，可以引用多个。
3. 启动 Codex 时指定使用哪个 agent，对应的 skills 就会被加载。

Codex 的一个好处是它对 skill 的版本管理比较友好，你可以在配置里指定 skill 的版本号，避免因为 skill 更新导致行为突变。这在团队协作场景下特别有用。

另一个需要注意的是，Codex 对 skill 的描述字段解析比较严格，格式不对会直接报"unrecognized configuration setting"之类的错误。遇到这种报错，先检查你的配置文件缩进和字段名，八成是格式问题。

4.3 本地模型接入时的 skill 适配

有些朋友会用本地模型来跑 Claude Code 或 Codex，这时候 skills 的适配会有点不一样。

本地模型的上下文窗口通常比云端模型小，所以 skill 里的步骤描述要更精简，避免一次性塞太多内容导致截断。我的做法是把 skill 拆成"核心步骤"和"扩展参考"两部分，核心步骤常驻上下文，扩展参考按需加载。

另外，本地模型对结构化格式的遵循能力可能弱一些，所以输出规范要写得更明确，最好给出完整的输出示例，让模型照着套。

4.4 调试 skill 的通用方法

不管你用哪个环境，调试 skill 的思路是相通的。我总结了一个"三步排查法"：

第一步，确认 skill 被加载了。查看 skill 列表，确认你的 skill 在里面。如果不在，检查目录位置和文件格式。

第二步，确认 skill 被触发了。在对话里输入一个明显应该触发该 skill 的问题，观察 agent 的响应里有没有引用 skill 的迹象。如果没有，问题出在触发条件上，回去调整触发词。

第三步，确认 skill 执行正确。如果触发了但结果不对，逐段检查执行步骤，看是哪一步 agent 理解偏了。常见原因是步骤描述有歧义，或者缺少异常处理分支。

这三步走下来，大部分问题都能定位。我见过有人一上来就怀疑是工具 bug，折腾半天重装环境，结果发现是 skill 里一个标点符号写错了导致解析失败。先做基础排查，能省很多时间。

5. 写一个高质量 skill 的实战心得

前面讲的都是"是什么"和"怎么配"，这一节我想聊聊"怎么写好"。这部分内容在官方文档里基本找不到，都是我在实际写了几十个 skill 之后攒下来的经验。

5.1 从"我平时怎么做"倒推 skill 结构

写 skill 最好的起点不是打开编辑器，而是回忆你自己做这件事的流程。比如你要写一个"代码审查"的 skill，先别急着写，拿一张纸，把你平时审查代码时的步骤列出来：

• 先看改动范围大不大
• 再看有没有明显的逻辑错误
• 然后看命名和注释是否清晰
• 接着看有没有遗漏的边界情况
• 最后看测试覆盖够不够

这个列表就是你 skill 执行步骤的雏形。因为这是你真实的工作流程，所以它天然是合理的、可执行的。比凭空设计一套"理想流程"要靠谱得多。

5.2 给 skill 加上"止损点"

这是我踩坑之后学到的最重要的一课。早期我写的 skill 都是"一路向前"的，假设所有条件都满足。结果遇到异常情况时，agent 会硬着头皮往下走，产出完全不可用的结果。

后来我在每个关键步骤后面都加了"止损点"，也就是明确告诉 agent：如果出现某种情况，就停下来，报告问题，不要继续。

比如在"依赖升级"的 skill 里，我会写：

如果升级后出现编译错误，且错误涉及核心模块，停止后续步骤，输出错误详情和受影响的模块列表，等待人工确认。

这个止损点看起来简单，但它把"agent 自作主张搞出一堆问题"变成了"agent 发现问题及时上报"。对于生产环境来说，这个区别是致命的。

5.3 用真实案例喂养 skill

skill 里的示例部分，一定要用真实案例，不要编。我见过有人为了省事，示例里写的是"假设有一个函数 foo，它做了 bar 操作"这种占位内容。这种示例对 agent 几乎没有帮助，因为它不包含真实世界的复杂性。

我的做法是，每写一个 skill，就从自己过去的项目里找一个真实场景作为示例。包括真实的输入、真实的中间过程、真实的输出。这样 agent 在学习这个 skill 时，接触到的是"真实世界长什么样"，而不是"教科书里长什么样"。

5.4 版本管理和迭代节奏

skill 不是写完就完事的，它需要持续迭代。我的建议是：

• 每个 skill 都带版本号，放在元信息里。
• 每次修改都记录变更原因，哪怕只是一句话。
• 定期回顾触发率，如果某个 skill 长期不触发，要么是触发条件有问题，要么是这个 skill 根本不需要。

我自己的 skills 目录里，有一半以上的 skill 都经历过至少三次修改。第一次写出来能用，第二次调整触发条件，第三次补充异常处理。迭代是常态，别指望一次写完美。

6. 那些年我在 skills 上踩过的坑

这一节专门讲踩坑，因为我觉得这些经验比正面教程更有价值。下面这些坑，有的是我自己踩的，有的是帮别人排查时遇到的，都是真实案例。

6.1 触发词写得太"聪明"导致不触发

前面提过一次，这里再展开说。有个朋友写了一个"API 文档生成"的 skill，触发词写的是"OpenAPI 规范解析""Swagger 注解提取"这类专业词。结果用户实际提问是"帮我把这些接口整理成文档"，完全不匹配，skill 从来不触发。

这个坑的本质是：写 skill 的人和使用 skill 的人，语言习惯往往不一样。写的人偏专业，用的人偏口语。解决办法就是在触发词里同时覆盖两种表达，甚至三种（专业、口语、场景）。

6.2 步骤之间缺少状态传递

这个坑比较隐蔽。我写过一个多步骤的 skill，第一步分析问题，第二步生成方案，第三步验证方案。单独看每一步都没问题，但连起来跑就出乱子——因为第二步不知道第一步分析出了什么，第三步不知道第二步生成了什么。

后来我在 skill 里显式定义了"中间产物"的概念，要求每一步把结果写到指定的临时位置，下一步从那里读取。这样步骤之间就有了明确的状态传递，不会再各干各的。

6.3 输出格式和下游不兼容

有一次我写了一个"日志分析"的 skill，输出是自然语言描述。结果下游的告警系统需要结构化数据，根本没法消费。只能返工，把输出改成 JSON。

这个坑的教训是：写 skill 之前，先想清楚输出给谁用。如果只是给人看，自然语言没问题；如果要给系统消费，就必须结构化。别等到写完了才发现格式不对。

6.4 忽略权限和边界

有些 skill 会涉及文件读写、命令执行这类操作。如果不明确声明权限边界，agent 可能会做出超出预期的操作。我见过一个 skill 因为没限制写入范围，结果把用户的项目文件覆盖了。

所以涉及副作用的 skill，一定要在配置里明确声明：能读哪些目录、能写哪些目录、能执行哪些命令。宁可限制得严一点，也不要留隐患。

6.5 在错误的层级解决问题

最后一个坑比较抽象，但很重要。有些人遇到 AI 输出不稳定，第一反应是去调 agent 的提示词，或者换模型。但实际上，很多问题的根源在 skill 层面——是 skill 的步骤描述有歧义，或者触发条件不清晰。

我的经验是，先检查 skill，再检查 agent，最后才考虑换模型。因为 skill 是最容易改、改动成本最低的一层。把这一层做扎实了，很多问题自然就消失了。

7. 关于 skills 的一些延伸思考

写到这里，核心内容基本讲完了。最后我想聊几个延伸话题，算是给这个领域再补一点视角。

7.1 skills 会不会成为新的"技术债"

我有个担忧：随着 skills 越来越多，会不会出现"skill 泛滥"的问题？就像当年 npm 包一样，一开始大家觉得方便，后来发现依赖树深不见底，维护成本高得吓人。

我的建议是，对 skills 也要有"断舍离"的意识。定期清理不再使用的 skill，合并功能重叠的 skill，保持 skill 库的精简。一个只有二十个高质量 skill 的库，比一个有两百个半成品 skill 的库要有价值得多。

7.2 团队协作下的 skill 管理

如果是团队使用，skills 的管理就更重要了。我的做法是：

• 建立一个共享的 skill 仓库，所有人从这里取用。
• 每个 skill 有明确的负责人，负责维护和更新。
• 定期做 skill 评审，淘汰低质量的，推广高质量的。
• 建立 skill 使用反馈机制，用的人可以提改进建议。

这样 skills 就从"个人收藏"变成了"团队资产"，价值会放大很多。

7.3 从 skills 看 AI 工具的未来形态

我个人的判断是，未来的 AI 编程工具会越来越像"操作系统"，而 skills 就是上面的"应用程序"。操作系统提供基础能力，应用程序解决具体问题。谁掌握了高质量的 skills，谁就能让 AI 工具发挥出更大的价值。

这个趋势对普通开发者来说其实是好事。因为写 skill 不需要你懂多深的底层原理，只需要你对自己的工作流程足够熟悉。把熟悉的事情结构化地表达出来，这就是 skill 的核心。门槛不高，但天花板很高。

我在实际使用中最大的体会是：skills 的价值不在于它多智能，而在于它多稳定。一个能稳定触发、稳定执行、稳定输出的 skill，比一个偶尔惊艳但经常翻车的 skill 要有用得多。追求稳定，而不是追求炫技，这是我写了几十个 skill 之后最想分享的一句话。

如果你刚开始接触 skills，我的建议是从一个小场景入手，写一个最简单的 skill，跑通整个流程，然后再逐步扩展。别一上来就想着写一个"万能 skill"，那基本不可能成功。从一个具体问题开始，解决它，然后再解决下一个。这个过程本身就是最好的学习。