企业官网建设流程全解析

agent-skills：我是怎么把智能体从“会聊天”调教成“能干活”的

做智能体（Agent）开发这段时间，“agent-skills”这个方向我踩了不少坑，也沉淀了不少东西。说白了，skills 解决的是一个特别现实的问题：大模型能力强，但“使唤不动”。你说让模型自由发挥，它可能跟你聊得天花乱坠，但真让它去查个数据库、调个接口、算个指标，它要么编数据，要么把参数传错。问题不在模型本身，而在于我们没给它一套清晰、可复用、可校验的“干活技能”。

所以就有了 agent-skills 这套思路：把智能体需要执行的每一项能力，从“随口吩咐”改造成“模块化技能”。每个技能有明确的名称、描述、参数定义、执行逻辑、返回格式。智能体遇到任务时，不是靠猜，而是靠“检索+调度”，把对应技能匹配出来，按固定的方式执行。这样一来，同样一件事，不管用户怎么说，智能体都知道该走哪条链路，结果也稳定得多。

项目面向的人群很明确：正在做智能体应用开发的工程师、想把大模型接入业务系统的技术负责人，还有对 AI Agent 内部机制好奇、想动手实践的学习者。下面我把整个项目从设计思路、字段规范、编写实操、注册调度到排障实录，完整拆开讲一遍。这不是官方文档式的介绍，是我自己动手做的时候理清的思路和踩过的坑。

1. 整体思路：为什么“技能”比“提示词”更扛得住事

1.1 从“让模型自由发挥”到“给模型定义技能”

最开始做智能体的时候，我采用的是最朴素的方案：写一个系统提示词（System Prompt），把业务规则、工具列表、输出格式全塞进去，然后让模型自己判断什么时候用什么工具。看起来挺灵活，实际一测就发现问题：提示词越长，模型越容易“选择性遗忘”。尤其是工具一多、参数一杂，模型经常调错工具、漏传参数，或者在某个分支上纠缠太久。同样是“查一下上个月销售额”，它有时候调报表接口，有时候直接开始编数字，完全看心情。

这里要解释一个核心现象：大模型本质上是一个“下一个词预测器”，它对所有指令的理解都是概率性的。提示词写得再详细，也只是“提高了理解对的可能性”，并不能保证每一次执行都稳定。而agent-skills 的思路，是把“理解”和“执行”拆开。理解层仍然交给大模型，让它从技能库里匹配最合适的技能；执行层则完全交给确定性代码。模型只负责判断“该用哪个技能”，不负责“自己去想怎么执行”。判断错了顶多是技能选错，执行结果却一定是确定的、可校验的。

打个比方，这就像带新人。你让新人“看情况处理客户问题”（纯提示词），他大概率手足无措；但你给他一套 SOP：客户投诉→先道歉→再记录→再确认处理时间（技能库），他按流程走，效果就稳定多了。skills 就是 Agent 的 SOP，把模糊的要求变成可复用的流程模块。

1.2 agent-skills 的边界：技能、工具和知识库到底是什么关系

新手经常把三个概念混在一起：工具（Tool）、知识库（Knowledge）、技能（Skill）。我在项目里把它们做了严格区分，这个区分直接影响架构设计。

• 工具是最底层的原子能力，比如“调用 HTTP 接口”“执行 SQL 查询”“读取文件内容”。工具本身没有“业务判断”，只负责执行。
• 知识库是静态信息的容器，比如产品手册、历史数据、规范文档。它的特点是“内容固定、供查询”，不产生行动。
• 技能是“工具+判断逻辑”的组合。它规定了在什么场景下、按什么顺序、调用哪些工具，并对工具返回结果做二次加工。技能是面向任务的，比如“查销售报表并生成分析摘要”，里面可能要调用查询工具、格式化工具，还可能查一下知识库里的指标口径。

这个划分非常重要。如果只做工具层，每个工具之间没有协同，模型还是不知道什么时候用哪个；如果只做知识库，模型只能“查资料”，不能“执行动作”。而agent-skills 正好补上了中间这个执行编排层：技能定义任务边界、编排工具调用顺序、固定输出格式，让智能体真正能完成一个完整的业务动作。

2. 技能结构设计：一个可复用的技能模块到底长什么样

2.1 技能的核心字段拆解

一个技能要能被大模型准确识别、被代码稳定执行，字段设计是关键。我在 agent-skills 里沿用了社区里比较成熟的 schema 结构，直接看示例：

name: sales_report_query description: 根据部门、时间范围和指标，查询销售报表并生成精简摘要。适用于任何与销售额、订单量、目标达成率相关的询问。 enabled: true category: data_analysis version: 1.2.0 author: platform-team parameters: - name: start_date type: string required: true description: 查询起始日期，格式 YYYY-MM-DD - name: end_date type: string required: true description: 查询结束日期，格式 YYYY-MM-DD，不能早于 start_date - name: department type: string required: false default: all description: 部门名称，支持销售部、市场部、运营部，默认查全部 - name: metrics type: array required: false default: ["sales_amount", "order_count"] description: 需要返回的指标列表，可选值见指标字典 trigger_examples: - "上个月销售部卖了多少？" - "查一下Q3的订单量和销售额" - "最近7天哪个部门目标完成率最高？" execution: type: workflow steps: - tool: validate_date_range args: ["start_date", "end_date"] - tool: query_sales_report args: ["start_date", "end_date", "department", "metrics"] - tool: format_summary args: ["__last_result__", "report_type=brief"] output_schema: type: object properties: summary: { type: string } data: { type: array } generated_at: { type: string }

字段看起来多，每个都是必要的。name是技能的唯一标识，建议用小写加下划线，便于检索。description是最关键的一个字段，它直接决定大模型能不能命中这个技能，必须写清楚“什么场景下用”“解决什么问题”。trigger_examples是给大模型的“示例锚点”，有这几个例子，模型匹配的准确率会明显提升。

参数定义部分同样重要。每个参数要有明确的类型、是否必填、取值范围。我在required之外还会加default和description，这是血泪教训换来的：没有默认值、描述含糊的参数，模型经常传错。例如metrics如果不限定可选值，模型就会自由发挥，传一个["money"]进来，代码根本解析不了。

2.2 为什么描述要“场景化”而不是“功能化”

很多人在写技能描述时喜欢写成功能说明：“执行销售报表查询”。我改用场景化描述之后，命中率提升非常明显。比如：

• 功能化描述：查询销售数据并返回结果
• 场景化描述：根据日期范围和部门查询销售额、订单量、目标完成率。当用户询问销售业绩、订单情况、目标达成进度时使用。

两者的差异在于：功能化描述描述的是“你是什么”，场景化描述描述的是“什么时候用你”。大模型在做技能匹配时，拿到的是用户问题，它需要用问题去匹配技能描述。描述越贴近口语场景、包含越多的业务词汇，匹配就越准确。这一点项目初期容易被忽略，但实测下来收益最大，强烈建议优先优化。

2.3 关于版本管理和禁用开关

技能不是一次性写完就结束的。业务口径变了、指标定义改了、接口参数升级了，技能都要跟着改。我在每个技能里都加了version字段，并且保留历史版本。调度层可以按版本灰度：先让 10% 的流量走新版技能，观察输出质量和报错率，再逐步全量。enabled开关则用于紧急止血。比如某个数据源故障了，直接把相关技能置为enabled: false，智能体就不会再调度到它，比改代码、发版快得多。

3. 核心细节解析：写技能时最容易翻车的几个环节

3.1 参数校验：与其让模型猜，不如让代码拦

技能执行的第一步不是调接口，而是参数校验。项目中的validate_date_range就是一个典型例子。用户问“查一下去年销售情况”，模型把start_date=2024-01-01、end_date=2024-12-31传进来，看着没问题；但用户说“查一下最近三个月”，模型可能会把日期算错，传成start_date=2025-03-20、end_date=2025-06-20，结果查出来的数据根本对不上。

所以在execution.steps里，我永远把validate_*类工具放在第一位。校验工具负责做三件事：格式检查（是不是 YYYY-MM-DD）、逻辑检查（结束日期不早于开始日期）、范围检查（不能查未来数据）。校验不通过，直接返回错误信息给大模型，让它重新理解用户意图并修正参数。这个设计把“模型可能出错”的风险控制在第一步，避免把错误参数传给下游业务系统。

同理，其他技能里的参数也要做类似兜底。比如查报表时用户问“看一下华东大区”，系统里跟这个名称对不上，但能模糊匹配到“华东销售中心”，校验层就做了同义词映射。这一步是常规文档里很少提到的，但在真实场景中几乎每天都能遇到。

3.2 输出格式固定：让大模型的“口胡”失效

技能执行完之后，返回的结果也不是直接丢给用户。我会在output_schema里固定输出的结构，比如 summary 是给用户的简要回答， data 是明细数据， generated_at 是生成时间。大模型拿到执行结果后进行“最后一步表述”，但它只能基于结构化数据润色语言，不能修改数值。

这样才能有效防止模型“一本正经地编数据”。如果你允许模型在最终回答里自由发挥，它极有可能因为上下文丢失或者用户追问，自己脑补一个不存在的数字。有了固定结构，模型只能把已有的data转成自然语言，数字从哪里来、格式是什么，都被锁死了。要理解这一点：技能输出数据是“证据”，模型只负责翻译证据，不负责创造证据。

3.3 技能描述里不要写“怎么做”

这也是一开始常犯的错误。写技能描述时总想解释清楚内部逻辑，比如“该技能会先校验日期再调用接口再格式化”。实际上，description字段不是给人看的，是给模型的匹配器看的。它不需要知道内部步骤，只需要知道“什么场景用”。内部逻辑全部由execution.steps定义，如果描述里写了内部实现，反而会干扰匹配判断。

我自己的标准是：描述里只保留三类信息——任务对象（查什么）、业务场景（什么时候用）、关键限制（不能做什么）。其他一律不写。

4. 实操过程：从零实现一个可落地的技能模块

以下用一个具体技能“查询招聘网站职位数据”为例，走一遍完整实现链路。这个技能在真实项目里很典型，因为它涉及外部接口调用、参数过滤、结果截断三个常见需求。

4.1 第一步：定义技能目录与基础文件

每个技能在项目中有独立目录，通常命名为skills/职位查询/，包含SKILL.yaml描述文件和handler.py执行代码。目录级别的拆分让技能可以独立测试、独立部署，也方便多个开发者并行维护。

# SKILL.yaml name: job_position_query description: 根据关键词、城市和薪资范围查询在招职位。当用户提到找工作、查职位、了解某个城市的岗位机会时使用。 enabled: true category: recruitment parameters: - name: keyword type: string required: true description: 职位关键词，如 Java、产品经理、数据分析 - name: city type: string required: false default: 全国 description: 城市名称，如 北京、上海、杭州 - name: salary_min type: integer required: false description: 最小月薪（单位：千元），低于该值的职位不返回 execution: steps: - tool: http_get args: url: "https://api.example.com/jobs" params: ["keyword", "city", "salary_min"] - tool: truncate_results args: ["__last_result__", "max_items=10"]

4.2 第二步：实现执行逻辑

执行代码的职责很简单：接收来自调度层解析好的参数，调用外部 API，对返回结果做清洗。核心部分如下：

import requests def run(params): keyword = params.get("keyword") city = params.get("city", "全国") salary_min = params.get("salary_min") query_params = { "query": keyword, "city": city, } if salary_min: query_params["salary_min"] = salary_min * 1000 resp = requests.get("https://api.example.com/jobs", params=query_params, timeout=10) resp.raise_for_status() data = resp.json() jobs = [item for item in data.get("jobs", []) if item["status"] == "open"] return {"summary": f"找到 {len(jobs)} 个在招职位", "jobs": jobs[:10]}

这里有一个细节：在params传入之前，调度层已经做过参数校验和类型转换。比如salary_min是整数型，调度层保证它不可能是字符串，执行层不需要再解析。代码看起来简单，但它只做几件事，没有业务判断，利于维护。位置、行业、排序等复杂规则，请放到校验层或额外步骤，不要堆在这个函数里。

4.3 第三步：注册技能到技能库

写好的技能需要注册到全局技能库，注册过程其实是在构建技能的索引。运行时，匹配器根据用户问题计算与每个技能description的语义相似度，挑出分数最高的候选技能。注册数据除了 YAML 内容，还要预生成一个快速检索用的向量索引。

这一步直接关系到性能。技能库如果只有几十个技能，每次实时把用户问题和所有描述过一遍模型也行；但技能多了以后，检索耗时会明显上升。我采用的做法是离线对每个技能的description和trigger_examples做向量化，存入本地向量库，查询时先用向量召回 Top-K，再做精排。这样既能控制延迟，又能保证命中率。

4.4 第四步：配置调用权限和审计日志

技能不能无条件被调用。尤其是涉及外部数据、写操作、内部系统的技能，必须有权限控制。在 agent-skills 中，每个技能可以配置allowed_roles，比如只有管理员角色才能触发“删除用户数据”这类高风险技能。这个配置放在技能调用链路的入口层，由统一的调度器拦截校验。

同时，每个技能调用都会记录完整的调用日志：传入参数、调用结果、耗时、由哪次会话触发。有一次线上反馈“某个技能总是返回慢”，排查后发现是外部接口在特定时段超时，因为日志里有完整的耗时分布，很快就定位了问题。没有日志，你根本没法复盘一次失败到底是模型选错了技能，还是技能执行出了问题。

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

5.1 模型迟迟不选择技能，反复“绕圈子”

这是最常见的现象。用户问“帮我查一下北京的前端岗位”，模型没有直接触发job_position_query，而是先反问“请问您想查找哪方面的工作？”或者在对话里打转。

排查时先看是不是技能的description写得太窄。如果描述里只提了“查询职位”，没提“北京”“前端”这些高频业务词，模型匹配不到很正常。解决办法是把常见口语表达加进trigger_examples，每加一条实际验证一条，命中率会逐步提升。

另一个原因是技能库里存在描述相似的技能，匹配器给出了多个候选，模型反而犹豫了。这种情况下要拉开技能描述之间的差异性，让每个技能的业务定位更明确。

5.2 参数传错、传漏

模型把city传成了城市代码（比如beijing而不是北京），或者把必填的keyword漏掉。这种问题靠“提示模型认真一点”没用，得靠调度层的解析器兜底。我在调度层维护了一套参数纠错规则：

• 值映射：把 common 城市名、代码、别名统一归一化为系统标准名称
• 类型纠正：模型传了字符串的薪资范围，自动转成整数
• 缺失补偿：必填参数缺失时，返回带提示的错误信息，引导模型补充，而不是自己猜一个填上

这样处理后，表面上模型“犯的错”少了，实际上错误被拦截在了执行层之外。

5.3 上下文太长导致技能命中率下降

对话轮次多了之后，技能命中率会明显下降。原因是用户当前问题与历史上下文混合，匹配器算相似度时被“噪声”干扰了。我试过把整个对话历史都塞给匹配器，效果很差。

解决办法是：匹配技能时只用“当前用户问题”，最多带上最近一轮的追问理解，不要带历史对话。把上下文还给下游的对话生成层，技能检索保持“独立且短小”。这也是 agent-skills 项目里一个重要的设计原则：技能选择只对当前请求负责，不背历史包袱。

5.4 执行超时、外部接口不稳定

外部接口不稳定是常客。为了不让技能调用拖垮整个对话，我在调度层做了超时控制和降级策略。每个技能的默认超时时间设 5 秒，超时后走降级分支：重试一次；还是失败就返回友好提示，让模型转入人工兜底流程。这需要技能执行层与调度层约定一套统一错误码，比如TIMEOUT、INVALID_PARAM、UNAUTHORIZED，模型能识别这些错误码，给出适当话术。

5.5 常见问题速查表

6. 从技能库到技能生态：agent-skills 后续还能怎么扩展

我目前最常用的扩展方向有三个：技能自动生成、技能组合编排、技能评测回流。

技能自动生成是指利用大模型分析历史对话中那些模型“搞不定”的请求，自动生成候选技能模板。比如系统发现用户经常问“对比一下 A 和 B 两个职位的薪资”，这类请求反复出现，就自动生成一个compare_jobs技能草案。人只需要审核微调，不用从零写。

技能组合编排则更进一步。单个技能解决单一任务，但实际业务往往是多个技能串联。比如“帮我筛选出合适候选人并发面试邀请”这个流程，至少需要两个技能：候选人筛选、创建面试单。我在这套体系里加入了技能编排层，它支持定义简单的 DAG 流程，指定步骤之间的依赖关系和数据传递。实现起来不算复杂，但很依赖流程稳定、数据格式统一的基础。这值得在核心技能库稳定之后再考虑。

评测回流是我最近在补的一块：建立技能评测集，定期用真实历史问题和对应的期望技能跑一遍，看命中率、执行成功率有没有回退。技能升级后立刻跑评测，避免“改一个技能，炸三个场景”。对我个人来说，这个评测集比文档管用多了，能时刻提醒自己哪些改动破坏了稳定性。

回到最开始的核心问题：怎么让智能体真正“能干活”？我的答案就是这套agent-skills 工程化思路——把模糊的需求翻译成确定的执行模块，把大模型从“什么都想自己来”变成“只做判断，不瞎执行”。智能体稳定性的关键从来不是提示词写得有多华丽，而是你有没有给它一套足够清晰、边界明确、可验证的技能体系。如果你也在做类似的 Agent 项目，不妨从梳理第一个技能开始试试，慢慢就会发现整套系统的变化。