企业官网建设流程全解析

Agent 这个方向最近热得发烫，但真正上手做过的人都有一个共识：模型本身不产生价值，产生价值的是模型能调用的那些能力。我见过太多团队把精力全砸在提示词和微调上，结果交付的 Agent 连发个邮件、查个数据库都做不到。问题恰恰出在最不起眼的地方——技能（Skills）体系的搭建。

agent-skills 这个项目，说白了就是解决一件事：怎么让大模型从"会聊天"变成"会干活"。它不是某个框架的专属概念，而是构建 Agent 时必备的一层基础设施。你能让模型调用多少高质量、定义清晰的技能，Agent 的实际表现就有多强。这篇文章我会从设计思路、核心组件、落地实操到疑难排障，完整复盘我在实际项目里搭建技能体系的经验，适合正在做 Agent 应用开发、或者被"模型能力很强但产品很蠢"折磨的开发者参考。

1. 技能体系解决的核心痛点

1.1 大模型的智能其实是被"手脚"限制的

很多人对 Agent 有一个误解，觉得模型越强，Agent 就越聪明。但实际跑过一轮就会发现，模型本身的推理能力只是下限，真正决定上限的是它能操作什么。一个只能输出文字的工具，无论如何也完不成"订机票"这件事，除非它真的能联网查询航班、调用支付接口、读写日历。

我当初做第一个 Agent Demo 时，模型每次都能给出完美的规划，一到执行就卡住。原因很简单：它想读文件，但没有读文件的技能；想发 HTTP 请求，但没有封装好的工具函数。后来我在项目里陆续加了十几个技能，模型的表现立刻不一样了。这个经验让我彻底转变了思路——Agent 的开发重心，应该从"调教模型"转向"武装模型"。

1.2 为什么技能不能直接写在提示词里

技能在实现上往往是一段程序、一个 API 封装或者一条工作流。如果你把这些东西直接塞进提示词，很快会遇到三个致命问题。

第一是上下文膨胀。模型每次对话都要重新读取整个技能说明，一个技能几十行没问题，几十个技能就是几千行 token，还没开始干活，输入成本已经爆炸了。第二是维护性差，改一个技能的逻辑，意味着要重新生成提示词，同步的问题随时会出错。第三是复用性低，换个场景就得重新粘贴一遍，不同 Agent 之间完全隔离。

所以技能必须是结构化的、独立存储的、按需加载的。模型只有在需要时才拉取对应的技能描述，执行时调用对应的实现，用完即走。这是一种典型的"按需装配"思路，跟操作系统的动态库有点相似。

1.3 技能与工具插件的关系梳理

技能、工具、插件这三个词经常混用，但在我的实践里它们是有分工的。工具是最小单位，指一个具体的函数或 API 调用，比如"查询天气""发送短信"。插件是多个工具的集合，通常面向某个平台或软件的集成。技能的范围更大，它可能包含多个工具调用、内部有一套决策逻辑、甚至自带状态管理。

举一个实际例子，我做过一个"竞品价格监控"技能，它内部调用了三个工具：网页抓取、数据解析、数据库写入。这个技能本身不是一个工具，而是一个完整的能力单元。模型只需要说一句"监控一下竞品的价格变动"，背后整套流程就自动跑完。所以设计技能时要有分层意识：底层是工具，中层是技能，上层是模型驱动的任务规划。

2. 技能设计的三核心与分类

2.1 技能的三个核心组成

一个结构完整的技能，无论形式如何变化，都由三个部分组成。

描述层是模型判断"什么时候该用我"的依据，包括功能说明、适用场景、使用条件。参数层定义了调用技能时需要传入的输入，字段名、类型、必填性都要明确。执行层是真正干活的逻辑，可以是 API 调用、脚本、工作流或一段代码。

很多人在设计技能时只关心执行层，觉得代码跑通就算完事，这是大忌。描述层写得含含糊糊，模型会在该调用的时候不调用，不该调用的时候乱调用；参数层定义不清楚，技能拿到错误格式的输入，再好的逻辑也白搭。

2.2 从功能角度拆解技能的类型

我在实际项目中按照功能把技能分成了六类，这样在设计时会更有针对性。

基础操作类负责访问本地资源和基础系统功能，比如文件读写、命令执行、数据库访问。领域能力类封装特定业务逻辑，比如库存查询、订单创建、财报生成，这是与行业结合最紧密的部分。信息获取类负责从外部世界拿数据，比如网页搜索、RSS订阅、天气查询。创作生成类调用外部模型或模板完成内容生产，比如文案改写、图片生成、表格美化。流程控制类管理多步骤任务的编排与状态流转，比如任务分解、进度跟踪、异常重试。记忆存储类负责跨会话保存和检索信息，包括向量数据库的写入、关键词索引、用户偏好缓存。

2.3 技能的适配层如何设计

适配层是技能体系里最容易忽视、却决定成败的部分。我见过太多项目，技能写得很完整，但模型不是"看不到"技能，就是"看不懂"技能的描述。

业界比较成熟的方案是给每个技能配一份机器可读的清单文件，类似插件的 manifest，里面用统一的格式记录技能的名称、描述、参数结构、入口地址。模型通过这份清单决定是否调用、如何调用，运行时通过统一的调度器把请求路由到具体的执行代码。

我自己的习惯是清单文件的命名规范做成"技能名+版本号"，例如web_search_v1.json，存入特定目录。启动 Agent 时统一加载所有清单，构建成技能索引。这样有新增技能时不用改任何代码，把清单文件扔进目录就能被识别。

3. 从零构建一套技能的实操

3.1 动手前的第一步：任务流程拆解

很多技能设计不好，根因在于没有提前做任务拆解。我建议动手前先拿一张纸，把目标任务拆成最小的动作单元。

我自己常用的方法是把任务画成一条流水线。比如做一个"自动生成周报"技能，我会先拆解：读取本周的工作记录，提取待办完成情况，汇总关键成果，套用周报模板，生成 Markdown 文件。这五步就是五个动作单元，再逐个判断每一步需要什么工具或数据，技能的结构自然就出来了。

这个拆解过程还有个额外好处：你会发现有些步骤根本不需要模型参与。例如"读取工作记录"这种确定性操作，写成代码反而更快更稳。真正需要模型介入的，往往只有"提取关键成果"和"优化措辞"这两个环节。把模型用在不可替代的地方，效率和成本都会好看很多。

在设计阶段就明确哪些步骤交给模型、哪些交给代码，比事后优化省太多力气。模型每一步都在推理，意味着每一步都在烧 token，还意味着每一步都有失败概率。

3.2 写好技能描述是基本功

技能描述在常规文档里叫"说明文字"，实际使用中它决定了模型调用技能的命中率。我见过太多描述写得像 API 文档，一堆术语，但模型根本不买账。

写技能描述的核心原则是三句话讲清楚：这个技能是干什么的，什么场景下应该用，什么场景下不应该用。我总结了一个模板，基本照着套就能用：

技能名称：尽量使用动词开头，如"检索产品信息"，避免用晦涩的内部代号 功能概述：一句话说明技能用途，如"根据产品 ID 查询商品名称、价格与库存状态" 适用场景：明确列出模型在什么情况下应该调用该技能 不适用场景：明确列出相似但不应调用的情况，防止误触

最好在描述里加一两个典型调用示例，模型对示例的敏感度远高于规则描述。比如"输入示例：查询 SKU 为 1002391 的商品库存"，模型很快就能学会。

3.3 参数定义的两种策略

定义技能参数看起来简单，实际上有讲究。我实战中踩过坑，一开始把所有参数都设为必填，模型调用时经常因为缺少某个字段而失败。后来优化了一段，把所有参数都设为选填，模型又经常漏传关键信息。

我的方案是区分核心参数与增强参数。比如一个"生成销售报表"技能，时间范围是核心参数，必填；客户分组维度是增强参数，选填。模型看到必填的参数，会在不确定时主动向用户确认，而不是自作主张猜测。这样既保证了核心功能的准确率，又给了模型灵活发挥的空间。

参数的类型定义也要准确。某技能在定义数字类型参数时示例写成"20"，模型就会把参数当成字符串传入内部逻辑，列表排序直接错乱，排查了半天才发现类型不匹配。

3.4 技能的组织存储与索引加速

技能文件的存储，我推荐目录加清单的结构。顶层建一个 skills 目录，每个技能一个独立子目录，内部包含清单文件和实现代码，以技能名命名文件名，比如send_email_v1.json和send_email.py。

技能数量少的时候无所谓，一旦超过 50 个技能，每次全量扫描就不够看了。我给模拟项目 X 做过一次优化：初始化时创建技能索引表，用 SQLite 存储技能 ID、名称、关键词、调用计数，同时建立关键词匹配索引，查询技能时直接从数据库里检索，而不是全盘扫描目录。效果非常明显，技能检索耗时从几百毫秒降到个位数毫秒。

4. 技能实现、版本与安全管理

4.1 技能实现时的代码拆分思路

技能执行层实现时，最忌讳的就是把所有代码堆在一个文件里。我的习惯是拆三层。

入口层是模型调用的直接入口，负责解析参数和做基础校验，比如检查必填项、确认类型正确。业务层实现核心逻辑，与具体平台解耦，比如"读取数据库""调用第三方 API"。适配层处理平台相关的细节，比如网络请求、权限获取、日志记录。这么拆的好处是，业务层可以独立单元测试，适配层可以随时替换，不用牵连整个技能。

举一个我实际重构的例子。有一个"文件汇总"技能，原来的实现方式是直接调用操作系统命令，在模拟系统环境里正常，部署到目标环境后权限不足直接报错。后来改成业务层只声明"我需要读某个路径下的所有文件"，适配层针对不同执行环境分别实现读文件的逻辑，问题就解决了。

4.2 技能的版本控制与灰度策略

技能是代码，必须走版本控制。很多团队把技能和 Agent 的提示词一起编辑，改坏了没有回滚手段，这是大坑。

我的做法是每个技能目录下建versions/文件夹，旧版本不删除，保留最近三版，同时写一个切换脚本修改清单文件中的版本号指向。比如v1.0.0稳定之后，开发新逻辑时复制一份成v1.1.0-beta，在灰度环境测试通过后切换指向。

某次我开发一个新技能时，模型调用频繁报错，直接回滚版本号就恢复正常了。如果没有版本管理，哪怕只是改了一行代码，也要靠肉眼排查半天。

4.3 技能的权限隔离与安全控制

技能的安全问题讨论得少，实际上挺严重的。一个能读文件的技能，如果不加控制，模型可能读到不该读的配置；一个能执行命令的技能，如果不校验输入，等于给模型开了个后门。

我的原则是最小权限划分。每个技能只授予完成自身功能所需的最小权限。比如"读取产品图片"技能，权限范围只限定在图片目录，不能访问其他目录。输入校验也要做好，凡是技能内部要拼接命令、拼接 SQL 的参数，都必须经过严格白名单校验。

4.4 技能质量评分与淘汰机制

技能库不能只增不减，否则时间一长就会有一堆"僵尸技能"。我建议给每个技能建立质量台账，记录调用次数、成功率、平均耗时和报错数。每过一段时间刷新统计，低于预定阈值的技能不是优化就是下线。

单一技能成功率低于 70% 就标记为需修复，连续三轮命中率持续下降就自动降级。技能的调动结果也值得记录，一段时间后回看，哪些技能实际被模型常用、哪些几乎从不触发，一目了然。

模型不调用的技能，不是没用，而是描述没写好或场景不适合。别急着删，先看看是不是描述不够清楚。

5. 高发问题与排查技巧实录

5.1 模型该调用时不调用怎么办

现象是模型通过自然语言直接回答，明明有对应技能却不用。我排查的第一站永远是技能描述本身。描述里如果写的是"提供某功能"，模型无法建立"遇到某任务→调用该技能"的关联，描述改写成"当用户需要……时，必须调用此技能"，命中率立刻上升。

还有一种情况是技能名与常见表达不一致。比如技能叫inventory_query，但模型更熟悉"查库存"这种说法。在描述里把常见的同义表达写进去，比如"用于查询库存、存货量、可用数量"，调用率会明显改观。

5.2 模型调用技能但参数满天飞

现象是技能被触发了，但传入的参数严重不合理，比如时间字段传了中文、数字字段传了字符串。这通常是参数定义不够清晰导致的。我排查时会先看模型实际传入的内容和清单定义差在哪里，然后强化参数描述，把每个字段的格式、示例都写清楚。

比如时间参数写成"格式为 YYYY-MM-DD，例如 2025-03-15，不要传带时区或中文的时间"，错误率立刻下降。

如果模型频繁漏传核心参数，可以在适配层做一层兜底逻辑。必填参数缺失时，让技能主动向用户询问而不是直接失败，虽然多了一次交互，但成功率比静默报错高得多。

5.3 多个技能被同时触发互相干扰

当模型判定任务涉及多个技能时，可能会一次调用好几个，比如查询天气的同时打开日历记录天气，这种误触发就是描述里"不适用场景"没写好。

我的做法是在相关技能的描述里互相写清楚边界，比如天气查询技能里注明"该技能只负责查询天气，不要调用日历写入功能"，模型误触发的概率会降低不少。

5.4 技能执行依赖的库或环境缺失

技能逻辑本身写对了，但模型运行环境里缺依赖包、没配 API Key、路径不对，这类环境类问题占线上事故的一半。

我在设计技能系统时加了一个启动自检机制：启动时加载所有技能清单，逐个检查运行环境的关键依赖是否就位，缺什么直接列出来。效果很好，不用等用户调技能才发现环境问题。

5.5 依赖包的版本冲突

某个技能依赖包升级了，另一个技能的老逻辑立刻挂掉。这个问题最隐蔽，排查也最耗时。

我的方案是为每个技能维护独立的依赖环境，技能间互不影响，代价是打包和启动慢一些，但换来的是稳定性和隔离性。推荐在技能清单里记录依赖包的版本范围，升级时整体评估哪些技能受影响再动手。

5.6 技能调用超时或卡死

技能内部某个 API 响应超时，模型长时间调用无响应，整个 Agent 体验都变差。解决思路是所有技能默认带超时控制，超过设定时间自动中断，返回给模型一个"暂时不可用"的信息，后续可以重试。

耗时可能较长的技能，比如批量抓取、报表生成，建议设计成异步任务：先返回"任务已开始"，再通过回调或轮询告知结果。这样模型不会被阻塞，用户等待感也明显改善。

6. 技能库演进的三点个人体会

做 agent-skills 这类体系，我最大的感受是：技能库不只是一堆代码文件的集合，它本质上是一种知识沉淀和组织方式。团队里的业务经验、常用流程、领域逻辑，最后都会以技能的形式固化下来，成为可复用、可评估的数字资产。每次新增技能，我都在把某个场景下"怎么做"的经验编码成一个可调用的服务，积累越多，Agent 能做的事就越多。

第二个体会是，技能设计开始的阶段不需要追求大而全。从两三个最高频、最有价值的任务场景启动，比如自动化周报、资料检索、数据查询，跑通全链路后再逐步扩展。技能太多管理成本会陡增，一开始适度的约束反而让方案更容易落地。

最后一个小技巧分享给正在折腾的开发者：写技能描述时，试试站在模型的角度去读一遍。想象自己是那个什么都不懂、只能靠文字描述判断下一步行动的模型，这些描述能让你精准地理解"何时、为何、如何使用这个技能"吗？如果不能，调整到能与模型"对上话"为止。这套做法的效果，远比多写几百行代码更立竿见影。