Agent技能化设计：从上下文混乱到稳定可用的工程实践

前阵子好几个做 AI 应用的朋友不约而同地和我聊起同一个困惑：Agent 项目跑通了 demo，但一上真实场景就乱成一团——模型一会儿忘了前面的工具结果，一会儿又重复调用同一个接口，改 prompt 改到怀疑人生。我看了他们的代码之后发现，问题几乎都出在同一件事上：整个 Agent 只有一套大而全的 system prompt 和一堆散落的工具函数，没有任何“技能”的概念。

后来我把思路切换到“技能化”之后，情况一下子清晰了很多。所谓 agent-skills，不是让模型自己摸索着调用十几个函数，而是把一类任务封装成一个带明确说明、带输入输出约束、带执行策略的“技能单元”，Agent 需要做什么就加载什么，顺序、边界、异常处理全都提前设计好。这套思路帮我省下了大量调 prompt 的力气，也让项目从“demo 能跑”进化到“真实用户真的能用”。

这篇就把我在技能化改造过程中的完整设计、代码实现、踩坑记录一次讲清楚。适合正在做 Agent 应用、被上下文混乱和多轮调用问题折磨的开发者参考，也适合想从零搭一个可维护 Agent 体系的人了解整体脑图。

1. 先搞清楚：Agent Skills 到底是什么

1.1 从“把步骤写进脑子”到“给 Agent 装工具箱”

大多数入门级的 Agent 是这样工作的：你在 system prompt 里写清楚“你是一个助手，你可以使用以下工具”，然后模型在对话中自己决定调用哪些工具、按什么顺序调用。这种做法的本质是把工作流程的全部信息都塞进上下文里，让模型自由发挥。

问题在于，模型的注意力是有限的，工具越多、任务越长，就越容易出错。我在一个数据清洗项目里试过给模型开放 8 个工具，前几轮对话还算正常，到第 20 轮左右就开始频繁地重复读取同一个文件，甚至把上一个任务的处理逻辑套到当前任务上。后来我数了一下，那套 system prompt 加上历史消息加起来快 6000 token 了，模型其实已经“看不过来”。

agent-skills 的思路正好反过来。它不把所有步骤都堆在提示词里，而是把“做一个数据清洗报告”这件事拆成一个独立的技能模块。这个模块自带以下内容：

• 这个技能是干什么的、什么场景下用；
• 输入需要什么样的数据结构；
• 内部执行分哪几步，每步调用什么工具；
• 失败时怎么重试、怎么回报错误。

Agent 只需要在合适的时机加载这个技能，技能内部自己安排具体动作。这就好比你不去训练一个新人记住公司所有流程，而是给他一本手册，遇到哪种任务翻到对应章节照做，手册里的步骤还都是提前验证过的。

1.2 技能、工具、提示词、工作流的边界

不少人会把“技能”和“工具”混为一谈，我在最初设计时也踩过这个认知坑。简单来说，工具是技能的执行原子，技能是“工具 + 编排逻辑 + 使用说明”的组合。

举个例子：

• 工具：search_web(query)、fetch_page(url)、extract_text(html)；
• 技能：调研一个行业的最新动态——它规定先搜索、再打开排名靠前的 3 个页面、提取正文、做摘要，如果搜索失败就换关键词重试一次。

工具只回答“我能做什么”，技能回答“这件事该怎么做”。提示词则是语言的载体，它可以把一个技能的使用描述发给模型，也可以在技能内部作为步骤指令存在。

工作流和技能的区别更偏“严格程度”：工作流像铁轨，步骤顺序和分支完全预设，几乎没有模型发挥空间；技能像半自动辅助驾驶，定义了大方向和边界，中间几步允许模型做小决策，但不会让它频繁脱轨。我在实践中的感受是，纯工作流适合稳定且高频的内部流程，技能更适合需要结合模型判断力、又希望可控的开放场景。

1.3 什么时候值得引入技能系统

不是所有项目一开始就需要技能系统。如果你的 Agent 只有两三个工具，任务链条也很短，直接在 prompt 里写清楚就足够了。但当你出现下面任一信号，就是引入技能系统的时机：

• 工具数量超过 5 个，模型开始混淆功能或调用错参数；
• 同一类任务需要在多个项目里复用，你不想每次重新写 prompt；
• 任务链条超过 3 步，比如“搜索 → 摘要 → 写报告 → 发邮件”；
• 你希望给 Agent 加上权限边界，某些高危动作只允许在特定技能内部触发。

我遇到过最典型的例子是文档处理类 Agent：读文件、解析格式、提取字段、校验数据、生成表格，这五个动作如果让模型裸调，顺序经常乱；把它们封装成一个“文档解析技能”，准确率直接从 67% 提升到 91%。这个提升不来自模型变聪明了，而是因为顺序被固定，模型不需要每一步都猜下一步做什么。

2. 技能系统的整体设计思路

2.1 技能的本质：输入-处理-输出的闭环

我在设计 agent-skills 时，反复琢磨一句话：技能是模型可以按需调用的、有边界可预期的能力单元。它应该像一个黑盒，外面只暴露明确的接口，内部可以很复杂但不需要让模型感知。

为了让模型能正确使用技能，技能自身包含四个核心要素：

• 名称和描述：让模型判断“现在是否需要它”；
• 输入参数定义：模型需要提供什么信息；
• 内部执行逻辑：可以是一段固定代码，也可以是一个局部 prompt + 工具调用链；
• 输出格式和退出条件：执行完返回什么，失败时怎么反馈。

这四个要素缺一个都会出问题。我最初只写了名称和输入，没有定义输出格式，结果模型经常把技能的中间状态当成最终结果，直接截断给用户看。后来我在每个技能里都加上了output_schema，这个问题立刻消失了——模型知道什么时候算“完成”。

2.2 技能的三层结构：定义层、执行层、编排层

整个技能系统我在逻辑上分成了三层，这样既方便单独测试，也方便后续扩展。

第一层是定义层，负责描述技能本身。包括技能的唯一 ID、一句话简介、参数列表、返回结构、适用的任务类型、停用条件。这一层是给模型“看”的，所以描述要写得像一个优秀 API 文档，避免含糊词汇。

第二层是执行层，负责真正干活。它可以是一个 Python 函数，也可以是一段带子流程的指令序列。我的经验是：只要是逻辑固定的操作（如数据处理、API 调用、文件读写），尽量直接用代码实现，不要交给模型；只有需要理解语义的部分（如判断文本情感、总结要点），才引入模型判断。执行层越确定，整体越稳。

第三层是编排层，负责调度和组合技能。编排层决定当前任务该调哪个技能、多个技能之间按什么顺序串联、前一个技能的结果怎么传给下一个。这一层是 Agent 的主逻辑，也是我在实际开发中改动最频繁的部分。

2.3 接口设计决定了技能能长多大

技能之间的接口如果不统一，系统很快就会变成一团乱麻。我给所有技能定了几个强制约定：

• 输入必须是结构化的 JSON，禁止传原始文本字符串；
• 输出必须是{ "status": "success" | "error", "data": ..., "error_msg": ... }的统一结构；
• 技能内部不得访问全局状态，所有依赖都通过参数传入；
• 技能执行时间超过阈值必须返回超时标志，不能无限等待。

这些约定刚开始看起来很麻烦，但正是它们让组合多个技能成为可能。我举个反面例子：某个技能 A 的输出是表格 HTML，技能 B 需要的是 Markdown 数组，结果 B 接收后解析失败。根源就是 A 的输出没按约定结构返回。改了 A 的输出格式后，B 一行代码没动就正常工作了。

接口统一带来的另一个好处是可测试性。每个技能都能单独用一段模拟输入跑一遍，不需要启动整个 Agent。我在项目里给每个技能配了一组测试用例，每次改动代码后跑一遍，能挡住大概七成的回归问题。

3. 从零实现一个轻量技能管理框架

3.1 技能描述与 Schema 设计

我会用 YAML 来做技能定义，因为可读性好，也方便非开发人员参与编写描述。下面是一个技能定义的完整示例，这个技能负责“从网页提取正文并生成摘要”：

id: web_article_summarizer name: 网页文章摘要 description: 输入一个网页 URL，抓取正文内容并生成 200 字以内的中文摘要。适用于新闻、博客等长文页面。 tags: [web, summarization, zh] input_schema: type: object properties: url: type: string description: 文章的完整 URL max_sentences: type: integer default: 3 description: 摘要最多包含的句子数量 required: [url] output_schema: type: object properties: title: type: string description: 页面标题 summary: type: string description: 生成的中文摘要 source_word_count: type: integer description: 原文提取后的字数 execution: type: python_function module: skills.web_article_summarizer timeout_seconds: 30 retry_policy: max_retries: 2 backoff_seconds: 1

有几个技巧值得说一下。

description字段是我反复打磨的重点。一开始我写的是“抓取网页并总结”，模型总在遇到 PDF 或视频页面时也调用它。改成“适用于新闻、博客等长文页面，不适用于视频、PDF 或需要登录的页面”之后，误调用率明显下降。模型本质上是通过描述来匹配任务的，描述里的限定条件越明确，匹配越精准。

input_schema里的default字段也很重要。模型有时不会主动填所有参数，有默认值兜底，至少不会因为缺参数而调用失败。

3.2 技能注册与加载机制

我采用“目录扫描 + 自动注册”的方式来管理技能。项目结构大概是这样的：

skills/ __init__.py web_article_summarizer/ skill.yaml handler.py data_cleaner/ skill.yaml handler.py report_generator/ skill.yaml handler.py

启动 Agent 时，框架扫描skills目录下所有子目录，逐个读取skill.yaml和handler.py，构建一个技能注册表。核心代码如下：

import importlib.util import yaml from pathlib import Path SKILLS_DIR = Path("skills") class SkillRegistry: def __init__(self): self._skills = {} def load_all(self): for skill_dir in SKILLS_DIR.iterdir(): if not skill_dir.is_dir(): continue skill_path = skill_dir / "skill.yaml" handler_path = skill_dir / "handler.py" if not skill_path.exists() or not handler_path.exists(): continue with open(skill_path, "r", encoding="utf-8") as f: meta = yaml.safe_load(f) handler = self._import_handler(handler_path) self._skills[meta["id"]] = { "meta": meta, "handler": handler, } return self def _import_handler(self, path): spec = importlib.util.spec_from_file_location( path.stem, path ) module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) return module.execute def get(self, skill_id): return self._skills.get(skill_id) def list_skill_metas(self): return [v["meta"] for v in self._skills.values()]

把所有技能都放进注册表之后，Agent 在系统提示词里会看到这样一段自动生成的技能列表：

可用技能： - web_article_summarizer: 输入 URL，输出文章摘要。适用于新闻、博客长文。 - data_cleaner: 输入 CSV 路径，输出清洗后的文件路径。适用于缺失值、格式修复。

这段列表是动态生成的，每新增一个技能，Agent 自动就能“知道”。这样做的价值是技能可插拔：上线新能力时，加一个目录即可；出问题要回滚时，删掉目录或改版本号即可。你不需要在 prompt 里手工维护工具列表。

3.3 调度与组合：让 Agent 学会查手册

注册只是第一步，更关键的是让模型学会在合适的时机调用合适的技能。我在实现上参考了 OpenAI 的 function calling 思路，但做了一层额外的“技能选择器”。

整个流程是这样的：

1. 模型接收用户请求；
2. 模型从技能列表中挑选一个或多个技能，输出调用请求（JSON 格式，包含技能 ID 和参数）；
3. 框架校验参数是否符合input_schema，不合法就返回参数错误，不直接执行；
4. 框架执行对应 handler，捕获超时和异常，包装成统一结果返回给模型；
5. 模型根据技能返回结果，继续后续对话或调用下一个技能。

这段流程听着不复杂，但第 2 步里最容易出问题——模型选错技能。我在实盘中发现，给模型的技能描述如果超过 15 个，选择准确率会大幅下降。解决方法是给技能加tags，在送入模型前做一次关键词预筛选。比如用户问“帮我把这个网页总结一下”，我优先筛选web和summarization标签下的技能，只把 3 到 5 个候选技能展示给模型，准确率立刻回到 90% 以上。

预筛选的代码大致是：

def filter_skills_for_query(query, registry, top_k=5): scores = [] for skill_id, entry in registry._skills.items(): meta = entry["meta"] score = 0 for tag in meta.get("tags", []): if tag in query: score += 1 score += sum(1 for kw in meta["description"].split("适用于")[-1:] if kw.strip() in query) scores.append((score, skill_id, meta)) scores.sort(reverse=True, key=lambda x: x[0]) return [s[1:] for s in scores[:top_k]]

这个方案很轻量，不需要引入向量检索，但效果远好于把全部技能堆给模型。如果你的技能数量超过 30 个，再考虑用嵌入式向量做语义召回也不迟。

3.4 完整执行示例：从技能选择到结果返回

让我用一个完整的例子演示整个调用过程。假设用户发来一条消息：“帮我看下这个网页里讲了啥，https://example.com/intro”。

框架收到消息后，先执行预筛选，匹配到web_article_summarizer技能，把它以及另外两个可能相关的技能一并注入模型上下文。模型判断后生成如下调用请求：

{ "skill_id": "web_article_summarizer", "arguments": { "url": "https://example.com/intro" } }

框架校验参数通过，调用 handler：

async def execute(url, max_sentences=3, **kwargs): try: html = await fetch_page(url) text = extract_main_text(html) summary = generate_summary(text, max_sentences) return { "status": "success", "data": { "title": extract_title(html), "summary": summary, "source_word_count": len(text), }, } except Exception as e: return { "status": "error", "error_msg": f"页面抓取或摘要生成失败: {str(e)}", }

执行完成后，框架把结果作为一条工具消息返回给模型：

{ "role": "tool", "skill_id": "web_article_summarizer", "result": { "status": "success", "data": { "title": "Intro Page", "summary": "这是一个介绍性质的页面...", "source_word_count": 1200 } } }

模型拿到结果后，用自然语言组织成对用户的回复。整个过程模型只做“决策”——选什么技能、传什么参数、怎么根据结果回答——而真正的“执行”完全由代码控制，避免了模型在抓取或解析过程中“自由发挥”。

我在这个架构里最大的体会是：代码负责稳定，模型负责弹性。固定逻辑全部下沉到技能代码里，模型只做那些真正需要理解和判断的部分。这样既保证了结果的可靠性，又保留了模型的灵活性。

4. 在真实项目里打磨技能的实操经验

4.1 数据清洗项目里的技能沉淀

理论说完了，说说我在一个真实落地项目里的经验。这个项目的任务是做一个数据清洗 Agent，输入是一个 CSV 文件，输出是一份清洗报告和清洗后的文件。初始版本是把所有清洗规则都写进 system prompt，结果模型经常漏掉某条规则，或者把规则用错顺序。

后来我把清洗过程拆成四个技能：

• profile_data：读取文件，统计缺失率、类型分布、重复行，输出数据画像；
• deduplicate_rows：基于指定的关键列去重；
• clean_missing_values：按列策略填充或删除缺失值；
• generate_report：汇总前面的操作记录，生成清洗报告。

这四个技能按照“先画像、再去重、再补缺失、最后出报告”的顺序串联。编排层用的是最简单的顺序执行：上一个技能的输出作为下一个技能的输入之一。

这套流程上线后，效果立竿见影。以前模型会跳过画像直接清洗，导致后面统计报告没数据可写；现在顺序被技能系统锁死，报告准确率从 72% 提升到 95%。这个提升主要来自任务边界清晰化——每个技能只需要管好自己那一小步，模型不再需要在大上下文里追踪完整流程。

4.2 参数设计与失败重试

技能参数设计是我在打磨过程中踩坑最多的部分，尤其是参数粒度问题。

一开始我把参数设计得太细，比如取出摘要技能，我加了language、length_penalty、temperature这些参数。结果模型经常传错值，不是因为模型笨，而是参数太多、太专业，模型根本不知道该怎么合理取值。后来我砍到只剩url和max_sentences两个业务参数，调用失败率立刻降了下来。

我的经验是：不要暴露模型不理解的底层参数。像temperature这类模型参数应该由技能代码内部固定，而不是开放给模型调。技能对模型暴露的参数必须是用户请求里自然存在的业务要素，例如 URL、文件路径、列名、问题描述等。

失败重试策略上，我用的是经典的指数退避方案。第一次失败等 1 秒重试，第二次失败等 2 秒，最多重试 3 次。重试之间要确保技能内部没有副作用残留，比如已经写入了一半的临时文件，重试前需要清理。

一个让我印象很深的坑：某个技能调外部 API，第一次调用因为网络超时失败，但实际服务端已经处理了请求。重试后数据被重复提交，产生脏数据。后来我给所有写操作类技能都加了幂等键——每次调用生成一个唯一 request_id，服务端用这个 id 去重。这个改动彻底解决了重试带来的重复问题。

4.3 技能评估：怎么知道技能好不好使

不评估技能质量，就不知道改动是变好还是变坏。我用一套简单但有效的评估方法，大概分三层：

第一层是单元评估，对每个技能准备 10 到 20 条测试输入，覆盖正常、边界、异常三类情况。比如摘要技能，我会准备一篇正常文章、一篇超长文章、一个 404 页面。跑完看通过率，低于 80% 的技能不进入系统。

第二层是组合评估，把技能按典型业务链路串起来跑一遍端到端任务。比如数据清洗项目里，我用 5 组脏数据文件，跑完全链路，看最终报告是否完整、字段是否合理。这一层能发现单个技能正常但组合在一起的接口问题。

第三层是线上抽样，把实际用户行为中随机抽取的成功和失败案例记录下来，每周复盘一次。我的做法是给每个技能调用都打日志，记录技能 ID、输入摘要、输出状态、耗时，然后用一个小脚本统计成功率随版本的波动曲线。

这三层评估看起来投入大，实际成本并不高。单元评估跑一次不到一分钟，组合评估大概三分钟。但它帮我挡住了大量“感觉改好了、实际上改坏了”的回归问题。我最常说的一句话是：没有评估体系的技能系统，改代码全靠玄学。

5. 常见问题与排查技巧

5.1 技能调用失败的经典场景

技能系统上线之后，最常见的失败不是代码 bug，而是模型没按预期调用技能，或者技能参数传错。我整理了几类高频问题和对应的排查思路：

第一类是模型总是不调用技能，直接尝试自己回答。这种情况几乎都是技能描述不够清晰，模型没意识到当前任务属于某个技能。我解决的方法是给技能加“触发条件”描述，例如：“当用户提供 URL 并要求总结时，必须调用本技能，禁止直接根据 URL 的字符串内容编造答案。”加了这句，模型就老实了。

第二类是技能选择正确但参数传错。比如用户提到“把这份 CSV 里的重复行去掉”，模型调用去重技能时把文件路径写成了用户原文里的文件名，而这个文件名并不存在。排查思路是先看调用日志，确认模型传入的参数值，再回头调整描述，明确指出“文件路径必须是实际存在的绝对路径，不要凭空构造”。

第三类是多技能串联时结果对不上。比如上个技能输出data是 JSON，下个技能却当成纯文本处理。这种情况要去查两个技能的output_schema和input_schema是否匹配。我统一了所有技能的结果包装格式之后，这类问题几乎绝迹。

5.2 上下文污染与技能隔离

技能执行时会产生中间日志、临时变量、工具错误信息，这些内容如果不加控制地全塞进模型上下文，会严重干扰后续推理。我的原则是：默认只把技能的结果摘要和必要信息回传模型，过程细节全部留在日志里。

具体做法是给每个技能加上summarize_result方法，把返回数据压缩成 2 到 3 行摘要。比如数据画像技能，原始输出是一个包含 20 个统计指标的 JSON，但回传给模型的摘要只有三句话：“总行数 1044 行，缺失值集中在 age 列（占比 12%），重复行 8 行。”模型有了这个摘要，已经足够决定下一步操作，没必要看 300 行原始统计。

同时，技能内部不要使用模型上下文存临时状态。我见过一个项目，把上一步的清洗记录直接作为文本追加到 system prompt，结果上下文越来越长，模型越来越“糊涂”。技能之间的数据传递必须通过显式返回值，而不是偷偷改上下文。

5.3 技能冲突和优先级

当一个动作可以由多个技能完成时，模型多半会选错。比如“生成一份报告”既能用data_cleaner.generate_report，也能用web_article_summarizer勉强凑一份，模型就可能选到后者。

我处理冲突的办法分三步。第一步，给技能加priority字段，同领域技能冲突时优先选高优先级。第二步，在描述里明确写“本技能只处理 XX，不要用它处理 YY”。第三步，也是最狠的一步，把明显不能胜任任务但容易被误选的技能从候选列表里剔除。

在编排层我还引入了一个观察点：模型反复在两个技能之间横跳时，日志里会打出一条“犹豫”标记。这时我去看上下文，通常是两个技能的 description 太相似，或者用户请求有歧义。修复手段不是加更多提示词，而是把两个技能的边界描述彻底分开。

5.4 经典故障排查速查表

下面这个表是我平时排查问题最常用的对照表，看到什么现象就直接找对应根源：

排查这一类问题，我最大的心得是：日志比 prompt 重要得多。给每个技能调用一行结构化日志，记录下“模型选了什么、传了什么、技能返回了什么、花了多久”，90% 的故障都能在日志里直接看穿。不要在模型输出上猜来猜去，去查日志，答案就在里面。

6. 技能系统的后续扩展方向

整套 agent-skills 体系搭建完成后，我还做了一些扩展，算是给这个系统的未来留了接口。

第一个扩展是技能版本管理。每个技能目录里加一个version字段，注册表里保留最近 3 个版本的 metadata，模型仍然只用当前版本，但随时可以切回旧版本。这个功能在小规模项目里看着多余，一旦技能数量上了 20 个，手动回滚就是必备能力。

第二个扩展是技能之间的显式编排脚本。有些固定业务链路，比如“调研 → 总结 → 生成周报 → 发送邮件”，我不想让模型每一步都重新决策，就用一个简单的编排脚本把技能串起来。脚本本身也是一个“超技能”，暴露给模型的是“一键执行早报流程”这样的入口，大幅减少模型的多步调用次数。

第三个扩展是技能记忆。某些技能执行时依赖用户偏好，比如摘要字数偏好、数据清洗时是否保留全角字符。我在技能内部加了一个轻量的偏好存储，第一次执行时记录用户选择，后续执行时自动沿用。当然这里要控制权限，不能因为一次偏好就永久固化，我给偏好记录加了一个“只保留最近 N 条”的窗口。

第四个扩展是技能市场基座。当团队里多个项目都需要技能时，我会把技能包发布到一个内部仓库，其他项目直接拉取使用。因为技能本身是纯代码 + 纯配置，天然适合版本化分发。这样可以不断沉淀团队经验，避免“每个项目重写一遍清洗逻辑”的浪费。

这些扩展不需要在第一天就全部搭好，但设计时预留好接口，后面加功能会顺手很多。核心就是把“技能”当成系统的一等公民：能被注册、被调用、被回滚、被复用，而不是深埋在 prompt 里的一段文字。

我个人在实际操作中还有一个体会想分享：所有技能框架的最终目标，是让模型需要做的决策越来越少。如果你发现某个技能系统上线后，模型还要费很大劲才能完成一个任务，那大概率不是模型的问题，而是技能切得不够细，边界画得不够清楚。每当我遇到代码或者 prompt 改不动的情况，我就会回头审视一次技能边界，大多数时候问题会自己浮出来。希望这篇能帮你在自己的项目里少走几个来回。