企业官网建设流程全解析

这两年我给不少团队做 AI Agent 应用落地，一个体会越来越深：AI Agent 能不能在业务里站稳，关键不在模型选得多强、prompt 写得有多花，而在你给它配的那套“工程工作流”是否扛得住变化。单纯把大段 prompt 塞给 Agent 的做法，项目初期很爽，等需求一多、场景一换，维护成本直接爆表。后来我把重心移到 Skills 这套机制上，才慢慢把 Agent 的交付物从“一次性对话”变成了“可持续迭代的工程资产”。

Skills 说白了就是给 Agent 准备的一套“技能包”：每个技能包有名字、有触发条件、有调用协议，包里可以塞脚本、参考文档、知识目录。Agent 收到任务后，会先看技能清单，判断当前任务该调哪个技能，然后动态加载对应内容。和插件机制比，它更像一份“岗位说明书”，Agent 知道自己什么时候该干什么事，也知道自己手里有哪些工具能用。

这篇文章适合两类人：一类是被 prompt 管理折腾到想放弃的同学；另一类是想把 Agent 能力产品化、交给团队其他人共同维护的同学。我会从概念、目录结构、编排、调试一路讲到踩坑实录，全部是落地过程中的一手经验。

1. Skills 到底是什么：先把这个概念揉碎

1.1 从 Prompt 到 Skill 的必然演进

先说一个很多人没想明白的点：prompt 本质上是一段线性文本，它承载不了复杂的分支逻辑。你可以在 prompt 里写“如果你遇到 A 情况就做 X，遇到 B 情况就做 Y”，但一旦分支超过五六个，模型就开始顾此失彼。更麻烦的是，当你有几十个业务场景时，不可能每个场景都维护一份独立 prompt，它们之间会有大量重叠，改了 A 往往影响 B。

Skills 的出现，本质上是把 Agent 的能力组织方式从“线性文本”升级成了“结构化模块”。每个技能包就是一个独立的、可被动态加载的子任务单元。Agent 在运行时可以同时挂载多个技能，根据任务需要逐层展开。这种设计借鉴了函数式编程的思想：把能力封装成带接口定义的模块，由调度器按需调用。

我见过不少团队在 prompt 上死磕，把系统提示词写到两三千字，结果模型输出质量反而下降。原因很简单：上下文窗口被无关信息占满，真正的关键指令反而被稀释了。Skills 的思路恰恰相反——它让 Agent 保持住一个精炼的“元提示”，真正的领域知识和操作细节都被折叠进技能包内部，用到才展开。

1.2 Skill、Tool、Plugin 的边界

这三者经常被混着说，但它们的粒度完全不同。搞清楚边界，你才知道该把什么逻辑放进哪个层级。

Tool 是单一动作，比如“读文件”“执行 shell 命令”“调用某个 API”。它没有业务语义，也不关心什么时候该被使用。Plugin 是一组工具的打包方案，解决的是“该连哪些外部服务”的问题，但同样不承担推理策略。Skill 则完全不同，它是面向任务的完整能力包：包含工具的挑选逻辑、执行步骤、领域规则、校验条件，甚至还有配套脚本。

我用一个修车比喻来解释：Tool 是扳手，Plugin 是工具箱里那层装扳手的格子，Skill 是“换轮胎工艺卡”。工艺卡上写着用哪个规格的扳手、按什么顺序拧、扭矩多少、装完之后怎么检查。Agent 读工艺卡才知道整套动作怎么串起来。

所以你在实际配置时，不要把什么都往 Skill 里塞，也不要把一个 Skill 拆得太碎。判断标准很简单：这个单元是否能独立解决一个完整的业务子问题？如果能，它就该是一个 Skill；如果只是操作某个数据源，它放 Tool 层就够了。

2. SKILL.md 是入口不是文档：目录结构与配置细节

2.1 一套可复用的 Skills 目录结构

先给出一套我跑顺了的目录结构，你们可以直接抄作业：

skills/ ├── requirements-analysis/ │ ├── SKILL.md │ ├── reference/ │ │ ├── story_format.md │ │ └── checklist.md │ └── scripts/ │ └── parse_requirements.py ├── code-review/ │ ├── SKILL.md │ ├── reference/ │ │ └── review_rules.md │ └── scripts/ │ └── collect_review_context.sh └── release-guard/ ├── SKILL.md └── reference/ └── release_checklist.md

每个技能包统一包含三个部分：SKILL.md是入口，相当于给 Agent 看的第一页索引；reference/放详细规则、模板、知识文档，这部分会被“懒加载”；scripts/放可执行脚本，Agent 可以按需调用。目录设计上有一个核心原则：主文件要短，知识要外置。

整个技能包必须可以整体拷贝到另一个项目里直接用。所以路径引用尽量用相对路径，不得硬编码某个机器上的绝对路径。我在交付技能包时还会附上一个 README，写清楚这个技能包依赖哪些外部命令、需要什么环境变量，方便下一个接手的人独立部署。

2.2 SKILL.md 的 frontmatter 怎么写才不会被 Agent 忽略

SKILL.md 开头的 frontmatter 不是摆设，那是整套工作流的“路由表”。我的标准模板长这样：

--- name: code-review version: 1.2.0 description: 当用户要求检查代码质量、提交前检查、排查潜在缺陷时，使用该技能；不要在数据库迁移评审时使用。 allowed-tools: - read_file - run_shell - grep dependencies: - requirements-analysis ---

别看字段少，每个都有自己的讲究。name要短，像命令名一样，方便其他技能引用，不要写成“关于代码审查的专业技能指南”这种话。version必须写，技能一多你就会发现，不同版本的同一技能输出格式可能完全不同，没有版本号你根本不知道 Agent 加载的是哪套逻辑。

description是整个文件里最重要的字段，它直接决定技能会不会被正确触发。这里先按下不表，第三节专门展开。allowed-tools用来限制技能能操作的工具范围，这是安全边界，不是你小说里的装饰品。dependencies声明当前技能依赖哪些其他技能，Agent 在编排时会主动去检查这些依赖是否可用。

3. 让 Agent 学会“在正确时机调用”：触发描述与上下文折叠

3.1 description 是触发开关，不是产品介绍

新手最容易犯的错，是把 description 写成产品说明书：“本技能提供代码审查能力，包含……”这种东西放在首页没问题，但给 Agent 看完全无效。Agent 做技能路由时，匹配的是“当前用户意图”和“技能的触发条件”之间的语义关联，你写再多的功能介绍，不如写清楚“什么时候该用它”。

我总结出一套实用的写作公式：触发场景 + 典型意图 + 反例边界。还是拿 code-review 这个技能来说：

description: > 当用户提到以下意图时使用： - 想检查代码质量、找 bug、做提交前审查 - 在 CI 阶段希望自动做一轮代码走查 - 怀疑某段代码有性能隐患或安全隐患 不要将此技能用于： - 数据库表结构评审 - 依赖升级评估

为什么要把反例边界写进去？因为多个技能的 description 在语义空间中很容易互相重叠，不写反例，Agent 就会随机挑一个撞上的技能来用。我做过一次对比测试：同样一组技能，加上反例边界之后，路由准确率从七成左右提到了九成以上。

这个数字说明：技能路由本质上是一个信息检索问题，你的 description 写得越像“检索索引”，召回的命中率越高。实操中还有个细节，我会刻意在 description 里写入业务方真实会说的口语词，比如“帮我看看这段代码稳不稳”“这个提交能上吗”，这类接地气的表达往往比书面语更容易被模型匹配到。

3.2 上下文折叠：别把细节灌进上下文

上下文折叠是 Skills 机制里最有工程价值的设计，很多人却完全没利用起来。它的核心思想是：SKILL.md 只保留一个“引导页”，详细规则全部折叠到 reference 和 scripts 里，Agent 只有在真正需要时才会展开读取。

打个比方：你桌上摊着一整本五百页的操作手册，找东西反而困难；但如果你只放一份目录，上面写着“遇到 A 情况翻第 120 页”，你就知道该去哪找答案。上下文折叠就是这个道理。我见过有人把几十条审查规则全写在 SKILL.md 里，Agent 光读文件就消耗了几千 token，等真要输出审查结论时，注意力早就被拖垮了。

我的做法是：SKILL.md 正文只写执行流程的骨架，比如“第一步先读取 reference/review_rules.md 中的规则；第二步运行 scripts/collect_review_context.sh 抓取变更上下文；第三步按规则逐条比对并输出结构化结论”。具体规则长什么样、脚本怎么实现，全部外置。

实测下来，一个包含几十个文件的技能包，初始加载占用可以控制在 300 到 500 token 以内，展开后才会逐步增加。这种设计带来的直接好处是：Agent 可以在多个技能之间来回切换而不丢失主任务，因为它的工作记忆始终留给最核心的业务目标。

4. 多技能编排：协议、检查点与降级

4.1 定义输入输出协议，让 Skill 之间能“对上话”

单个技能做功只能解决孤立的子问题，真正常见的诉求是把多个技能串成一条工作流。这时候最关键的问题是：技能之间怎么传数据？我推荐两种实践方式，按项目严格程度自行选择。

轻量方式：统一要求每个技能以“结论 + 结构化数据”收尾。比如需求分析技能跑完，必须输出一个列表：每条需求包含 ID、描述、优先级、验收标准。下游技能靠解析这些结构化数据继续干活。这种方式适合快速迭代、技能数量不超过五六个的小项目。

严格方式：为每个技能定义一份 JSON Schema，Agent 输出之前必须把结果转成 JSON，交给scripts/validate_output.py做格式校验，不合格就退回重写。我曾经给一套跨平台的数据采集系统配过这种方案：采集技能把原始结果写入data/raw.json，清洗技能读取这个文件继续处理，每个中间产物都落盘、都带校验。

这里我要强调“中间产物落盘”的价值：一是可追溯，出问题时能看到每一步的实际数据；二是可续跑，某一步挂了之后修完可以接着跑，不用从头再来；三是方便排查，可以单独拿一个中间文件去测试下游技能，不用重新跑全流程。

4.2 编排层怎么控制顺序：检查点的力量

技能之间的先后顺序不能靠 Agent 的“临场发挥”，要靠编排层显式控制。我的策略是引入“检查点”机制，每一道工序完成之后都必须通过验收，才能放行到下一道工序。

一个典型的代码提交流水线大概是这样的：

pipeline: - skill: requirements-analysis output: docs/requirements.json - gate: validate docs/requirements.json 存在且格式合法 - skill: code-review output: docs/review_report.md - gate: 检查 review_report.md 中不包含阻断级问题 - skill: release-guard output: docs/release_decision.md

检查点本质上是一个断言：如果上一工序的产物不符合预期，就把任务打回去重新执行。很多人设计工作流时只画了“顺利路径”，但真实环境里失败才是常态。检查点越早、越频繁，返工成本就越低。我宁可在每道工序后都加一个轻量校验，也不愿等到最后一步才发现中间某环节输出的是空文件。

另外要提一个关于并发编排的教训：当两个技能各自独立、不共享状态时，让 Agent 并行调度确实能提速，但我个人建议默认还是顺序执行。因为并发的收益在大部分业务流程里并不明显，但引入的不确定性很多——同一个技能被并发调用两次、写同一个文件导致覆盖、模型上下文切换混乱。除非性能实测确实成为瓶颈，否则不值得为了那点速度去赌稳定性。

4.3 失败与降级：工作流的鲁棒性设计

技能编排跑在真实环境里，会遇到各种你没预料到的情况：外部依赖的接口超时、脚本抛异常、Agent 跑到一半上下文超限、中间产物被误删。一个成熟的技能工作流必须具备三层保护机制。

第一层是重试。对瞬时故障（网络抖动、接口 5xx），给每个技能配一个简单的重试策略：最多重试 3 次，间隔按指数退避，比如 1 秒、3 秒、9 秒。第二层是降级。给关键步骤准备一条备选路径，比如在线搜索不可用时，自动切换到本地知识库；某个脚本执行失败时，改用 Agent 的纯推理能力生成兜底方案。第三层是安全中止。如果某个技能连续 3 次输出校验失败，果断停止整个流水线，进入人工介入流程，别让模型在错误的状态里反复空转。

我见过最典型的空转场景：Agent 反复用同一个脚本去读一个根本不存在的路径，每次失败后它不尝试查找真实路径，而是换个姿势继续执行同一个注定失败的方案。这种问题光靠重试解决不了，必须设置止损条件，告诉 Agent：当异常持续出现时，不要再浪费 token，直接上报人类。

这里分享一个我踩过坑之后的习惯：给每个工作流维护一份 incident log，每出一次线上异常就记录问题现象、临时补丁、最终解决方案，两周后再统一整理，把反复出现的补丁固化成技能包的新版本。这套动作听着像是软件开发流程，其实一个技能包就是一个需要持续打磨的代码库，只是它的执行引擎是 LLM 而已。

5. 工作流的验证：录制回放与自动化测试

5.1 录制回放：把 Agent 的决策过程固化下来

很多团队把技能包配好之后直接上线，等线上出问题再回来排查，这跟不写测试就把代码推上生产一样危险。Agent 应用最大的难点在于不确定性，同一个问题今天跑和明天跑，结果可能完全不同。所以验证技能工作流，重点不是看一次输出对不对，而是看输出的稳定性。

我常用的手段是录制回放：给 Agent 的运行过程开启 trace 记录，把每次工具调用的输入输出、命中的技能名、推理摘要、耗时全部打点保存下来，然后拿同一批测试样本反复跑，对比前后差异。

重点关注几个字段：

最值得警惕的是“调用路径漂移”：同样一条用户请求，昨天走的是 code-review 技能，今天却绕到了别的地方。这通常不是模型变笨了，而是某个技能的 description 被你调整之后，语义空间发生了变化。录制回放能让你第一时间抓住这些变化。

5.2 用自动化测试守护技能行为

我现在每个技能包都配一个test_suite.py，用 pytest 组织用例。测试内容分三层：一层测路由是否正确触发目标技能；一层测输出结构是否始终合规；一层测边界情况——空输入、超长文本、恶意注入样本、极端表述，看 Agent 会不会给出离谱的输出。

测试脚本大概长这样：

import pytest from agent_runtime import load_skill, run_skill CASES = [ ("帮我看看这个模块的参数校验是否完整", "code-review"), ("把这段逻辑改成异步实现，注意兼容性", "code-refactor"), ("这个提交准备上生产，帮我走一遍检查", "release-guard"), ] @pytest.mark.parametrize("query,expected_skill", CASES) def test_routing(query, expected_skill): skill = route_skill(query) assert skill.name == expected_skill, f"{query} 路由失败" def test_output_schema(): result = run_skill("code-review", sample_context) assert validate_output(result, "code-review_schema.json")

改过 SKILL.md 之后，先跑一遍测试套件再考虑上线。不少团队会在调好一个技能后忘了回归测试其他技能，结果“修复了一个技能的触发，另外三个技能开始乱触发”，这种连锁反应在语义路由机制里太常见了。

我还坚持一个原则：自动化校验不达标时让它继续迭代输出，看着像省了人工，实际上可能掩盖掉真正的问题环节。判定失败就明确失败，让负责人去查原因，这样才能倒逼每个技能包保持输出质量。

6. 常见问题与避坑实录

6.1 技能不触发 / 乱触发

这是大家遇到最多的问题，根本原因逃不出这几类：

1. description 写成了功能说明，没有触发信号，Agent 匹配不上
2. 多个技能的 description 语义过于相似，互相抢活
3. 技能名带特殊字符或过长，框架识别异常
4. 技能声明了 dependencies，但依赖没被正确注册，Agent 不敢调用

修复手段中最有效的一招，是给每个技能写三条以上的触发例句，然后用向量检索实验验证例句和描述之间的召回效果。如果例句触发了两个技能，说明这两个技能的边界描述还不够清晰，需要把反例写得更具体。我做过的项目里，经常出现“提交审查”和“代码重构”两个技能互相干扰的情况，后来把时间边界写进描述，比如“仅当用户提到‘提交’‘合并’‘上线’时使用”，问题立刻缓解。

6.2 输出格式失控

同一技能跑十次，输出格式出四种，这是大家在纯 prompt 方案里最头疼的问题。解决思路不是靠模型自律，而是靠外部约束。

我的方案分两步：第一，明确给 Agent 指定输出结构，该指定 JSON 就不要含糊地说“用结构化方式输出”；第二，使用两阶段输出：Agent 先产出草稿，然后调用validate_output.py做格式校验，不合格就附上失败原因让模型重新输出，最多重来两次。

顺手补充一个约束技巧：如果非要用 Markdown 输出，一定要明确限定标题层级和字段名，否则模型会自我发挥，生成一个看起来工整但下游程序根本解析不了的格式。

6.3 权限与工具冲突

技能包一旦上线，它覆盖的业务范围就固定了，但 Agent 在运行时对工具的调用范围并不天然收敛。如果你不在allowed-tools里限制技能可用的工具，模型有可能出于“完美主义”去读取它本不该读的文件。

一个让我印象深刻的案例：某团队给一个代码审查技能包开了过宽的 shell 权限，模型在审查过程中把服务器上的日志目录整个扫了一遍，虽然没有造成实际损失，但暴露的是权限规划问题——技能权限必须跟随业务边界。

工具冲突也常见，尤其是两个技能同时写同一个文件时，互相覆盖导致数据丢失。我的做法很朴素：不同技能分配不同的临时工作目录，通过环境变量注入路径。另外，同一技能内部的工具调用也要注意并发安全，我干脆禁止并发写同一个文件，从根上规避这个问题。

7. 最后几个实操心得

整个迭代过程走下来，有几个心得想单独分享给同行。

不要一开始就设计宏大工作流。先把单个技能打磨到测试集上稳定通过，再把技能串联起来，每加一个环节就跑一轮全链路回归。我见过不少团队一上来就画了八个技能的大蓝图，结果光路由就把项目拖垮了。技能包的粒度应该是“一次解决一个业务问题”，而不是“把整个业务流程塞进一个文件”。

技能包一定要版本化管理。version字段要维护，仓库要用版本控制管理，输入输出协议变更时要同步更新所有依赖它的技能。这样即使某一天线上行为异常，你也能快速定位是哪个版本变更引入的。

最后一条心得：技能包的工程属性决定工作流的下限，模型能力决定的是上限。如果你把技能包的目录、路由、校验都当成正经代码工程来对待，那么无论底层模型换成什么，系统都能保持稳定。反之，再强的模型也无法在混乱、不可测、随改随崩的技能配置里发挥出真正价值。