企业官网建设流程全解析

1. 从"skills"这个模糊词说起：它到底指什么

第一次看到"skills"这个标题，很多人会懵。它太泛了，泛到像是随手敲的一个占位符。但结合热搜词里高频出现的 Claude Code、Codex、agents、plugin 这些词，方向其实很明确——这里说的 skills，指的是 AI 编程助手（尤其是 Claude Code、Codex 这类 agent 工具）里的技能扩展机制，也就是让 agent 在基础能力之外，按需加载特定领域知识、工具调用流程、操作规范的一套模块化方案。

打个比方。基础的大模型 agent 就像一个刚入职的聪明应届生，脑子好使，但对你们公司的代码规范、部署流程、内部工具链一无所知。skills 就是给他的一本本"岗位操作手册"——遇到写数据库迁移的时候翻哪本，遇到排查线上日志的时候翻哪本，遇到前端组件规范的时候翻哪本。手册不是一次性全塞给他，而是按需触发、按需加载，这样既不撑爆上下文窗口，又能保证在具体任务上足够专业。

这套机制解决的核心痛点有三个。第一是上下文经济性：一个 agent 的上下文窗口再大也是有限的，把所有领域知识一股脑塞进 system prompt，既浪费 token 又稀释注意力。skills 把知识拆成独立模块，只在相关任务出现时才注入。第二是可复用性：一个团队沉淀下来的最佳实践，可以打包成 skill 在成员之间共享，不用每个人重新踩坑。第三是可维护性：某个流程变了，只改对应的 skill 文件，不用动整个 agent 配置。

适合读这篇内容的人，我大致分三类。一类是已经在用 Claude Code 或 Codex 做日常开发，但还停留在"对话式问答"阶段，没意识到可以给它装技能包的开发者。一类是想给团队搭建统一 AI 辅助工作流的 tech lead，需要知道 skills 怎么组织、怎么分发。还有一类是纯粹好奇 agent 扩展机制原理的技术爱好者，想搞清楚"skills 和 plugin 到底啥区别"。

需要先说明一点：skills 这个概念在不同工具里的实现细节不完全一样。Claude Code 有它自己的一套 skill 目录约定，Codex 的扩展方式又有所不同，社区里还有各种第三方封装的 skills 市场。下面我尽量讲通用的机制和思路，具体到某个工具时会点明差异。所有涉及具体配置的部分，都是基于常见实践的合理还原，你实际用的时候以官方文档为准。

2. skills 与 plugin、agent 的边界：别把三个概念搅在一起

热搜词里 skills、plugin、agents 三个词经常一起出现，很多人第一次接触会以为是一回事。实际上它们处在不同的抽象层级，搞清楚这个层级关系，后面配置的时候才不会乱。

2.1 三者的职责划分

我用一个不太严谨但好记的类比：agent 是员工，plugin 是员工能用的外部工具，skill 是员工脑子里的操作手册。

agent 是执行主体，它负责理解你的意图、规划步骤、决定调用什么。plugin 是能力扩展，通常对应一个具体的外部接口或工具——比如读文件、跑命令、查数据库、调某个 API。skill 则是知识扩展，它不直接提供新能力，而是告诉 agent"在什么场景下、按什么顺序、用哪些 plugin、注意哪些坑"。

举个具体例子。你要 agent 帮你做一次数据库 schema 变更。plugin 层面，它需要"执行 SQL"和"读文件"这两个工具。skill 层面，它需要知道：先备份、再在事务里执行、变更前检查是否有长事务锁表、变更后验证索引是否生效。这些步骤不是 plugin 能提供的，是知识，是经验，是 skill 该装的东西。

2.2 为什么 skill 要独立于 plugin 存在

有人会问：既然 skill 就是一堆操作步骤，为什么不直接写进 plugin 的描述里，或者干脆写进 agent 的 system prompt？

写进 plugin 描述的问题在于，plugin 是通用的，一个"执行 SQL"的工具不该内置"我们公司的变更规范"。工具要保持中立，规范要独立可替换。写进 system prompt 的问题更明显：system prompt 是常驻的，每次对话都占上下文，而你不可能同时需要前端规范、后端规范、运维规范、数据规范——大部分时候只需要其中一个。skill 的按需加载正好解决这个矛盾。

这也是为什么 skills 机制在 Claude Code 这类工具里被设计成"目录扫描 + 描述匹配"的模式：agent 启动时只读取每个 skill 的简短描述（name + description），判断当前任务和哪个 skill 相关，相关才把完整内容读进来。这个设计思路和 RAG 的检索增强很像，只不过检索的是本地文件，触发靠的是模型自己的判断而不是向量相似度。

2.3 一个容易踩的认知坑

我见过不少人把 skill 当成"提示词模板"来用，写了一大段"你是一个资深 XX 工程师，请遵循以下规范……"。这样写不是不行，但浪费了 skill 机制最大的价值——触发条件。

好的 skill 应该有一个清晰的"什么时候用我"的描述。比如"当用户要求进行数据库 schema 变更、迁移脚本编写或索引调整时使用本技能"，而不是"本技能包含数据库相关知识"。前者让 agent 能准确判断该不该加载，后者会让 agent 要么漏加载、要么乱加载。这个细节后面讲编写规范时还会展开。

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

理解了定位，接下来是实操。一个 skill 文件的结构，直接决定了它好不好用、会不会被正确触发。我按重要性从高到低拆。

3.1 元信息：name 和 description 是命门

几乎所有 skills 实现都要求每个 skill 有一个名字和一段描述。这两个字段是 agent 决定"要不要加载这个 skill"的唯一依据，所以它们的重要性远超正文。

name 要短、要具体、要能一眼看出领域。db-migration比database好，react-component-style比frontend好。避免用utils、helpers、misc这种一看就不知道干嘛的名字。

description 的写法有个实用套路："当……时使用本技能，它包含……"。前半句写触发场景，后半句写能力范围。举几个我实际用下来触发比较准的例子：

• 当需要编写或审查数据库迁移脚本时使用，包含变更前检查清单、事务边界规范、回滚方案模板。
• 当处理 React 组件的样式组织、命名和目录结构时使用，包含团队约定的 CSS 方案选型与组件拆分原则。
• 当排查线上服务超时、连接池耗尽或慢查询时使用，包含分层排查顺序和常用诊断命令。

注意这些描述都带了明确的动作词（编写、审查、处理、排查），因为 agent 判断相关性时，任务里的动词是强信号。如果你的 description 全是名词堆砌，触发率会明显下降。

3.2 正文：流程、检查清单、反例

正文部分我建议按"流程 + 检查清单 + 反例"三段式来组织，这是从实际使用中总结出来的，比单纯罗列知识点有效得多。

流程部分写"第一步做什么、第二步做什么"，最好带上判断分支。比如数据库迁移的 skill，流程可能是：先确认变更类型（加字段/改类型/加索引）→ 不同类型走不同检查项 → 生成脚本 → 本地验证 → 提交。agent 拿到这个流程，执行起来就有章法，不会东一榔头西一棒子。

检查清单部分写"做完之后必须确认的事"。这部分用无序列表最合适，每条一个可验证的点。比如"确认迁移脚本在空库和存量库上都能跑通""确认回滚脚本已同步编写""确认变更期间没有长事务"。清单的价值在于它把隐性经验显性化了，新人（包括 AI）照着勾就行。

反例部分最容易被忽略，但恰恰最有价值。写清楚"不要这样做"以及"为什么"。比如"不要在业务高峰期执行大表 DDL，因为会锁表导致请求堆积""不要在迁移脚本里混入数据修复逻辑，因为回滚时会出问题"。反例能帮 agent 避开那些它凭常识想不到的坑。

3.3 一个可参考的 skill 文件骨架

下面这个骨架是我自己常用的，你可以直接拿去改。注意这是通用结构，具体到 Claude Code 或 Codex 时字段名可能略有差异。

--- name: db-migration description: 当需要编写或审查数据库迁移脚本时使用，包含变更前检查清单、事务边界规范、回滚方案模板。 --- ## 适用场景 - 新增/修改/删除表字段 - 新增/删除索引 - 数据回填脚本 ## 执行流程 1. 确认变更类型，判断是否属于大表 DDL 2. 大表 DDL 走在线变更工具，小表可直接执行 3. 编写正向脚本与回滚脚本 4. 在预发环境验证 5. 提交并附上变更说明 ## 检查清单 - [ ] 回滚脚本已编写并验证 - [ ] 变更期间无长事务 - [ ] 索引变更评估过对写入的影响 - [ ] 脚本幂等，可重复执行 ## 反例 - 不要在迁移脚本里混入业务数据修复 - 不要省略回滚脚本，哪怕"这次肯定不回滚" - 不要在业务高峰期执行大表 DDL

这个骨架的关键在于：元信息精准、流程可执行、清单可验证、反例有理由。四样齐了，一个 skill 基本就立住了。

4. 让 skill 真正被触发：几个反直觉的细节

写完 skill 只是第一步，能不能被 agent 在对的时候加载进来，是另一回事。这块我踩过的坑最多，单独拎出来讲。

4.1 描述写太宽，反而不会被触发

直觉上，description 写得越宽泛，覆盖的场景越多，触发率应该越高。实际恰恰相反。如果你写"当处理任何编程相关任务时使用"，agent 会觉得这个 skill 太泛，反而倾向于不加载——因为它判断不出这个 skill 相比它自己的通用能力有什么增量。

正确的做法是收窄。宁可写五个精准的小 skill，也不要写一个包罗万象的大 skill。精准的描述让 agent 的匹配判断更果断。我做过对比，把一个大而全的"后端开发规范"拆成"API 设计规范""错误码规范""日志规范"三个独立 skill 之后，每个的触发准确率都明显上升。

4.2 触发词要贴近任务里的自然语言

agent 判断相关性，靠的是把当前任务描述和 skill description 做语义匹配。所以 description 里应该包含用户实际会说的词。

比如你的 skill 是关于"接口幂等性设计"的，如果 description 只写"幂等性"，用户说"这个下单接口重复提交怎么办"的时候可能匹配不上。加上"重复提交""防重""去重"这些同义表达，命中率就上来了。这不是让你堆关键词，而是把领域里常见的说法覆盖到。

4.3 多个 skill 冲突时怎么办

当两个 skill 的适用范围有重叠，agent 可能同时加载，也可能只加载一个，行为不太确定。我的处理原则是：在 description 里显式划清边界。

比如"数据库迁移"和"数据库性能优化"两个 skill，前者 description 里加一句"本技能不涉及查询性能调优，那属于性能优化范畴"，后者加一句"本技能不涉及 schema 变更，那属于迁移范畴"。这样 agent 遇到边界任务时能做出更清晰的选择。

如果确实有共享内容，抽出来做成第三个基础 skill，让前两个引用它。不过要注意，skill 之间的引用机制在不同工具里支持程度不一样，有些工具不支持 skill 互相引用，那就只能接受一定程度的重复，或者把共享内容放进一个更基础的 skill 里靠触发顺序解决。

4.4 验证触发是否正常

写完 skill 别急着用，先做几个测试。我通常准备三组测试用例：一组是应该触发的（明确属于该领域），一组是不应该触发的（相邻领域），一组是边界模糊的（可触发可不触发）。

然后观察 agent 的实际行为。如果该触发没触发，多半是 description 的触发词不够贴近；如果不该触发却触发了，多半是 description 写太宽。这个测试过程有点像调 prompt，需要迭代几轮。别嫌麻烦，一个触发不准的 skill 比没有 skill 还糟——它会在错误的时机注入错误的知识，把 agent 带偏。

5. 团队场景下 skills 的组织与分发

个人用 skills，随便放放就行。团队用，就得考虑组织结构和分发机制，否则很快会乱成一锅粥。

5.1 目录结构怎么设计

我推荐按"领域/子领域"两级来分，不要超过三级。比如：

skills/ backend/ api-design/ error-code/ logging/ frontend/ component-style/ state-management/ ops/ incident-response/ db-migration/

每个叶子目录里放一个 skill 文件（或一组相关文件）。这样结构清晰，agent 扫描时也容易按目录归类。避免把所有 skill 平铺在一个目录里，几十个文件堆一起，维护起来很痛苦。

5.2 版本管理与变更流程

skills 本质上是团队知识资产，应该和代码一样纳入版本管理。我建议单独开一个仓库，或者放在主仓库的一个独立目录下，走正常的 PR 流程。

变更流程上，我见过两种做法。一种是"宽松制"：谁都能改，改完直接合并。另一种是"评审制"：涉及核心流程的 skill 变更需要领域 owner 审核。我的经验是，涉及安全、数据、线上操作的 skill 必须走评审，其他可以宽松。因为这类 skill 一旦写错，agent 照着执行可能造成实际损失。

另外建议给每个 skill 加一个"最后更新日期"和"维护人"字段（可以放在文件头部注释里）。时间久了，你能一眼看出哪些 skill 可能已经过时。

5.3 分发方式的选择

团队分发 skills 有几种常见方式，各有取舍。

我个人偏向共享仓库 + 定期同步。简单、透明、出问题好排查。软链接方式看着优雅，但一旦挂载出问题，agent 会静默地加载不到 skill，排查起来很费劲。

5.4 一个团队协作的实操心得

团队用 skills 最容易出的问题不是技术问题，是没人维护。一开始大家热情很高，写了一批 skill，半年后流程变了，skill 还是老的，agent 照着老流程执行，反而添乱。

我的应对办法是：把 skill 维护和现有的流程文档维护绑定。也就是说，任何流程变更，改文档的同时必须改对应的 skill，写进团队的 definition of done 里。这样 skill 不会变成孤儿资产。另外每隔一个季度做一次 skill 盘点，把没人用的、过时的清理掉。宁可少而精，不要多而烂。

6. 常见故障与排查：从"加载不上"到"触发错乱"

用 skills 的过程中会遇到各种问题，我把高频的几类整理出来，附上排查思路。这些大多是我自己或身边人实际遇到过的。

6.1 skill 完全没被加载

现象是 agent 的行为和没装 skill 时一模一样。排查顺序：

1. 确认文件位置对不对。不同工具对 skill 目录的位置要求不同，有的要求放在项目根目录的特定子目录，有的要求放在用户主目录。位置错了，扫描不到。
2. 确认文件格式对不对。元信息字段名写错、YAML 头格式错误、编码问题，都会导致解析失败。用一个最简单的 skill 做对照测试。
3. 确认工具版本支持。skills 机制是较新引入的，老版本可能不支持。查一下版本。
4. 看日志。大多数工具在加载 skill 失败时会打日志，只是默认级别可能看不到。把日志级别调高再试。

6.2 skill 被加载了但没起作用

现象是 agent 似乎知道有这个 skill，但执行时没按 skill 里的流程走。可能原因：

• skill 内容太长，被截断。有些工具对单个 skill 的注入长度有限制，超长部分会被丢弃。把 skill 拆小。
• skill 内容和 agent 的通用能力冲突。比如 skill 里写的流程和模型训练时学到的"常识"矛盾，模型可能更信自己的常识。这种情况要在 skill 里显式说明"即使与通用做法不同，也请遵循本流程"，并给出理由。
• 指令不够具体。skill 里写"注意性能"，模型不知道具体注意什么。改成"查询必须走索引，禁止全表扫描"这种可执行的指令。

6.3 触发时机不对

该触发的时候不触发，或者不该触发的时候乱触发。前面 4.1 到 4.3 讲了一些，这里补充一个排查工具：把 agent 的思考过程打开（如果工具支持）。看它在判断相关性时是怎么想的，往往能直接定位问题。如果看不到思考过程，就用二分法：把 skill 的 description 逐步简化，看哪个版本开始触发正常，反推是哪个词导致的误判。

6.4 多个 skill 互相干扰

现象是加载了 A 和 B 两个 skill 后，agent 的行为变得混乱，两边的要求都执行了一半。这通常是因为两个 skill 对同一件事给了不同指令。

解决办法是在 skill 里明确优先级，或者干脆合并。我倾向于合并——如果两个 skill 经常同时被触发且内容有冲突，说明它们本来就不该分开。分开的唯一理由是它们各自有独立的触发场景，如果场景总是重叠，分开就是自找麻烦。

提示：排查 skill 问题时，先用一个最小可复现的例子。把无关 skill 全部移走，只留一个，确认它单独工作正常，再逐个加回来。这样能快速定位是哪个 skill 引入的问题。

7. 我对 skills 这套机制的实际体会

用了一段时间 skills 之后，我最大的感受是：它的价值不在于让 agent 更聪明，而在于让 agent 更可控。

基础模型的能力已经很强了，很多时候它给出的方案大方向是对的。问题出在细节——不符合团队规范、忽略了某个边界条件、用了已经废弃的 API。skills 的作用就是把这些"团队特有的、模型不可能知道的"细节固化下来，让 agent 的输出从"大致能用"变成"直接能用"。

另一个体会是，写 skill 的过程本身就是在梳理团队知识。很多流程平时大家凭肌肉记忆在做，真要写下来才发现有歧义、有遗漏。写 skill 逼着团队把这些隐性知识显性化，这个副产品可能比 skill 本身还有价值。

至于投入产出，我的判断是：高频、易错、有明确规范的领域最值得写 skill。比如数据库变更、线上发布、安全相关的操作。低频的、一次性的任务，写 skill 的性价比不高，直接对话解决就行。别为了用 skills 而用 skills，工具是拿来解决问题的，不是拿来供着的。

最后分享一个小技巧：新写一个 skill 之后，别只看它"能不能用"，要看它"在什么情况下会误用"。故意用一些边界任务去试探它，看 agent 会不会在不该加载的时候加载。一个 skill 的鲁棒性，往往体现在它"知道什么时候不该出现"。这个测试习惯帮我避免了好几次线上事故——有次一个关于批量数据操作的 skill，在测试时发现它会被"删除单条记录"这种任务误触发，如果没测出来，后果不堪设想。