做 Agent 应用的人，大概率都遇到过这个尴尬：同样的调研类任务，前天和昨天让同一个模型执行，给出的报告格式都变样，甚至偶尔会漏掉关键步骤。最开始我以为是模型幻觉问题，后来才发现，问题出在“没有把任务过程固化成技能”。这其实就是近几年 Agent 领域常说的 agent-skills 要解决的核心问题——把模型完成任务所需要的工具调用、流程编排、提示词模板、结果校验规则，打包成一个可复用、可编排、可版本管理的独立模块。
这篇文章我会从技能系统设计、技能模板结构、完整实操案例这三个层面展开，最后分享一套我自己在技能调试中总结的排错思路。适合正在做 Agent 应用开发的朋友参考，也适合那些想从简单 API 调用进阶到任务型 Agent 的开发者。内容尽量不拽概念，把每一步为什么这么做讲透，方便你直接照着改到自己项目里。
1. 技能系统的整体设计思路，为什么 Agent 离不开技能层
1.1 从“每次写 Prompt”到“沉淀技能”的转变
在没有技能层的阶段，Agent 的本质其实就是“一个模型 + 一堆工具”，所有任务逻辑都靠 Prompt 硬撑。为了让模型知道什么时候该调搜索、调完怎么选信息、选完怎么生成报告，我往往要写一个一两千字的系统提示词。这个方案在单个任务上勉强能跑，一旦任务场景多起来就开始失控：
- 提示词过长，模型容易忽略中间步骤，直接跳到最后输出结果；
- 不同任务的提示词互相冲突，比如调研任务和摘要任务对“输出完整性”的要求不同；
- 模型升级后行为变化不可控，同样的提示词在新版本上表现完全不同；
- 团队协作困难，业务同事看不懂你的超长提示词，改一个环节就要全部重写。
把任务逻辑从 Prompt 里抽出来，放进一个有结构的“技能包”之后，情况明显好转。这个技能包类似给新员工的一份工作手册：里面有明确的目标、每一步的操作说明、遇到不同情况的应对策略、需要参考的资料清单，还有最终成果的样式要求。模型不需要靠猜测来决定下一步做什么，它只需要按技能定义去执行。
从技术视角看，技能层的本质是“行为约束 + 记忆外部化”。行为约束指任务的触发条件、执行顺序、分支判断都被显式定义，模型在技能框架内做有限决策，而不是自由发挥；记忆外部化指技能描述了该用什么工具、怎么解析工具结果、中间结果存哪里，不需要依赖模型上下文窗口里的隐式记忆。这套设计直接提升了行为的可复现性，这也是 Agent 从 Demo 走向生产环境必须迈过的一道坎。
1.2 技能层在 Agent 架构中的位置
我自己习惯把 Agent 系统分成四层，技能层在中间承上启下：
| 层级 | 职责 | 典型组件 |
|---|---|---|
| 交互层 | 接收用户请求、展示执行过程 | 聊天界面、SSE 事件流、任务审批面板 |
| 决策层 | 理解意图、选择技能、编排执行顺序 | 模型本身、意图识别模块、任务规划器 |
| 技能层 | 封装具体任务的完整执行逻辑 | 技能注册表、技能执行器、工具调用列表 |
| 工具层 | 提供原子能力 | Web 搜索、代码执行器、数据库查询、文件读写 |
决策层负责“做什么”，技能层负责“怎么做”。打个比方，决策层是项目经理，技能层是带着详细施工图的技术负责人。两者分开的最大好处是：你可以单独优化技能执行逻辑，或者替换决策层的模型，不会互相干扰。
实际落地时，技能层通常由一个注册表和一个执行器组成。注册表存技能元数据，包括名称、描述、入参 Schema、类型标签，用来给决策层做触发匹配；执行器按照技能定义加载提示词模板、绑定工具集、启动执行循环、收集结果。决策层通过观察技能描述决定调不调，调的时候把用户意图映射为技能入参，执行器负责把剩余事情干完。
1.3 为什么不用“多智能体”而是“多技能”
一些人看到多任务协作，第一反应是上多智能体架构——一个规划 Agent、一个执行 Agent、一个审核 Agent。这个方案不是不能用，只是对小团队和轻量场景来说，维护成本高得吓人。每个 Agent 都要有独立的 Prompt、记忆、工具权限，Agent 之间的通信还要处理上下文传递、消息格式、并发冲突。
技能模式则轻量得多。多个技能可以共享同一套工具层，技能之间通过标准参数传递中间结果，不需要额外的通信协议。比如“数据抓取技能”输出一个结构化 JSON，把这个 JSON 直接作为“图表生成技能”的输入，就能完成一条完整的数据处理流水线。如果后面发现某个环节要调整，只需要改对应技能包，不影响其他环节。
这个思路的核心价值是“边界清晰”。每个技能只管自己领域内的逻辑闭环，不关心外部谁调用它、调用完之后还要干什么。边界清晰意味着可测试、可替换、可并行开发，这在多人协作时特别重要。
2. 技能模板结构与核心要素拆解
2.1 一个技能包应该长什么样
我参考了几种开源实现，最终把技能包结构稳定成五块内容，分别是元数据、工具列表、提示词模板、执行流程、校验规则。这个结构兼顾了机器可读性和人工可维护性，下面是一个技能定义的简化示例：
{ "skill_name": "structured_research", "description": "针对给定主题进行多源信息收集，输出带引用的结构化摘要。当用户需要最新资讯、深度研究或事实查证时使用。", "parameters": { "type": "object", "properties": { "topic": {"type": "string", "description": "研究主题，必须是非空字符串"}, "max_queries": {"type": "integer", "description": "最大搜索轮次", "default": 3}, "time_window": {"type": "string", "description": "限定信息时效范围", "enum": ["day", "week", "month", "year"]} }, "required": ["topic"] }, "tools": [ "web_search", "web_fetch", "text_summarizer" ], "prompt_template": "templates/structured_research.md", "workflow": [ {"step": "decompose", "description": "将主题拆解为3-5个子问题"}, {"step": "search", "description": "对每个子问题执行搜索，结果写入临时存储"}, {"step": "synthesize", "description": "综合所有搜索结果，生成带引用的摘要"} ], "validation": { "required_fields": ["summary", "sources"], "output_format": "json" } }每个字段都有实际用途。description是决策层选择技能的依据，写得好不好直接决定模型会不会“误触”或“漏触”；parameters定义技能能接受什么输入，让决策层可以把用户的话映射成结构化参数；tools限制技能只能使用白名单工具，避免模型乱调；prompt_template是技能内部行为的“最后一道约束”，负责把参数和步骤串起来；workflow给执行器一个粗粒度的阶段划分，方便做进度展示和日志记录；validation则保证输出符合下游的预期，坏数据不会流到下一环。
2.2 元数据与描述信息：写不好一切白搭
技能描述是一段让模型阅读的文本，它的质量直接决定了技能命中率。我在实践中反复调整，总结出一个可复用的描述公式：
触发场景 + 动作描述 + 输出形式 + 边界条件举例来说，“当用户询问某个主题的最新信息，或者要求对比多个来源的观点时，执行多源检索并输出带引用的要点总结。不适用于主观创作类任务，也不适用于本地文件分析。”
这样写比“研究功能”要清晰得多，模型能在意图判断阶段就把用户需求映射到正确的技能上。边界条件尤其重要，它可以大幅减少技能误触发的情况。我之前就遇到过用户只是闲聊“帮我看看最近有什么电影”，结果触发了新闻检索技能，消耗了不少 token 还得不到准确答案，问题就出在描述里没写“非事实查询类任务不放行”。
参数 Schema 的设计也需要克制，能用三个参数解决的不要放五个。每个参数都会增加模型一次意图解析成本，参数过多时模型可能漏填或填错。我通常只保留必须的入参，可选参数能设默认值就设默认值。
2.3 提示词模板中的角色、步骤与约束
技能包里的提示词模板，和系统级 Prompt 的区别在于它只为“一个技能内部服务”。模板不需要管用户身份、风格偏好那些事，只需要聚焦任务本身。我把模板的固定结构整理为四段：
- 角色定义：明确模型在这个技能里扮演什么角色，比如“你是一名严谨的调研助理”，要避免与系统 Prompt 冲突；
- 执行步骤：按顺序列出操作步骤，明确告诉模型每一步该输入什么、产出什么；
- 分支处理：写明特殊情况的处理方式，比如“搜索结果为空时，降低时间要求进行二次搜索”“来源冲突时，优先选择权威站点内容”；
- 输出格式：用规范描述最终输出结构，关键字段必须逐一说明。
模板不是句子越长越好。我曾经把执行步骤写得非常详细，包括“打开浏览器、点击搜索按钮”这样的操作描述，结果模型反而失去灵活性，简单任务也被迫按复杂流程走，浪费时间。后来我把粒度控制在“让模型知道当前阶段要什么结果，而不是怎么操作工具”的层次上，效果立刻改善。
一个比较完整的模板片段大概长这样：
你是专业调研助理。请按以下流程完成主题调研： 1. 将主题拆解为不超过5个子问题，用 JSON 数组输出； 2. 依次对每个子问题执行 web_search，每次搜索后记录“子问题、来源URL、核心信息”； 3. 汇总所有搜索结果，完成信息去重和冲突校验，优先选择更新时间更近、域名可信度更高的来源； 4. 输出 JSON，包含 summary（150字以内的总结）、bullet_points（不超过8条要点）、sources（来源URL数组）、conflicts（冲突说明，可选）。 注意： - 如果两次搜索都没有有效结果，不要编造，直接输出空 sources 并说明原因； - 所有来源信息必须真实对应搜索结果，禁止推测 URL。2.4 工具列表与执行权限收敛
很多人在技能定义里忽略工具白名单的作用，觉得“反正模型只会调用我已注册的工具”，其实不然。当系统工具数量多的时候，模型在复杂任务里可能为了达成目标选择了一条错误的工具路径，或者绕过了本应使用的技能专用工具。工具白名单能显著降低这种情况的概率。
比如“结构化研究”技能只允许web_search、web_fetch、text_summarizer，即使系统里有数据库查询工具和文件读写工具，也不会被这个技能误用。白名单本质上是把技能的执行环境“沙箱化”，这个思路和容器化应用只开放必要端口是一个道理。
工具列表的维护节奏也需要把握，工具数量少时不需要白名单，工具多了之后白名单的价值就体现出来了。我一般会在技能注册表里加一个后台统计，记录每个工具被各技能调用的频次，帮助发现哪些工具长期闲置或过度使用。如果一个技能实际只用了两个工具却不小心放进了五个，说明技能边界没划清楚。
3. 实操：从零实现一个“结构化研究”技能
3.1 需求定义与先决条件
这节用一个我实际开发过的技能举例，它的目标是：用户输入任意主题，Agent 完成多源信息检索、去重汇总、带引用输出。这个技能很适合作为脚手架案例，因为它的功能跨度比较大，涉及检索、抽取、总结三步，但技术栈又简单，不需要额外数据库或者复杂的异步框架。
动手前，你先确认自己的 Agent 项目具备三个条件：
- 有一个稳定的模型调用接口，支持函数调用或工具定义格式；
- 有 web_search 和 web_fetch 两个基础工具，能返回带回链的文本内容；
- 项目里能存 JSON 配置文件，能从代码加载技能定义。
条件不满足也不要紧，你可以用 Textise Dot iitty 之类的网页阅读服务代替 web_fetch，用搜索引擎的 RSS 接口代替 web_search，只是效果会打折。下面是技能定义的核心配置：
{ "skill_name": "web_research", "description": "当用户需要某话题的最新资料、多源观点对比或事实查证时使用。进行网络搜索并输出带引用来源的要点总结。不适合处理用户本地文件内容。", "parameters": { "type": "object", "properties": { "topic": { "type": "string", "description": "需要研究的主题" }, "max_queries": { "type": "integer", "description": "最大搜索次数，默认3，范围1到5", "default": 3 } }, "required": ["topic"] }, "tools": ["web_search", "web_fetch"], "workflow": [ "subtopic_decompose", "search_loop", "information_synthesis", "output_formatting" ] }max_queries是控制成本和耗时最重要的参数。搜索一次大概消耗 500 到 800 token，加上返回网页内容、模型阅读和总结，可能整体要 3000 到 5000 token。设成 1 到 5 的范围，能在需求深度和成本之间取得平衡。
3.2 技能执行主循环代码实现
技能执行器是整个技能层的心脏，它负责加载定义、绑定工具、循环执行工作流、返回结果。这里我给出一个极简但完整的 Python 实现，去掉业务细节，只保留主干。它能在自己项目里跑通，后续按需扩展。
import json import re from typing import Any, Dict def load_skill(skill_name: str) -> Dict[str, Any]: """从技能目录加载技能定义文件""" with open(f"skills/{skill_name}.json", "r", encoding="utf-8") as f: return json.load(f) def resolve_prompt_template(skill: Dict[str, Any], context: Dict[str, Any]) -> str: """加载并渲染提示词模板，将参数注入模板占位符""" with open(skill["prompt_template"], "r", encoding="utf-8") as f: template = f.read() for key, value in context.items(): template = template.replace("{{" + key + "}}", str(value)) return template def validate_output(skill: Dict[str, Any], output: Dict[str, Any]) -> bool: """校验技能输出是否符合预期结构。""" required = skill.get("validation", {}).get("required_fields", []) for field in required: if field not in output: return False if skill.get("validation", {}).get("output_format") == "json": try: json.dumps(output) except (TypeError, ValueError): return False return True def run_skill(skill_name: str, params: Dict[str, Any], tool_executor: Any, model_fn: Any) -> Dict[str, Any]: """ 技能执行主入口。 tool_executor: 统一接受 (tool_name, **kwargs) 并返回文本结果的执行器 model_fn: 统一接受 messages, tools 等参数并返回模型输出的函数 """ skill = load_skill(skill_name) context = {"topic": params["topic"], "max_queries": params.get("max_queries", 3)} # 阶段1：子主题拆解 decompose_prompt = resolve_prompt_template( skill, {**context, "stage": "decompose"} ) # 这里如果模型输出不是合法 JSON，做一次容错清洗 raw_subtopics = model_fn( messages=[{"role": "user", "content": decompose_prompt}], temperature=0.2, ) match = re.search(r"\[[\s\S]*\]", raw_subtopics) subtopics = json.loads(match.group(0)) if match else [params["topic"]] # 阶段2：对每个子主题循环执行搜索 collected_chunks = [] for i, subtopic in enumerate(subtopics[: context["max_queries"]]): search_result = tool_executor.run("web_search", query=subtopic) snippet = search_result.get("snippet", "") if len(snippet) < 20: continue collected_chunks.append({"subtopic": subtopic, "snippet": snippet}) # 阶段3：汇总生成，进入模板 synth_prompt = resolve_prompt_template( skill, {**context, "stage": "synthesize", "chunks": collected_chunks} ) final_text = model_fn( messages=[{"role": "user", "content": synth_prompt}], temperature=0.3, ) # 阶段4：解析并校验输出 try: final_output = json.loads(final_text) except json.JSONDecodeError: final_output = {"summary": final_text, "sources": []} if not validate_output(skill, final_output): # 校验失败时重试一次，模板追加“严格按照JSON格式输出” retry_prompt = synth_prompt + "\n请严格输出 JSON，不要包含其他内容。" final_text = model_fn( messages=[{"role": "user", "content": retry_prompt}], temperature=0.1, ) try: final_output = json.loads(final_text) except json.JSONDecodeError: final_output = {"summary": "", "sources": []} return final_output这个实现里有个容易被忽略的细节：子主题拆解完之后，我用collected_chunks缓存了每一轮的搜索结果，然后一次性塞给最终总结。这个设计是有意的——不要在总结阶段重复搜索，否则 token 消耗会翻倍甚至更多。
tool_executor和model_fn被设计成接口而不是具体实现，这带来两个好处：第一，你可以把工具调用和模型调用替换成自己项目的版本，完全不影响技能逻辑；第二，测试时可以注入 mock 对象，不用真实调用外部 API。
3.3 模板渲染与上下文传递细节
上面代码里模板占位符用了{{topic}}、{{stage}}、{{chunks}}这类简单替换。业务项目里模板引擎可以考虑 Jinja2，支持循环和控制流。比如在汇总阶段，需要用循环来遍历 chunks 列表：
{% for chunk in chunks %} - 子主题：{{ chunk.subtopic }} - 内容摘要：{{ chunk.snippet }} {% endfor %}如果用 Python 的原生 replace 方法处理列表，需要先把列表序列化成字符串，这个做法在数据量小的时候也没问题，但模板一旦复杂起来就难维护。使用 Jinja2 的另一个好处是模板语法本身就带注释和条件渲染，提示词的可读性会好很多，业务同事做 review 也更容易。
上下文传递还有个常见坑：chunks内容太长了，超过模型上下文窗口。我建议做一次截断，把每条 snippet 限制在 200 到 300 字符，超过的部分直接按段落切掉。搜索结果的价值主要在第一段和标题，尾部往往是重复性或无关内容，丢掉不心疼。如果确实需要完整信息，可以让模型在总结时对不确定的要点再次调用web_fetch获取全文。
3.4 技能调试与效果验证
技能写完不能直接上生产，我一般按三层来验证。第一层是单元验证，手动传入几个主题，观察子主题拆解是否合理；第二层是集成验证，接入真实搜索，确认搜索强度和内容质量；第三层是对比验证，拿同样一批主题，对比“有技能”和“无技能”的输出差异。
我测试时常用的主题有：“大模型推理优化最新进展”“某个城市马拉松赛事规模”“新能源汽车换电模式现状”。这几个主题分别覆盖了技术类、事件类、产业类，能够暴露出不同的问题。
我实际跑测试时发现，max_queries从 3 提高到 5，内容覆盖率提升约 30%，但耗时从约 25 秒涨到 40 秒。对实时交互来说，40 秒已经接近可感知的卡顿边界，所以默认值我最终定在 3。如果用户主动要求深度调研，再动态调高，这样成本和体验是可控的。
还有一个验收指标是“输出结构的稳定率”。连续跑十次同一主题，每次都必须输出合法的 JSON，且字段完整。这个指标能筛掉很多模型随机性问题。出现不稳定输出时，最常见的修法就是降低 temperature 到 0.2 以下，以及在模板里加一行“只输出 JSON”。
4. 常见问题与排查技巧实录
4.1 模型不按流程走，跳过关键步骤怎么办
这个问题的症状是：明明模板写了“先拆解子问题、再搜索、最后总结”，结果模型收到用户请求后直接输出最终答案，搜索工具完全没被调用。排查时先看模型调用的完整消息记录，判断到底是没有按系统提示执行，还是技能定义没有被加载。
经验上这类问题的出现顺序是：先确认技能注册表的描述是否清晰，描述模糊时决策层根本没选中这个技能；再确认模板是否被正确渲染，占位符没替换会形成语法混乱，模型理解不了就只能自由发挥；最后才是降低 temperature 提升执行一致性。
4.2 工具返回超时或结果不完整
Agent 跑在真实网络环境下，总会遇到搜索超时、网页打开失败的情况。代码要对工具异常做兜底，不能让一次超时把技能执行直接推倒重来。我习惯在tool_executor.run外面包一层 retry，第一次超时后指数退避重试一次，第二次仍失败就把这一路结果标记为“未获取”，在最终输出里注明数据不完整。
还有一个容易被忽略的坑：搜索工具返回的内容虽然是文本，但可能包含大量广告、导航、无关 HTML 文本。给搜索结果接一层“正文抽取”环节，用 pre 读取器提取标题和正文主干，能显著提升后续总结的质量。要不要做这一步，从耗时的变化幅度就能判断出来——不做抽取时模型总结时间明显偏长，因为它不得不“阅读”大量噪音。
4.3 技能输出 JSON 解析失败
这个异常在我测试早期非常频繁，模型总是忍不住在 JSON 外面加注释、加问候语、加 markdown 代码块标记。处理思路是“先清洗、再重试”：
- 用正则去掉输出文本里的代码块标记；
- 定位第一个
{和最后一个}，截取中间内容进行解析； - 解析失败时重试一次，重试时明确要求“不要包含任何解释性文字”。
如果仍失败，才走到“降级输出”逻辑，用一个包含 summary 文本的空模板兜底。降级输出的质量会差，但至少不会让整个会话崩溃。
4.4 技能误触发或漏触发
误触发最常见的原因是技能描述里“该做什么”写得太泛。比如你把技能描述写成“为用户提供网络信息”，这把信息检索、百科问答、新闻提醒全圈进来了，模型自然容易串台。把描述限定为“当用户需要特定话题的最新多源调研时使用，单问单答不需要触发”之后，情况立刻改善。
漏触发的原因则更隐蔽，通常发生在用户表达间接时。比如用户说“我想了解一下这几家的区别”，如果技能描述里只有“事实查证、多源调研”，模型可能意识不到这也是一次研究任务。我建议把“对比分析”也标注为触发条件，然后通过参数化让技能兼容“多实体对比”的场景。
4.5 故障速查表
我把调试中高频遇到的现象、原因和处理办法整理成一个速查表，方便实际排查时快速定位。
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 技能没有执行，直接输出 | 决策层没选中技能 | 检查技能描述是否包含足够的触发信号 |
| 执行了搜索但最终答案很泛 | 摘要阶段 prompt 缺少“基于 collected_chunks”的强约束 | 在总结调用前注入搜索结果摘要 |
| 输出的引用 URL 不真实 | 模型幻觉补全 | 校验 URL 是否出现在搜索返回结果中 |
| 无限循环调用同一工具 | 搜索条件一直失效但代码持续重试 | 增加最大重试次数，超过后跳出循环 |
| 同一输入两次结果差异大 | temperature 偏高或模板中分支定义不清晰 | 将 temperature 降至 0.2 以下并固定随机种子 |
| 自定义技能完全不被加载 | 技能配置文件未解析或路径错误 | 检查注册表加载日志，确认技能 JSON 格式合法 |
排查问题时我的经验是“先看日志，再猜原因”。技能系统打日志要记录每次模型调用的完整输入输出、每次工具调用的耗时与返回结果摘要、每一步工作流的跳转时间。没有日志的状态下靠猜，效率极低。
5. 从单技能走向技能库的扩展思路
5.1 技能的复用与组合
单个技能能解决单点问题，技能库则解决系统问题。当你有“研究总结”“PDF 转文本”“表格提取”“图表生成”几个技能之后，可以尝试让它们组合出一条新流水线：“PDF 转文本技能”提取出的内容，喂给“表格提取技能”得到结构化数据，再交给“图表生成技能”产出可视化。组合的关键是每个技能的输入输出都必须是结构化的 JSON，不能是自由文本。
标准化的代价是前期设计多花时间，回报是可组合性大幅提升。我用一个简单的命名规则约束输出结构：字段名用蛇形命名、必填字段控制在 5 个以内、复杂对象用嵌套 JSON 而不是拍平结构。这套规则让下游技能在消费上游数据时几乎不需要做适配。
5.2 技能库的版本管理与灰度发布
技能文件既然是一个独立模块，就必然要有版本管理。技能名加_v1后缀虽然简单，但在技术债处理上很吃力。我推荐在技能定义里增加version字段，然后让执行器在加载时根据版本号选择具体的模板和工具列表。
灰度发布的流程说起来很简单：新版本技能先跑在一个内部测试 Agent 上，跑一批固定测试集，观察成功率、耗时和输出质量对比，确认没问题之后切流量到 10%，逐步放量到 100%。这一步最难的不是技术，而是定义“成功”的指标。我习惯按下表来评估：
| 指标 | 新版本阈值 |
|---|---|
| 输出结构合法率 | ≥ 95% |
| 平均执行耗时 | 不超过旧版本 1.2 倍 |
| 用户主动反馈问题率 | 不超过旧版本 |
| 单次运行 token 消耗 | 不超过旧版本 1.3 倍 |
5.3 多角色协作维护技能库
技能库规模超过 20 个之后，一个开发者根本维护不过来，需要建立分工机制。我的分工方案是：一线使用者提出技能需求和验收标准，提供典型用例和边缘 case；开发者负责工具封装、技能框架和调试；有经验的高级工程师负责技能质量审核、安全边界划定和版本发布。
这个分工最明显的收益是“需求从使用中来，验证回使用中去”，不会出现开发者闭门造车造出没人用的技能的情况。技能上线后还要定期做运营统计，看每个技能的真实调用次数、失败次数和 token 消耗趋势。调用次数持续走低的技能要考虑是否描述写得不好，还是任务需求本身已经变化了。
根据我自己的项目经验，一个成熟的 Agent 系统，技能数量维持在 20 到 30 个时是维护成本和功能覆盖面最平衡的区域。超过 40 个后就要考虑给技能做分类、分组和检索，甚至需要一个技能管理后台来辅助维护。过早追求“大而全”的技能库不仅消耗开发时间，还会因为技能之间边界模糊而不断踩坑。
6. Agent 技能设计中的成本控制与性能优化
6.1 成本控制：技能层如何帮你省钱
很多人没有意识到，技能层设计得不好是隐性烧钱大户。没有技能抽象时，每次用户请求，模型都要从超长系统提示词里理解任务、在多个工具之间徘徊，一次请求可能消耗七八千 token，其中相当一部分浪费在不必要的上下文阅读上。技能化之后，系统提示词被压缩到极短，模型只在技能内部的小上下文里工作，单次 token 消耗可以下降一半以上。
我在一个实际 Agent 项目里做过程：原来的长 Prompt 方案每轮请求平均消耗约 6200 token，技能化之后降到约 3100 token，同时响应时间从平均 17 秒缩到 8 秒。成本优化不是靠模型选型或者 API 降价，而是靠架构层面的上下文缩减。
技能调用频率也可能成为成本漏点。同一个用户会话里，如果多次触发同一类技能，可以考虑让技能结果带上“缓存策略”。比如研究类技能的结果缓存一天，重复请求直接返回缓存，不重新执行全流程。不过这个缓存策略要用得克制，一旦用户明确要求“最新信息”，就必须绕过缓存走完整搜索流程。
6.2 性能优化：减少技能执行过程中的空转
技能执行流程里最常见的空转是“等待模型输出”。如果技能流程可以拆成并行分支——比如多个子主题的搜索完全可以同时进行——就不要写成串行循环。实测下来，把三个子主题的搜索从串行改成并发，整个技能的耗时能缩短 40%。并发要做好限流，同时发起太多请求容易被搜索结果限流或者被 API 限速。
上下文长度管理也是性能优化的一部分。技能执行过程中，每一步中间结果都在膨胀，如果全部保留在上下文里，后续步骤的推理时间会指数级上升。我的处理原则是“第三层总结、第四层精简”：每次搜索后把结果压缩成 150 字以内的要点，而不是把整段原文留在上下文中，到汇总阶段只剩精简的要点列表，模型处理起来快很多。
工具层的调用还能做“预加载”。如果技能工作流第一步是子主题拆解，通常是固定的几个模型输入输出，我可以把拆解结果缓存起来，同一主题第二次执行时直接复用，省掉一次模型调用。预加载的本质是在“可靠缓存”和“动态变化”之间找到一个平衡点，并不适用于所有技能，但用于高频重复场景非常划算。
6.3 可观测性：技能执行的监控维度
没有可观测性就没有成本优化。我给自己项目的技能层加了四个监控指标，分别是触发率、成功率、单次成本、响应时长。触发率反映决策层的匹配质量；成功率反映技能自身设计是否靠谱；单次成本和响应时长则直接与费用和用户体验挂钩。
日志记录时不能只记结果，要把每次技能触发的原因、参数、执行路径都记录下来。这有助于回溯“用户为什么会触发这个技能”。比如我发现某个技能的成功率很高，但用户满意度评价反而低，查日志后发现是技能被误触发，用户本想做的是简单问答，技能却跑了一遍完整研究流程。这类问题只看指标看不见，必须回到日志里看链路。
我给技能执行加了 trace_id，贯穿技能触发、工具调用、模型输出整个链路。任何一次失败都能沿着 trace_id 找到具体的工具返回、模型输出和上下文快照。没有 trace_id 的调试，相当于没有目录的书，查个问题要翻半天。
7. 从技能设计到团队协同，再聊聊我的一些体会
7.1 让技能可以被团队成员一起编辑
技能文件本质上是文本、是 JSON、是 Markdown 模板，这给它带来了一个独特优势——非工程师也可以参与编辑。技能描述怎么写、触发条件怎么定、模板里哪些话术更有效，这些内容一线使用者最有发言权。我在团队里推行“技能文件入库 + 评审合并”的协作方式，不仅开发者在维护，运营同学也能提修改意见。
需要注意技术门槛的平衡。参数 Schema 和工具白名单这部分还是要工程师把关，非技术同学改动作大了容易把技能调崩。我的做法是把技能包按“提示词模板区”和“配置区”分开，提示词模板大家都能提 PR，配置区必须工程师审核后才允许合并。
7.2 技能质量评估不能只看技术指标
技术指标只能反映技能执行得“正不正确”，不能反映它是否“贴合用户需求”。我后来在评估体系里加入了“场景覆盖率”这个维度——技能里定义的触发场景，有没有覆盖所有实际的用户请求类型。具体操作是把一段真实用户请求日志按意图聚类，再把聚类结果与技能的 description 做匹配，哪些请求没有对应技能，就可能是技能库的空白点。
这个评估角度很独特但很重要。比如我发现技能库里“查询类”技能很多，但用户日志里有一大堆“帮我对比两个方案”的请求没被技能库覆盖，说明团队把精力花在了已有技能完善上，忽略了新需求方向。技能库规划要跟着需求走，不是跟着技术热点走。
7.3 我踩过的一些坑和解决心得
技能模块规模小的时候，不用急着上复杂框架。我最初尝试过给每个技能都配置一个独立的 Agent，结果技能数量一多，配置工作量直接翻了十几倍，而且调试复杂度急剧上升。后来回到“共享推理层＋技能包”的简单架构，效果反而更稳定。架构应当是逐步演进出来的，不是一开始设计出来的。
另一个坑就是技能描述写得过于“机智”。有段时间我为了让技能命中率更高，把描述里加了很多热门词汇，结果误触发率直线上升。技能描述是给模型看的事实陈述，不是营销文案。它需要的是准确、清晰、边界明确，而不是花哨。
最后一个体会：技能系统的上线不是一劳永逸。模型在升级，工具在外界变化，用户需求在演变，技能包必须持续维护。我保持着每月一次“技能审计”的习惯，删除调用频次过低、输出质量不稳定的技能，调整描述覆盖不了真实请求的技能，把新出现的需求按优先级排进开发计划。对 Agent 系统来说，维护技能库的节奏，决定了这个系统能不能真正存活下来。
