企业官网建设流程全解析

1. 从"skills"这个热词说起：它到底是什么

最近几个月，不管是在技术社区还是开发者群聊里，"skills"这个词出现的频率高得离谱。如果你只把它理解成"技能"这个英文单词，那就完全错过了它背后正在发生的一场工具链变革。我最早注意到这个词，是在折腾 Claude Code 和 Codex 这两套 AI 编程助手的时候——官方文档里反复出现 "Agent Skills" 这个概念，社区里也冒出一堆 "superpower skills"、"codex skills"、"find skills" 之类的讨论。说白了，这里的 skills 指的是一套可插拔、可复用、面向 AI Agent 的能力封装机制。

它解决的问题其实很朴素：AI 编程助手（比如 Claude Code、Codex、Cursor 里的 agent 模式）本身是个通用大脑，但每个团队、每个项目、每个具体任务都有自己的一套规矩和流程。你不可能每次都把"我们项目用 pnpm 不用 npm""提交前必须跑 lint""数据库迁移要按这个模板写"这些上下文重新喂一遍。skills 就是把这些重复性的领域知识、操作流程、约束条件打包成一个个独立模块，让 agent 在需要的时候自动加载、按需调用。这跟传统意义上的"插件（plugin）"有点像，但又不完全一样——plugin 更多是扩展宿主程序的功能，而 skills 是扩展 agent 的行为模式和知识边界。

适合谁来关注这块内容？三类人最该花时间研究：一是日常重度使用 Claude Code、Codex 这类工具的开发者，学会写 skills 能让你的 agent 从"能用"变成"好用"；二是团队里的技术负责人，skills 是把团队规范沉淀成可执行资产的最佳载体；三是做 AI 应用开发的工程师，理解 skills 的设计思路，对你设计自己的 agent 系统有直接借鉴意义。接下来我会从设计思路、核心机制、实操落地、踩坑排查几个维度，把 skills 这套东西彻底拆开讲清楚。

2. skills 的整体设计与核心思路拆解

2.1 为什么是"技能包"而不是"大提示词"

很多人第一反应是：我直接把所有要求写进 system prompt 不就行了，为什么要搞这么复杂的 skills 机制？我一开始也这么想，直到提示词膨胀到几千行、每次调用都要烧掉大量 token、而且改一处就影响全局的时候，才明白问题所在。

大提示词的核心缺陷有三个。第一是上下文污染：你把前端规范、后端规范、数据库规范全塞进去，agent 在处理一个纯前端任务时也被迫读了一堆无关内容，注意力被稀释，输出质量反而下降。第二是维护困难：一个几千行的提示词文件，谁改了什么、哪条规则还有效，根本说不清。第三是无法复用：你在这个项目写的规则，换个项目就得复制粘贴，改一次要同步好几处。

skills 的思路是把这些内容按职责切分、按需加载。每个 skill 是一个独立单元，有自己的名称、描述、触发条件和具体内容。agent 在处理任务时，先看当前任务匹配哪些 skill 的描述，只把相关的加载进来。这就像你招了个新员工，不会第一天就把公司所有规章制度全背给他，而是他做报销时给他报销流程，做发布时给他发布流程。

提示：判断一个东西该不该做成 skill，标准很简单——它是否会在多个任务中重复出现，且只在特定场景下才需要。满足这两点就值得封装。

2.2 skills 与 plugin、agent 的关系梳理

这三个概念经常被混着用，我按自己的理解理一下。Agent是执行主体，是那个会思考、会调用工具、会多轮迭代的"大脑"。Plugin是给宿主环境（比如 IDE、编辑器）扩展功能的模块，它改变的是工具本身的能力。Skills则是喂给 agent 的知识和流程，它改变的是 agent 的行为方式。

打个比方：agent 是一个厨师，plugin 是给他添置的新厨具（烤箱、破壁机），skills 则是菜谱和这家餐厅的出品标准。厨具再好，没有菜谱和标准，做出来的菜也不稳定。反过来，菜谱再详细，没有趁手的工具，效率也上不去。三者是配合关系，不是替代关系。

在实际使用中，Claude Code 和 Codex 对 skills 的支持方式略有差异。Claude Code 更强调通过配置文件或目录约定来组织 skills，Codex 则倾向于用更结构化的方式定义。但底层逻辑是一致的：描述驱动匹配 + 按需注入上下文。

2.3 一套好的 skills 体系应该长什么样

我踩过不少坑之后，总结出一套相对靠谱的 skills 组织原则。首先是粒度适中：一个 skill 不要试图覆盖太多东西，最好聚焦在一个明确的能力上，比如"React 组件编写规范"或"数据库迁移脚本生成"。粒度太粗会导致加载冗余，太细又会导致数量爆炸、匹配困难。

其次是描述精准：skill 的 description 字段是 agent 决定要不要加载它的唯一依据，必须写清楚"这个 skill 在什么场景下用、能解决什么问题"。我见过太多人 description 写得含糊，结果 agent 要么该加载时不加载，要么不该加载时乱加载。

第三是内容自洽：一个 skill 内部应该是完整可执行的，不要依赖另一个 skill 的上下文。这样即使单独加载也能正常工作。第四是可测试：每个 skill 都应该有明确的输入输出预期，方便你验证它是否真的按预期工作。这一点在社区讨论 "agent skills 测试" 时被反复提及，但真正落地的人不多。

3. 核心机制解析与关键细节

3.1 skill 的匹配与加载机制

理解 skills 怎么被选中，是写好 skills 的前提。主流实现基本都遵循"两阶段"逻辑：第一阶段是召回，agent 拿到任务后，扫描所有可用 skill 的元信息（主要是名称和描述），筛出可能相关的候选；第二阶段是精排与注入，从候选里进一步判断哪些真正需要，把它们的完整内容加载进当前上下文。

这个机制决定了两个关键点。第一，description 的质量直接决定召回率。如果你的描述里没有包含任务中会出现的典型词汇，agent 根本想不到你。比如你写了个处理 Excel 导出的 skill，描述里只写"数据处理"，那用户说"帮我把报表导成 xlsx"时，agent 很可能匹配不上。第二，skill 数量不能无限膨胀。召回阶段是要扫描全部元信息的，几百个 skill 会让这一步变慢，也会增加误匹配概率。我的经验是单个项目控制在 20 到 50 个 skill 比较舒服，超过就考虑分组或分层。

3.2 触发条件的写法与常见误区

触发条件（什么时候用这个 skill）是 skills 里最考验功力的部分。我把它分成三类写法，各有适用场景。

第一类是关键词触发，直接在描述里列出典型触发词。适合场景明确、词汇固定的任务，比如"生成 API 文档""写单元测试"。优点是简单直接，缺点是遇到换种说法的任务就失效。

第二类是意图触发，描述的是用户想达成什么目标，而不是具体用什么词。比如"当需要保证代码风格一致性时使用"。这种更鲁棒，但对描述能力要求高。

第三类是组合触发，同时满足多个条件才激活。比如"当任务涉及数据库且需要修改表结构时"。这种能有效降低误触发，适合那些一旦误用就会造成较大影响的 skill。

注意：最常见的误区是把触发条件写得太宽泛，比如"处理任何代码相关任务"。这种 skill 几乎会在所有场景被加载，等于没有做切分，还白白消耗上下文。

3.3 skill 内容的组织格式

内容部分我建议遵循"目标—步骤—约束—示例"四段式。目标用一两句话说明这个 skill 要达成什么；步骤是可执行的操作序列，尽量具体到命令级别；约束是必须遵守的红线和边界；示例给出一到两个正例，必要时加一个反例。

为什么要有示例？因为 agent 对抽象规则的理解不如对具体样例的模仿来得准。你写"代码要简洁"，它不知道简洁到什么程度；你给一段 10 行的正例和一段 50 行的反例，它立刻就懂了。这一点在我做 "codex skills" 调试时体会特别深，加了示例之后输出稳定性提升非常明显。

另外，内容里要避免自相矛盾。我见过一个 skill 前面说"优先使用函数式写法"，后面示例却全是 class 组件，agent 直接懵了，输出在两种风格之间反复横跳。写完一定要通读一遍，确保内部逻辑一致。

4. 实操落地：从零搭建一套可用的 skills

4.1 环境准备与工具确认

动手之前先把环境理清楚。如果你用的是 Claude Code，需要确认版本支持 skills 机制，并且知道它默认从哪个目录读取 skill 定义。Codex 这边类似，要确认你的安装方式（官网下载还是包管理器）对应的配置路径。社区里 "claude code 安装""codex 安装教程" 这类内容很多，但版本差异大，建议以你本地实际版本的文档为准。

我自己的做法是先建一个独立的 skills 目录，跟项目代码分开管理，然后用软链接或配置指向它。这样多个项目可以共享同一套 skill，改一处全部生效。目录结构大致是这样：

skills/ frontend/ react-component.md css-naming.md backend/ api-design.md db-migration.md common/ commit-convention.md code-review.md

按领域分文件夹，每个 skill 一个文件。文件名用英文短横线连接，跟 skill 的 name 字段保持一致，方便排查问题。

4.2 编写第一个 skill 的完整过程

我拿"提交信息规范"这个最常用的场景来演示。先想清楚：这个 skill 要解决什么问题？让 agent 在帮你生成 commit message 时，遵循团队的格式约定。触发条件是什么？当任务涉及提交代码、生成 commit message 时。

内容部分这样写：

--- name: commit-convention description: 当需要生成或检查 git commit message 时使用。适用于提交代码、整理变更记录等场景。 --- ## 目标 生成符合团队规范的 commit message。 ## 格式 <type>(<scope>): <subject> type 取值：feat / fix / docs / style / refactor / test / chore scope 为影响的模块名，可选 subject 用中文，不超过 50 字，不以句号结尾 ## 约束 - 一次提交只做一件事，不要混合多种 type - 破坏性变更必须在 body 中标注 BREAKING CHANGE - 不要写"修改了一些东西"这类无信息量的描述 ## 示例 正例：feat(user): 新增手机号登录入口 反例：update code

写完放进目录，重启或重新加载 agent，然后测试。测试方法是给它一个变更场景，看它生成的 message 是否符合格式。如果不符合，先检查 description 是否被正确匹配，再检查内容是否有歧义。

4.3 参数选择与效果调优

skills 本身没有太多数值参数，但有几个"软参数"需要你根据实际情况调。第一个是加载优先级：当多个 skill 都可能匹配时，哪个优先？一般把更具体、更专用的排在前面。第二个是内容长度：单个 skill 建议控制在 200 到 800 字，太短信息不足，太长挤占上下文。第三个是更新频率：规范类 skill 相对稳定，流程类 skill 可能随工具链变化频繁调整，建议给每个 skill 标注最后更新日期。

调优的核心方法是对比测试。同一个任务，分别在"有 skill"和"无 skill"两种情况下跑，看输出差异。如果加了 skill 反而变差，说明 skill 内容有问题，可能是约束太死导致 agent 无法灵活处理，也可能是描述误导了匹配。我一般会准备一组固定的测试用例，每次改完 skill 都跑一遍，确保没有回归。

4.4 多 skill 协同的实战案例

单个 skill 好写，多个 skill 一起工作才是真正的考验。举个我实际遇到的场景：一个任务既要改前端组件，又要更新对应的 API 调用，还要写测试。这时候可能同时触发"react-component""api-design""test-writing"三个 skill。

问题来了：三个 skill 的约束会不会打架？比如前端 skill 说"组件保持无状态"，API skill 说"数据获取逻辑放在组件内"，这就冲突了。解决办法是在设计阶段就明确职责边界：组件 skill 只管 UI 结构和样式，数据逻辑归 API skill 管，测试 skill 只管测试覆盖。边界清晰了，协同就顺了。

另一个技巧是设置主从关系。当任务涉及多个领域时，指定一个"主导 skill"负责整体流程编排，其他 skill 作为"从属"提供具体规则。这样 agent 不会在多个 skill 之间迷失方向。

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

5.1 skill 不生效的排查路径

这是最高频的问题。我整理了一个排查顺序，基本能覆盖九成情况。

我遇到最多的是 description 问题。有一次写了个处理图片压缩的 skill，描述写的是"优化资源"，结果 agent 在处理 JS 打包优化时也把它加载了，完全跑偏。改成"当需要压缩图片文件体积时使用"之后，匹配就准了。

5.2 上下文超限与性能问题

skill 加载多了会挤占上下文，导致 agent 变慢甚至报错。社区里 "codex 无法加载组织设置" 这类问题，有一部分就是上下文管理不当引起的。应对办法有三个：一是精简内容，把能删的废话删掉；二是分层加载，常用 skill 常驻，冷门 skill 按需；三是定期清理，把过时、重复、低效的 skill 删掉。

我个人的习惯是每个月过一遍 skill 列表，看哪些最近没被触发过，哪些触发后效果不好。没用的直接删，别舍不得。skill 库跟代码库一样，需要持续维护，不然就会变成技术债。

5.3 跨工具迁移的注意事项

很多人同时在用 Claude Code 和 Codex，想把一套 skill 两边通用。这里有个坑：两套工具对 skill 格式的支持不完全一致，直接复制可能不生效。我的做法是内容与格式分离——把 skill 的核心内容写成纯 Markdown，格式相关的元信息（frontmatter）针对不同工具各写一份。这样内容改一次，两边同步，格式各自维护。

另外，不同工具对 description 的匹配算法有差异，同一个描述在 A 工具里匹配得好，在 B 工具里可能就不行。迁移后一定要重新测试，别想当然。

5.4 独家避坑经验

最后分享几条我踩坑换来的经验。第一，别一上来就写几十个 skill，先从最痛的三个场景开始，用顺了再扩展。第二，skill 要版本化，用 git 管理，每次改动都有记录，出问题能回滚。第三，给 skill 写测试用例，哪怕只是几个典型输入和期望输出，也比没有强。第四，description 里放用户会说的原话，而不是你自己总结的术语，因为匹配是拿用户输入去比对的。第五，定期让 agent 自己评估 skill 效果，比如问它"刚才这个任务你用到了哪些 skill，哪个最有帮助"，它的反馈往往能给你意外启发。

这套东西我用了大半年，最大的感受是：skills 的价值不在于数量，而在于精准。一个写得好的 skill，胜过十个凑数的。它本质上是把你脑子里的隐性经验显性化、结构化，让 agent 能稳定复现你的判断。这个过程本身，也是对你自己工作方法的一次梳理。