企业官网建设流程全解析

做AI应用有个卡了很久的痛点：Agent一接到复杂任务就容易“自由发挥”，步骤一多就开始丢三落四。后来我尝试把高频操作封装成一个个可复用的技能包，也就是这篇文章要聊的 agent-skills 思路，整个稳定性明显上了一个台阶。这篇内容会从技能拆解、结构定义、落地实操到故障排查，把一套完整的方法讲透，适合正在做Agent应用开发、或者被模型输出不稳定的问题折磨过的朋友参考。

1. Agent Skills到底是什么，以及它解决的核心问题

1.1 从Function Calling到Skills：一次能力层级的跃迁

前两年大家聊Agent，基本离不开Function Calling。把外部API封装成函数，让模型在需要的时候去调用。这个思路没错，但它管得实在有点“细”——你给Agent装了一堆零件，却没有告诉它这些零件该什么时候按什么顺序组装。

Skills要解决的就是这个上层问题。一个Skill不是单次API调用，而是把“完成某类任务”所需要的步骤、提示词、校验逻辑、工具调用组合成一个完整模块。Agent拿到一个模糊的诉求，比如“帮我整理这周的例会记录”，它能直接命中一个叫做“meeting-minutes”的技能，而这个技能内部已经预设好了大纲提取、发言人识别、待办事项整理这一整套动作。

我当时做第一个技能库时最大的感受是：思路一旦从“让模型学会调用”转变成“让模型按技能执行”，整个系统的可预测性立刻就不一样了。模型不再需要现场编流程，它只需要从一个已经验证过的流程库里做选择，这个选择成本比从零生成一层层推理要低得多，也更稳。

1.2 技能封装带来的三个实际收益

第一个收益是确定性。靠提示词描述流程，模型每次执行的颗粒度都会漂移，生成结果时好时坏。但技能内部是固定模板加变量填充，输入输出有明确约束，输出格式和步骤基本可控。

第二个收益是复用。研发团队里最烦的就是不同项目反复写同一套提示词。技能库一旦建起来，换项目时直接取用，跨部门共享也方便。我自己见过一个项目，两个业务线各自维护流程提示词，后来统一收拢成技能库，版本管理直接少了两套重复维护成本。

第三个收益是迭代效率。以前优化Agent行为只能靠改系统提示词，一改就影响全局。现在只需要单点升级某个技能，回滚也方便。技能A出了问题，把版本指回去就行，不会牵一发动全身。

1.3 哪些场景最适合引入技能体系

不是所有Agent都值得上技能体系。纯闲聊型、单轮问答型的应用，加了技能层反而拖慢响应。真正适合的是多步骤任务型场景，比如工单处理、内容生产、数据分析、日程管理这一类：每一步都有固定套路，但组合方式又需要灵活匹配用户输入。

我用下来觉得最典型的信号是：你的Agent经常在同一个步骤上犯同样的错。比如生成报告时总漏掉数据来源，或者处理报销单时总忘了校验金额上限。这些错误本质上说明“该步骤没有被固化成流程”。把这些反复出错的环节抽出来做技能，修正一次，全链路受益。

2. 技能设计的三条核心原则

2.1 单一职责：一个技能只干一件事

新手最容易犯的错是技能设计得太“大”。我见过有人把“客户全生命周期管理”做成一个技能，结果技能描述写了五行，分支逻辑十几条，模型每次都徘徊在“到底该走哪条分支”的边缘。这种技能看起来省事，实现起来全是坑。

正确的做法是把任务拆到动作级。比如“客户全生命周期管理”应该拆成“新客户欢迎信生成”“流失客户预警分析”“客户满意度回访提纲”等多个技能。判断标准很简单：如果你需要用“如果……那么……”来描述技能内部流程，就说明它还不够原子。

单一职责带来的直接好处是触发更准确。模型在判断“该调用哪个技能”时，本质上是在做语义匹配。技能粒度越细，描述就越聚焦，匹配自然更准。

2.2 描述即入口：怎么写技能描述决定触发效果

很多人以为技能描述只是给人看的注释，这完全低估了它。对Agent来说，技能描述就是触发入口。模型不会打开你的技能内容逐一阅读（有些实现连这一步都不做），它只看描述来判断该不该调用。

我踩过一次很深的坑。当时给一个数据可视化技能写了句“将数据转化为可视化图表”，结果用户聊天气时模型都去调它，因为这个描述覆盖了太多场景。后来把描述改成“当用户提供结构化表格数据并明确要求生成折线图、柱状图或饼图时使用”，误触发立刻下降。

写描述有几条实操经验：第一，写清楚触发场景，使用“当……时”句式；第二，明确排除场景，比如“不要用于纯文本描述性回答”；第三，把关键词写在前面，因为部分框架做检索时会截断或加权开头部分。

2.3 上下文隔离：技能执行时如何不污染主对话

技能和工具最大的区别在于它内部是一个“小世界”。这个设计是有意为之：技能内部的临时推理、中间结果、工具返回的原始数据，都不应该塞回主对话里。否则上下文一长，模型很快就迷失在前面的噪声中。

我见过不少团队做技能时把步骤说明、示例、中间推理一股脑写进返回结果。比如让模型“用一句话复述思考过程”，这本意是增加透明度，结果主对话里堆了大量“我已确认数据完整，现在开始处理”这类废话，既占上下文又干扰后续判断。

正确的做法是：技能内部完成后只返回结构化结果和必要的置信度信息。我一般会在技能模板里明确写一句“最终返回结果只包含以下字段，不要附加推理过程或说明文字”。这个约束看着简单，实际能省掉至少三分之一的上下文开销。

3. 技能的标准结构与定义规范

3.1 技能清单：元数据、描述、参数、实现

一套完整的技能包含四个核心模块，缺一不可。之前整理过大量社区技能包之后，我统一用这样一个结构：

name: weekly-report version: 1.2.0 description: | 当用户需要生成周报、回顾本周工作进展或整理项目更新时使用。 不要用于月报、年报或单纯的日志记录。 author: internal parameters: work_items: type: array description: 本周完成的主要任务项 required: true date_range: type: string description: 周报覆盖日期范围，如 2024-03-01 至 2024-03-07 required: false implementation: prompt_template: ./templates/prompt.md scripts: - ./scripts/format_json.py dependencies: - jq

元数据负责版本控制和归属管理，描述负责触发，参数负责结构化的输入约定，实现则指向真正的执行内容。这套结构和“面向对象设计”有异曲同工之处：对外暴露稳定的接口，对内隐藏具体实现。调用方只关心参数和结果，不关心内部怎么跑。

3.2 技能实现的两层结构：调用层与执行层

我看到不少失败的技能实现都是把两层混在一处。负责编排的prompt模板里既写了“调用什么脚本”，又写了“怎么处理脚本输出”，还夹着给用户看的文案。一旦出问题，排查成本非常高。

建议拆成两层。调用层是一份精简的prompt模板，它只做三件事：根据参数判断执行策略、调用指定脚本或工具、把结果转成返回格式。执行层则是具体脚本或子Agent流程，负责真正干活，比如数据处理、API请求、文件操作。

举一个例子，一个“批量重命名文件”的技能，调用层prompt大概长这样：

你是文件整理助手，用户提供了以下参数： {{folder_path}}、{{rename_rule}} 你的任务： 1. 检查folder_path是否存在且可访问 2. 调用重命名脚本，命令为：python scripts/batch_rename.py "{{folder_path}}" "{{rename_rule}}" 3. 获取脚本返回值后，生成重命名结果摘要 注意：不要自行实现重命名逻辑，不要修改脚本文件，不要输出中间过程。

执行层脚本则负责真实的文件操作和异常处理。这种分离让提示词和代码的改动互不干扰：提示词优化不影响命令逻辑，脚本修bug也不用动prompt模板。

3.3 一个可直接套用的技能目录模板

技能目录的组织方式直接影响维护体验。我常用的目录结构如下：

skills/ weekly-report/ SKILL.yaml templates/ prompt.md output_schema.md scripts/ build_report.py validate_params.py tests/ case1_input.json case1_expected.md CHANGELOG.md

tests目录很多人会忽略，但技能也是代码，不测就换，迟早出事故。我在下文的测试章节会详细展开。CHANGELOG则是多人协作时的关键，每次改了什么、为什么改，必须记录清楚。

4. 从零构建一个完整技能：周报生成实战

4.1 任务分析：哪些步骤值得固化

用周报生成来演示比较典型。先拆解人工写周报的流程：收集本周任务和进展、筛掉无关信息、按固定格式组织内容、提炼数据或亮点、输出成文。这五个步骤里，除最后一步外几乎全都有固定套路，非常适合技能化。

值得固化的判断标准是：这一步骤是否在每次执行中都存在？是否存在多种等价做法？如果有，就值得先用一个最合理版本固定。周报技能的“收集信息”步骤尤其值得固化，多数人在这里浪费的时间最多。

4.2 编写技能描述与参数定义

接下来写SKILL.yaml里的描述和参数。描述部分我前面说过，必须明确触发场景和排除场景。参数定义要遵循结构化优先，尽量用array和object而不要用自由文本。

name: weekly-report version: 1.0.0 description: | 当用户需要生成周报、汇报本周工作进展、整理项目周更新时使用。 适用于工作周报、项目周报、团队更新等场景。 不要用于日汇报、月度总结或季度复盘。 parameters: work_items: type: array items: type: string description: 本周完成或推进的工作事项，每条为一项独立工作 required: true blockers: type: array items: type: string description: 本周遇到的问题或阻塞项，没有则传空数组 required: false date_range: type: string description: 日期范围，格式为 YYYY-MM-DD 至 YYYY-MM-DD required: false

参数不是越多越好。每多一个参数，模型在调用时就要多一次判断，判断偏差就会引入不稳定。我当时给周报技能加了七个参数，实际运行发现模型经常传错，砍到三个后明显改善。参数能少则少，能用可枚举值就不要用自由文本。

4.3 编写技能提示词模板

prompt模板是技能执行的核心。在周报技能里，我用的模板包含三个小节：角色定位、执行步骤、输出约束。

# 角色 你是一名项目助理，负责帮用户将零散的工作记录整理成规范的周报。 # 执行步骤 1. 将work_items逐条按“项目领域”分类，例如：产品迭代、技术重构、客户支持。 2. 对每个分类，将相关事项合并为一句有信息量的描述，避免流水账。 3. 如果blockers不为空，归纳为不超过3条风险说明，每条写明影响和可能应对方式。 4. 生成标题为“{{date_range}} 周报”的markdown文档。 # 输出约束 - 使用markdown格式，包含：本周聚焦、进展明细、风险与阻塞三个二级标题。 - 不要编造或推断用户未提供的信息。 - 不使用问句，不要输出任何与上述三类无关的内容。 - 只在段落中用文字表达，配置表格必须符合markdown标准。

模板要防止模型“加戏”。输出约束里写“不要输出无关内容”不是废话，而是实测真实有效的抑制手段。模型在没有这个约束时，经常在末尾加一句“如果需要进一步分析请告诉我”，这些都属于噪声，必须掐掉。

4.4 注册技能与联调验证

技能文件写完后，注册到Agent框架里。不同框架的注册方式有差异，核心都差不多：把SKILL.yaml所在目录路径加入技能库扫描列表，然后重启服务。注册后第一件事不是直接外测，而是用固定的测试输入跑一遍，检查参数是否被正确解析。

我习惯做一次零输入测试：只传一个空参数，看技能调用链路的错误处理是否符合预期。这个测试能暴露出很多参数校验问题。比如脚本里没判断空数组就直接遍历，一跑就崩。

联调时重点盯两件事：触发准确性（该调时不漏、不该调时不误触）和输出格式稳定（跑十次结果结构一致）。我一般跑至少二十次场景覆盖，包含正常输入、干扰输入、极端输入。等到格式彻底稳定了，再接入线上流量。

5. 技能库治理与演进：版本、检索与回归测试

5.1 版本管理与兼容策略

技能库跑到一定规模，版本管理必须提上日程。我维护的库大概三十来个技能，接手时没有版本概念，某技能改了一版，所有调用方默认用最新版，结果别的小组跑出一个完全不同格式的输出，排查了一天。后来统一加版本号，问题才解决。

版本号采用三段式：主版本变更意味着输出格式大改或接口不兼容，次版本是功能增强但保持兼容，补丁版本是修bug。 一个重要约定：技能内提示词和脚本互相引用时务必用相对路径，不写死版本号。部署时用一份清单锁定全库版本，上线前整体校验，避免“某个技能悄悄变了”的情况再次出现。

5.2 技能检索与自动触发优化

技能库变大之后，模型从所有技能中命中正确目标的难度也在变大。这个和搜索引擎的原理很像：候选集越大，精确率越难保证。我常用的优化手段有三招：

第一招，给技能描述加触发词表。这个跟标签类似，把用户可能的表达方式都铺出来。比如周报技能，我会加“周报”“weekly report”“本周总结”“项目更新”等变体。第二招，离线构建索引时按场景分桶。比如一个Agent服务电商客服，就把退换货、物流查询、发票申请分到同一桶里，检索时先锁定桶，再找具体技能。第三招，对高频技能做优先级加权。某些业务里80%的咨询集中在少数技能上，显式提高它们的匹配权重，能让响应速度更快。

有个反面教训是权重调太高。某个技能被反复触发之后，相似场景全被它吸走，其他技能形同虚设。我后来给权重加了一个上限，并且定期看触发日志反向校准，避免个别技能垄断入口。

5.3 测试与回归：保住技能质量底线

技能迭代一定伴随回归风险。改一个描述词，可能让原本能触发的场景变成沉默；改一段提示词，可能让输出格式彻底崩坏。我见过太多团队技能改完上线就炸，就是因为没有测试。

我现在坚持在技能库里建一个轻量测试清单，每个技能至少维护四类用例：

• 正常场景：预期触发的输入，验证输出格式和内容质量
• 相似但不该触发的场景：验证别被“沾边”的输入带走
• 边界输入：空字段、超长文本、缺参数等
• 回归用例：历史上出过问题的输入，确保修复不复发

这四类用例可以放在3.3提到的tests目录里。CI校验接入Git hooks，提交时自动跑一遍主流程测试。手法并不复杂，但非常值得做。没有测试保护的技能库，本质上就是一个随时可能炸的炸弹。

6. 技能实战中的常见问题与排查实录

6.1 技能压根不触发，怎么定位是描述问题还是路由问题

这类问题占了技能排障的一半以上。我的排查顺序是：先看触发日志，确认模型是否看到了这个技能的描述。日志里完全没有相关记录，说明可能是技能未注册或描述索引没更新。日志里能看到描述、但模型依旧选了其他技能，那就是描述本身不够精准，进入了“候选但没胜出”的灰色地带。

实操时还有个很隐蔽的坑：很多框架会截断过长的技能描述。你费心写了一大段，结果模型只读到了前几十个字符。所以写描述时，一定把最核心的信息放在开头两行，次要信息放后面，别把精华埋在第三段。

6.2 参数传错或漏传，如何减少模型的“手滑”概率

模型写参数不稳定是常态，尤其是多个参数之间类型接近时，特别容易混。比如周报技能里date_range和work_items都是字符串相关类型，模型有时会把整个任务描述塞进date_range字段。

缓解办法是给参数增加足够强的“类型锚定”。我在参数描述里会写明示例值，并用纯文本说“字段必须为YYYY-MM-DD格式的日期范围，不要包含其他文字”。还有一招是增加一个参数校验脚本，在技能执行前先跑一遍校验，参数不合格直接返回错误并请用户重新输入，不在执行中用半残参数硬跑。

6.3 技能内与外层系统提示词打架，听谁的

很多团队把业务流程写成巨长的系统提示词，又在技能里写了相似的指令。一旦两者存在细微冲突，模型就会摇摆。比如系统提示词说“回复要口语化”，技能模板里写“输出要正式报告语气”，模型直接精分。

我的解决方案是划分领地：全局系统提示词只管全局安全策略和对话风格基调，技能内部只管特定任务的执行逻辑和输出格式。如果某个约束跟技能规则产生冲突，执行层以“更具体的局部规则”优先，这一条要写进全局提示词里。模型在对抗指令时，有明确优先级声明的处理效果好很多。

6.4 技能输出不稳定，同一个输入两次结果不一样

这个问题本质上是提示词结构给了模型太多自由发挥空间。我排查时先看输出中变异的部分集中在哪个环节。如果是内容信息有变化，说明提示词对信息源的引用不够严格，需要把“只能基于用户提供的work_items展开”这类约束写得再具体一些。如果是格式变化，多半是模板没给出严格结构，比如没限定二级标题的内容和顺序。

另外一个容易被忽略的因素是技能内部脚本的退出码和错误输出。脚本报错了但没抛给模型，模型就开始自己编一份“合理”的结果补上，看起来输出完整，实际数据是假的。后来我所有脚本都统一输出JSON，包含success字段和error信息，调用层判断success不是true就直接返回错误给用户，绝对不让模型进入“编造兜底”模式。

6.5 技能版本回退后行为不一致，排查思路

有一次我升级技能A，发现线上行为异常，准备回退到旧版本，结果发现回退无效，因为技能内部调用的公共函数库已经被新版更新覆盖了。这个坑提醒我：技能回退不能只回退技能本身的文件，必须连带锁定它调用的整个依赖链条。

此后我做了两层保障：第一，技能清单里明确声明依赖的公共组件版本范围；第二，发布时生成全量锁文件，记录每个技能和依赖的精确版本组合。回退操作直接使用上次稳定发布时的锁文件，而不是手动指一下某个技能目录。

写在最后的实操心得

整套技能体系搭完之后，我自己有一个深刻体会：技能不是越多越好，而是越准越好。初期我在库里堆了四十多个技能，结果模型触发准确率反而下降，因为候选太多干扰判断。删掉一半低价值技能，情况立刻改观。现阶段技能库维护更像是做减法，删掉一个用不上的技能往往比新加一个技能更有价值。最后再分享一个小技巧，技能上线前先跑一个月触发日志分析，那些被调用次数接近零的技能，大概率就是该被清理的对象，勇敢删掉就对了。