最近一直在折腾一个叫“agent-skills”的东西说白了就是给 AI Agent 搭一套“技能体系”。如果你玩过 Agent 开发一定遇到过这种尴尬模型本身挺聪明但让它“打开浏览器查资料”“处理一份 Excel”“调一下内部 API”它就一脸懵——因为没人告诉它这些操作要怎么做。技能体系解决的就是这个问题把 Agent 能执行的动作、能调用的工具、能完成的任务规范成一套可注册、可发现、可复用的“技能包”让 Agent 真正做到“召之即来来之能用”。这篇文章想把我这段实践中的经验和教训完整记录一下。内容包括技能层为什么要存在、边界怎么画、注册表和调度逻辑怎么写、参数协议怎么定、踩过哪些坑以及团队协作时怎么维护这套体系。无论你是刚接触 Agent 开发还是已经在做生产级智能体项目应该都能找到点有用的东西。这里不会讲那些虚的概念全是能直接抄走的代码和配置。1. 为什么要给 Agent 搭一套技能体系先说一个很现实的问题Agent 和普通聊天机器人的本质区别在于它会“动手做事”。但模型本身只是个决策器它不会真的去打开文件、发请求、操作数据库。所以我们要给 Agent 装上“手”——这就是技能。我在早期做 Agent 时没这个概念当时的做法很粗暴把所有工具函数一股脑塞进 System Prompt让模型自己根据描述去选。结果越往后越痛苦。工具几十个之后Prompt 又长又乱模型经常选错工具或搞错参数加一个新工具要在代码里改一堆地方不同类型任务想复用另一套工具的代码基本靠复制粘贴。这些问题让我意识到必须有一个中间层把“工具调用”这件事规范化、可插拔化。“agent-skills”这个项目的核心就是想做成这样一套规范。它不关心底层模型是谁也不绑定某个框架而是定义了一种让 Agent 以统一方式发现和调用技能的方式。就像手机上的应用商店——技能包就是一个个 AppAgent 是手机操作系统注册表是应用商店模型通过描述信息去决定装哪个 App 来执行任务。这么做的好处有几个。第一Prompt 瘦身了模型不需要看到所有技能细节只需要看到技能名称和一句描述具体怎么做藏在技能包内部。第二技能可以独立开发和测试任何一个人新增一个技能包不影响其他功能。第三执行逻辑和决策逻辑解耦了模型的“决策”负责选技能技能的“执行”负责做操作两边可以单独优化和排查问题。我记得第一次把这套结构搭建完成时最大的体感是调试变舒服了。以前 Agent 出错得翻完整段对话才能定位是不是工具调用出了问题。现在可以直接看“模型选了哪个技能、参数传了啥、技能返回了啥”相当于给 Agent 加了一层可观测性。这一点对生产环境太重要了。1.1 技能和工具、工作流、插件的边界在哪“技能”这个词很多人会跟工具Tool、工作流Workflow、插件Plugin混在一起说。我自己的理解是工具是最底层的原子能力比如“发送 HTTP 请求”“执行一段 Python 代码”工作流是多个工具的组合编排比如“先查天气再决定要不要带伞”插件是带业务语义的封装集合比如“钉钉插件”包含发消息、建群、审批等一整套接口。技能层夹在中间粒度比工具粗、比工作流细。一个技能通常是对某个“可以做的一件事”的完整封装比如“技能搜索近三天社区内的技术讨论帖”可能内部会调用搜索工具、排序工具、摘要工具但对 Agent 来说它只需要知道“能搜帖子”这一个入口就行。不要让 Agent 去编排底层工具那样既容易出错又慢技能层的作用是帮 Agent 把复杂任务缩成一个可调用的选项。边界问题特别容易犯两个错。一是技能太大一个技能里塞了十几个子操作Agent 按需只调用一部分结果文档描述都写不清到底什么情况该用它。二是技能太碎一个技能只包一层 HTTP 请求跟直接用工具没区别还多绕一层。我后来的判断标准是如果这个技能用一句 30 个字以内的话说不清“什么时候用、能拿到什么结果”那就说明粒度不对要么拆要么合。还有一个经验技能最好是“状态无关”的。同一个技能不要依赖上一次 Executor 里的内部状态每次调用都是一个完整的原子过程。因为 Agent 的调用顺序和上下文是不可控的如果技能内部残留状态第二次调用很可能出诡异的结果。我写过的一个文件合并技能早期就吃了这个亏第一次合并结果会被第二次调用追加进去后来把所有中间状态改成只从参数重新构建问题就没了。1.2 项目的目录结构和命名规范动手写代码之前建议先把目录结构和命名规范定下来。我见过很多项目一开始没在意这个技能多了之后找文件全靠搜索维护成本极高。我当前项目里的目录结构大致是skills/ search_local_docs/ SKILL.md schema.json executor.py requirements.txt assets/ send_email_report/ SKILL.md schema.json executor.py requirements.txt data_analysis/ SKILL.md schema.json executor.py requirements.txt registry.yaml shared/ auth_provider.py network_client.py logging_conf.py每个技能独立成一个目录目录名是技能的唯一 ID命名用 snake_case一眼能看出这个技能是干嘛的。SKILL.md 是给模型看的描述文档schema.json 是给系统看的参数定义executor.py 是真正干活的入口。registry.yaml 是全局注册表用来登记哪些技能对哪些场景可用。这样不管是人还是 Agent都能快速定位一个技能的位置和用途。命名规范这地方多说两句。技能名称不要用太长的一段话最好是“动词_名词”比如 search_local_docs、send_email_report、generate_chartAgent 在选择时更容易理解。避免用项目专属的缩写词比如内部叫 “MCP” 但别人不知道什么意思模型也可能被你绕晕。技能目录里的 SKILL.md 和 schema.json 一定要有这是技能能被 Agent “发现”的关键。没有这两个文件就算 executor 写得再多Agent 也不知道这个技能该怎么用。2. 技能层的核心设计思路设计技能层不是写几个 Python 模块那么简单关键的决策集中在三个点上怎么注册、怎么描述、怎么调度。这三个点直接决定这套体系用起来顺不顺手、维护起来痛不痛苦。先讲注册机制。我采用的是“声明式注册配置文件扫描”的方式。一个新技能要加入系统只需要两步在 skills 目录下新建一个技能文件夹填好 SKILL.md 和 schema.json然后在 registry.yaml 里登记一条记录指定技能 ID、启用的场景标签、权限级别。系统启动时扫描 registry.yaml 加载技能运行时按场景动态把技能暴露给 Agent。这种方式比在代码里硬编码注册要灵活得多新增技能不用改主程序代码改完配置文件重启即可。但配置驱动有一个隐患加载顺序和依赖关系容易出问题。比如技能 A 依赖共享库里的 auth_provider如果技能 A 被单独加载时没有把那个共享模块所在目录加入加载路径import 就直接失败。我在项目里把 shared 目录做成一个动态插入 sys.path 的模块技能 Executor 里所有共享依赖都以绝对包名导入避免相对路径出现问题。这个是第一次部署时踩到的坑当时整整查了两个小时才定位到是路径问题。再讲描述文件。SKILL.md 的作用是“教模型怎么用这个技能”而不是“向程序员解释这个技能怎么实现”。写法和项目文档完全不是一回事。我一般分成几块写一句话说明这是做什么的什么时候应该用这个技能什么时候不應該用必要的前置条件和上下文要求一个简短的调用示例。语言保持简短不要超过 300 字。模型读 Prompt 是有长度限制的技能描述写得越长系统能装下的技能数量就越少。schema.json 则是给系统读的参数定义。定义 Agent 需要传哪些参数、类型是什么、哪些必填、边界值是什么。我会把 description 字段写得非常具体。模型填充参数时依据的是这个 description描述得越细参数填得越准。比如你要一个日期参数不能只写 “date”要写 “支持 YYYY-MM-DD 格式的日期指任务执行当日不要接受历史日期或未来超过 7 天的日期”。模型真的会认真读这些小字所以别嫌麻烦。最后说调度。调度层接收到模型输出的技能调用指令后要做几件事校验技能是否存在、校验参数是否符合 schema、执行权限检查、把参数传给 executor、捕获执行过程中的异常并格式化返回结果。这里最容易被忽略的是“结果反馈格式”。如果 executor 返回的是一整段自由文本模型后续的推理会很难受如果返回的是结构化 JSON比如 {code: 0, data: {...}, message: ...}模型就能精准地拿其中某个字段做下一步操作。我的项目里所有技能都必须返回结构化结果未达标的一律在测试阶段打回。2.1 参数字段设计让模型少犯错的技巧参数字段设计是整个技能层里对“模型调用正确率”影响最大的一环很容易被低估。我之前写过几个技能参数只定义了名称和类型没有写边界条件和说明结果模型的错误率高得离谱——日期格式五花八门、缺了必填项、传了会导致越界的值。后来把描述写细之后正确率直接上了一个台阶。一个完整的参数定义模板大致是这样{ name: query_text, type: string, description: 要搜索的关键词2~50个字符不要包含特殊符号多个关键词用空格分隔, required: true, default: null, allowed_values: null }每个字段都有它存在的意义。description 给模型语义理解required 告诉模型这是不是必填default 提供安全和兜底allowed_values 则是在枚举场景下做硬校验。特别建议在描述里写清楚“不要”做什么模型对否定约束的理解能力比许多人想象的要好。比如“不要传 HTML 标签”“不要传已经被合并的分支名”这类约束显著减少错误调用。枚举类和范围类参数能用 allowed_values 或 min/max 描述就尽量写全。模型有概率生成一个在 schema 上合法但业务上不可用的值。有一回我的“图表生成”技能接受一个颜色参数类型是 string 且必填模型传了一个 “blue-ish”图表库直接报错。后来把可选值规定为 “blue, red, green, yellow, purple, orange” 几种枚举同样场景下错误率就从接近三成降到了接近零。如果技能内部有内部状态或依赖全局配置不要在参数里暴露给模型。比如技能需要“当前用户 ID”通过全局上下文注入不让模型传既避免恶意篡改也减少出错。总之一句话你能给模型设定的边界越清晰模型的表现越稳定。2.2 技能描述怎么写才不会被模型误解技能描述的撰写原则可以总结为“三短一明确”名称短、描述短、示例短但适用条件要明确。很多人的技能描述犯一个通病——强调“能做什么”却不说“什么时候该用”。举例说“数据分析”技能的描述如果只写“该技能可以执行 Pandas 数据分析支持分组、聚合、可视化、统计检验等”模型面对一个简单的求和需求时很可能不调用技能而是自己瞎算或者用了一个复杂度远超需求的技能。我自己的习惯是把描述拆成两句。第一句用最多 30 个字说明“这个技能做什么、产出什么”比如“对上传的 CSV 文件执行分组统计并输出结果表格”。第二句写“适用于什么场景”比如“当用户上传 CSV 并询问平均、合计、分维度统计时使用如果只是简单一两行列表直接用内置计算能力就好”。多写一句触发条件模型选择准确率会有明显提升。还要注意的一点不要把命令式细节写进描述。有些技术博主喜欢在描述里写上“内部调用了 xx 库的 yy 函数”这没有任何帮助反而让模型困惑。对模型而言它要的是“做什么”和“什么时候做”不是“怎么实现”。实现细节应该放在 SKILL.md 最后面的人话备注里仅给维护的人看。示例也非常重要。给一个参数填充的录例模型会照着你的格式来。比如日期参数你示例写 “2025-03-15”模型大概率会输这么多格式而不靠猜。示例要穷尽边界条件要给出正常、空值、异常三种情况下的处理方式。代码里记得处理边界比如空列表、空字符串、空操作。Agent 的指令可能来自用户的随意表达遇到边界情况必须能兜底而不是抛异常。3. 实操一个可落地的技能注册与调度系统讲了这么多原则没有代码始终是空谈。这里把我在 agent-skills 项目里实际用的一套最小可运行系统写出来。它不依赖任何特定框架只用 Python 标准库加一个轻量的 schema 校验。你可以直接把这一套迁到 LangChain、AutoGen 或者自研 Agent 框架里。先看整体流程。系统启动时读取 registry.yaml 得到可用技能列表Agent 的 Prompt 中会注入所有技能的“名称摘要参数字段摘要”模型决策后输出一个结构化的技能调用指令调度器收到指令后执行参数校验、权限校验、调用 executor、标准化返回结果如果执行中出现异常统一抛给上层由 Agent 决定是否重试或返回给用户。这一条链路里的每一步都可以独立测试和替换。我实际用的注册表结构是这样的version: 1.0 default: [search_local_docs, send_email_report] skills: - id: search_local_docs enabled: true scopes: [default, research, office] permissions: [read_local_files] executor: skill_search_local_docs.executor:run max_retries: 2 timeout: 30 - id: send_email_report enabled: true scopes: [default, office] permissions: [send_email] executor: skill_send_email_report.executor:run max_retries: 1 timeout: 15 - id: data_analysis enabled: false scopes: [] permissions: [run_python_code] executor: skill_data_analysis.executor:run max_retries: 0 timeout: 120每个技能后边的字段都不是随便写的。enabled 是总开关false 的技能不会出现在 Agent 视野里。scopes 控制“这个技能在哪些业务场景下可见”避免理财场景的 Agent 误挂一个发邮件技能。permissions 用于执行前的权限校验一个只读任务的技能就不该有任何写操作的权限。max_retries 和 timeout 根据技能实际耗时来决定——发邮件这种操作重试一次就够数据分析可能要 2 分钟不能用一个统一值。核心调度器代码大致如下import importlib import jsonschema import yaml import logging from pathlib import Path class SkillRegistry: def __init__(self, config_pathregistry.yaml): self.config_path Path(config_path) self.skills {} self._load() def _load(self): with open(self.config_path) as f: config yaml.safe_load(f) for item in config[skills]: if not item[enabled]: continue self.skills[item[id]] item logging.info(loaded skills: %s, list(self.skills.keys())) def list_skills_for_scope(self, scope): return [ {id: s[id], description: self._read_description(s[id])} for s in self.skills.values() if scope in s.get(scopes, []) ] def _read_description(self, skill_id): skill_path Path(skills) / skill_id / SKILL.md return skill_path.read_text(encodingutf-8)[:500] class SkillExecutor: def __init__(self, registry): self.registry registry def execute(self, skill_id, params, scope, contextNone): skill self.registry.skills.get(skill_id) if not skill: raise KeyError(fskill {skill_id} not found) if scope not in skill.get(scopes, []): raise PermissionError(fskill {skill_id} not allowed in scope {scope}) self._validate_params(skill_id, params) module_path, func_name skill[executor].split(:) module importlib.import_module(module_path) func getattr(module, func_name) try: raw_result func(params, context or {}) return self._normalize(raw_result, skill_id) except Exception as exc: logging.exception(skill %s execution failed, skill_id) return {code: 500, message: str(exc), data: None} def _validate_params(self, skill_id, params): schema_path Path(skills) / skill_id / schema.json with open(schema_path) as f: schema json.load(f) jsonschema.validate(instanceparams, schemaschema) def _normalize(self, raw, skill_id): if isinstance(raw, dict): return {code: 0, data: raw, message: ok} return {code: 0, data: {result: str(raw)}, message: ok}这段代码看着不复杂但几个细节还是值得琢磨一下。jsonschema.validate 会直接抛异常如果不想让模型看见冗长堆栈可以在调用处统一捕获并转成一条友好的错误消息。importlib 动态导入让每个技能成为独立模块按 skill 的 executor 字段导入即可新增技能无需修改主程序。context 参数用来传入用户身份、全局配置等技能运行需要的上下文技能运行时不能自行去读环境变量或者全局单例否则在并发场景下会互相污染。还有一个容易踩的坑sample 里用了 Path(skills)这个路径是相对当前工作目录的。如果程序从别的目录启动路径就会失效。建议改成根据file计算绝对路径或者把 skills 目录做成一个安装包。第一次部署时我因为在 systemd 里设置了 WorkingDirectory 没注意到导致生产环境加载不到技能还是用绝对路径后稳定了很多。3.1 一个真实技能的例子本地文档搜索为了让你看清“技能包”里每个文件该长什么样我拿项目里的search_local_docs技能做例子拆解一下。这个技能的作用是根据用户输入的关键词在本地某个目录中检索文本文件返回匹配文件的路径和摘要片段。先看 SKILL.md# search_local_docs 核心功能在已授权的本地文档目录中按关键词搜索文本文件返回文件路径、修改时间和匹配片段。 适用场景用户要求查找/搜索/找到某个文档、某段内容且目标范围在本地文档库内。 不适用场景找不到任何本地目录或需求涉及网络公开信息检索。 使用示例用户说帮我查一下关于季度汇报的文档则传入 query季度汇报。这段描述既告诉模型“什么时候用”也告诉模型“什么时候别用”后者的价值有时候更大。模型不会因为描述短就少干活反而因为触发条件清楚了调用的准确率提高不少。schema.json 长这样{ type: object, properties: { query: { type: string, description: 搜索关键词2~50个字符多个词用空格分隔不要包含引号或特殊符号, minLength: 2, maxLength: 50 }, max_results: { type: integer, description: 最多返回结果数默认5不要超过10, minimum: 1, maximum: 10, default: 5 } }, required: [query] }executor.py 内部实现的核心逻辑就是遍历目录、读文件内容、做一次简单的关键词匹配、按匹配次数排序返回def run(params, context): query params[query].strip() keywords [k.lower() for k in query.split()] doc_dir context.get(doc_dir, docs) max_results params.get(max_results, 5) matches [] for p in Path(doc_dir).rglob(*.md): content p.read_text(encodingutf-8, errorsignore) lower_content content.lower() if all(k in lower_content for k in keywords): snippet _make_snippet(content, keywords[0]) matches.append({ path: str(p), modified: p.stat().st_mtime, snippet: snippet, }) matches.sort(keylambda x: x[modified], reverseTrue) return {matches: matches[:max_results]}这里有一点很关键executor 不应该承载任何业务策略它就是个执行器。要不要对结果排序、按什么排序虽然也是代码逻辑但我更愿意把这种“偏好”放在技能内部的代码里而不是让 Agent 传参。因为模型的判断不稳定同一个排序需求在不同对话里可能生成不同的传参方式给出带默认值的参数是最稳妥的。3.2 测试框架每个技能都能独立验证技能一旦多了手动测根本测不过来。我后来给每个技能配了一个独立的测试脚本放在技能目录下的tests/里用 pytest 统一跑。测试要覆盖几个维度正常输入是否符合预期缺参、错参、超范围参数是否能正确拦截技能在模拟的异常环境中是否能返回结构化错误而不是裸异常参数校验不通过时错误信息是否能在不泄漏堆栈的前提下让上层 Agent 看懂。一个典型测试用例大致长这样def test_search_local_docs_normal(): ctx {doc_dir: tests/fixtures/docs} result run({query: 季度汇报, max_results: 3}, ctx) assert result[code] 0 assert len(result[data][matches]) 1 def test_search_local_docs_bad_param(): ctx {doc_dir: tests/fixtures/docs} try: run({query: x}, ctx) except Exception: return raise AssertionError(should not reach here)一套完整健全的技能测试会让你后续迭代模型时放心很多。我每次换一个底层模型都会把所有技能测试跑一遍看调用成功率、参数正确率有没有变化。这比在对话里一个一个试要快得多。如果你现在还没有任何回归测试我建议立刻从最重要的两个技能开始建这个投资非常值。4. 常见问题与排查技巧实录实操过程中一定会碰上各种奇奇怪怪的问题。这里挑几个在 agent-skills 项目里出现过的典型问题记录一下排查思路和解决方案。这些问题普遍性很强你大概率也会遇到。4.1 模型总是选错技能怎么办最典型的场景有两三个技能功能很接近比如“搜索本地文档”和“总结本地文档”模型面对“帮我整理一下这个目录下的季度总结”这种问题经常选了搜索而不是总结。排查下来根本原因通常出在“技能描述不够有区分度”上。两个相近技能的描述如果都能覆盖同一个用户意图模型分不清是很正常的。解决办法是给每个技能写一个“排他性描述场景”搜索技能写明“只负责找到文档的具体位置和片段不生成总结内容”总结技能写明“接收一组明确列出的文档路径对内容进行归纳不负责查找文件”。描述之间要有互补性而不能是重叠性。另一种情况是技能本身使用门槛太高导致模型回避。比如技能需要三个参数而用户只提供了一半信息模型发现参数不足可能就放弃了。这时候应该在技能内部支持可选参数和默认值让模型即使参数提供不全也能安全执行或者在描述里明确写“缺少参数时会使用默认值无需向用户确认”。把模型调用技能的心理负担降到最低准确率自然会上去。4.2 技能执行成功但结果不符合预期这种问题真的很磨人。技能没有报错code 返回 0但拿到结果一看根本不是用户想要的。定位这种问题得把“模型决策”和“技能执行”两头拆开来看。我习惯的做法有三个第一详细记录模型实际传入的参数很多时候是参数在边界处被模型填了一个语义相近但完全不同的值比如把”项目负责人“填成了“邀请函”这个看日志立刻就能发现。第二打印技能返回的中间过程。如果技能的第一次输出和最终结果不一样那说明是后续处理步骤出了问题。这里建议在技能内部逐步记录中间结果而不是只记录最终返回值。像是做数据分析的技能我会把“接收到的数据形状”“清洗后的结果”“聚合后的结果”分别打印出来问题出现在哪一步就一清二楚了。第三要重视”将用户问题的原始表述与参数实际值做对比“。有时候模型在参数里擅自做了改写比如用户说“最近一个月”模型把参数填成了“last_7_days”这种问题不是报错级别的问题但结果是错的。针对这种情况我会在 schema 的 description 里强调“必须原样使用用户的时间描述不要自行换算”这比在代码里做一堆日期转换要有效得多因为模型才是理解歧义的关键节点。4.3 并发和多租户场景下的状态串扰这个问题可能比较进阶但如果你开发的 Agent 要服务多个用户或跑在服务端上几乎必然遇到。典型症状是用户 A 触发了“发送周报”技能结果收到邮件的却是用户 B。根因是技能内部把“当前用户”作为全局变量存储了两个请求并发执行时互相覆盖。解决这个问题强制要求所有技能的状态都从 params 和 context 参数里面读不依赖任何全局可写变量。context 中每个用户的上下文是独立的是由上层 Agent 框架负责注入的。规则虽然很简单但在实际落地时总有技能不小心用了模块级变量或缓存对象。我在代码评审时会专门盯这一点。另一个办法是给技能实例化加上用户级的隔离每个用户持有一个独立的技能执行器实例但那样成本偏高还是尽量从代码规范上解决。4.4 技能数量太多导致 Prompt 超长或选择困难技能从几个涨到几十个之后即使每个技能描述压缩到 200 字光技能列表就占了 5000 字以上的 Prompt 空间。模型面对二三十个选项时选择准确率也会下降。这里的解法是两层。第一层按场景分组Agent 每次对话只加载与当前场景相关的技能子集比如“写作场景”就只挂文案技能“办公场景”只挂文档和邮件技能。上一节说的 scopes 字段就是这个用途。第二层技能描述再做一次摘要处理。给模型看的描述可以压缩到 30 个字以内只保留触发条件完整描述放在开发者后台供人工查看。模型对简洁的条目反而更敏感。我曾经在 20 个技能的配置下测试过完整描述版的选择准确率反而低于摘要版因为模型分配给每个技能的注意力更少干扰项更多。所以为模型做减法对效果提升是很明显的。4.5 技能执行超时和卡死有些技能偶尔会出现运行时间超出预期甚至完全卡死的情况。比如搜索本地目录时遇到一个巨大的文件、数据分析技能读了一个几十 MB 的 CSV都会让整个 Agent 回复变慢。超时控制在注册表里有配置字段但真正重要的是技能 executor 内部要主动配合。避免一次性读取超大文件进内存文件行数多时建议设置行数上限网络请求要设置显式的超时时间不要依赖系统默认值数据分析类的技能对数据集做个行数/列数检查超限时立刻返回友好错误而不是硬跑。还有一个容易被忽略的点技能内部不应该有无界循环。比如“重试直到成功”这种逻辑要设置最大重试次数。一种更隐蔽的情况是技能内启动了一个后台线程但主线程返回了导致看起来执行完成但实际上后台还在占资源。我的要求是技能执行结束后必须保证没有挂在后台的未完成任务。在测试环境里我会用 eventlet 或 gevent 的 monkey patch 配合超时断言强制暴露这类问题。5. 维护成本与性能优化技能体系建立起来之后的维护才是真正考验工程能力的地方。代码层面的维护相对好做最难的是“技能功能跟实际业务需求之间的匹配”。经常出现的情况是模型升级了以前不擅长的事现在能直接做了原来为了弥补模型能力而写的技能就变得多余或者业务逻辑变了技能内部的数据源、权限模型、输出格式全都要跟着改。我会定期做“技能清理”和“技能合并”的复盘把调用量低的、描述与新模型能力冲突的技能下线这个动作对整体性能的提升很明显。性能优化里最值得投入的一项是技能加载的缓存机制。技能加载时大部分开销在读取 SKILL.md 和 schema.json、编译 Python 模块、初始化网络连接。如果每次运行都重新来一遍耗时感人。我会做一个带时间戳和文件哈希的缓存文件没变化就直接用缓存的加载结果实测能节省 30% 以上的冷启动时间。但一定要注意缓存的失效问题技能代码内容变了但缓存还在就会加载到旧代码。最简单有效的方式是在加载时计算文件的 mtime 做比对代价小且绝对可靠。网络连接相关的技能也要做连接复用。比如发邮件、调 API 的技能如果每次都新建立连接TCP 握手和 TLS 握手都要浪费几百毫秒。维护一个全局连接池技能运行时从连接池里取连接用完还回去这是比较常见的优化手段。还要注意技能如果超时了要把连接标记为失效并销毁否则拿一个坏连接去重试只会持续失败。我上一版邮件技能就吃过一个坏连接一直重试的亏后来加了健康检查才稳定下来。日志和可观测性也是维护时很容易忽略、但恰恰是最重要的部分。每个技能的调用都应该记录模型选择的技能 ID、实际的入参、执行耗时、返回码、错误信息必要时要记录技能内部的关键中间步骤。有了这些日志你才能回答“这个技能到底有没有被用上”“哪些参数最容易填错”“哪些技能超时率最高”。没有数据支撑的优化都是盲人摸象。我在项目里做了一个按技能维度聚合的 dashboard每周看一次调用数和成功率决策要不要淘汰或调整技能就都有依据了。团队协作时还需要注意技能的版本管理。我把每个技能的 schema 和 executor 放在同一个 Git 仓库里采用语义化版本号。技能 ID 不变但 schema 出现不兼容变更时版本号要升大版本同时在 SKILL.md 中写明兼容性说明。这样上层 Agent 框架和各个业务方都有明确的依赖管理方式。如果出现一个旧环境的 Agent 调用了一个新版本技能参数可能对不上那时候就能通过版本号快速定位问题。我给技能加的一个额外能力是“技能自检”也就是技能在被调用前能主动检查自己的前置依赖是否可用。比如邮件技能的自检会检查 SMTP 配置是否完整、数据库技能会检查连接是否能 ping 通。如果自检失败技能能提前返回一个明确的错误码Agent 可以根据错误码判断是否需要跳过这个技能或者询问用户。这种设计极大减少了“技能一直被调用但一直失败”的空转问题。结尾的一点个人体会折腾了这么久的技能体系我自己最深的体会是不要一开始就追求大而全的框架先把两三个技能做成能稳定处理真实任务再慢慢扩。Agent 开发里最磨人的地方往往不是模型本身而是那些看似不起眼但每天都在踩的边界问题——参数少传了一个、描述多了一句容易误导、缓存没刷新、并发把全局变量搞乱了。技能层的价值不在于它有多么炫酷而在于它把这些脏活累活都收拢到一个可管理、可观测、可测试的位置。你搭好之后回头看会觉得这是整个 Agent 项目里最划算的一笔投入。如果你也在做 Agent 开发建议从今天开始把手头的工具函数按这套思路拆一拆先跑通一个技能的完整链路剩下的慢慢补齐就行。
Agent技能体系搭建实战：注册、调度与避坑指南
最近一直在折腾一个叫“agent-skills”的东西说白了就是给 AI Agent 搭一套“技能体系”。如果你玩过 Agent 开发一定遇到过这种尴尬模型本身挺聪明但让它“打开浏览器查资料”“处理一份 Excel”“调一下内部 API”它就一脸懵——因为没人告诉它这些操作要怎么做。技能体系解决的就是这个问题把 Agent 能执行的动作、能调用的工具、能完成的任务规范成一套可注册、可发现、可复用的“技能包”让 Agent 真正做到“召之即来来之能用”。这篇文章想把我这段实践中的经验和教训完整记录一下。内容包括技能层为什么要存在、边界怎么画、注册表和调度逻辑怎么写、参数协议怎么定、踩过哪些坑以及团队协作时怎么维护这套体系。无论你是刚接触 Agent 开发还是已经在做生产级智能体项目应该都能找到点有用的东西。这里不会讲那些虚的概念全是能直接抄走的代码和配置。1. 为什么要给 Agent 搭一套技能体系先说一个很现实的问题Agent 和普通聊天机器人的本质区别在于它会“动手做事”。但模型本身只是个决策器它不会真的去打开文件、发请求、操作数据库。所以我们要给 Agent 装上“手”——这就是技能。我在早期做 Agent 时没这个概念当时的做法很粗暴把所有工具函数一股脑塞进 System Prompt让模型自己根据描述去选。结果越往后越痛苦。工具几十个之后Prompt 又长又乱模型经常选错工具或搞错参数加一个新工具要在代码里改一堆地方不同类型任务想复用另一套工具的代码基本靠复制粘贴。这些问题让我意识到必须有一个中间层把“工具调用”这件事规范化、可插拔化。“agent-skills”这个项目的核心就是想做成这样一套规范。它不关心底层模型是谁也不绑定某个框架而是定义了一种让 Agent 以统一方式发现和调用技能的方式。就像手机上的应用商店——技能包就是一个个 AppAgent 是手机操作系统注册表是应用商店模型通过描述信息去决定装哪个 App 来执行任务。这么做的好处有几个。第一Prompt 瘦身了模型不需要看到所有技能细节只需要看到技能名称和一句描述具体怎么做藏在技能包内部。第二技能可以独立开发和测试任何一个人新增一个技能包不影响其他功能。第三执行逻辑和决策逻辑解耦了模型的“决策”负责选技能技能的“执行”负责做操作两边可以单独优化和排查问题。我记得第一次把这套结构搭建完成时最大的体感是调试变舒服了。以前 Agent 出错得翻完整段对话才能定位是不是工具调用出了问题。现在可以直接看“模型选了哪个技能、参数传了啥、技能返回了啥”相当于给 Agent 加了一层可观测性。这一点对生产环境太重要了。1.1 技能和工具、工作流、插件的边界在哪“技能”这个词很多人会跟工具Tool、工作流Workflow、插件Plugin混在一起说。我自己的理解是工具是最底层的原子能力比如“发送 HTTP 请求”“执行一段 Python 代码”工作流是多个工具的组合编排比如“先查天气再决定要不要带伞”插件是带业务语义的封装集合比如“钉钉插件”包含发消息、建群、审批等一整套接口。技能层夹在中间粒度比工具粗、比工作流细。一个技能通常是对某个“可以做的一件事”的完整封装比如“技能搜索近三天社区内的技术讨论帖”可能内部会调用搜索工具、排序工具、摘要工具但对 Agent 来说它只需要知道“能搜帖子”这一个入口就行。不要让 Agent 去编排底层工具那样既容易出错又慢技能层的作用是帮 Agent 把复杂任务缩成一个可调用的选项。边界问题特别容易犯两个错。一是技能太大一个技能里塞了十几个子操作Agent 按需只调用一部分结果文档描述都写不清到底什么情况该用它。二是技能太碎一个技能只包一层 HTTP 请求跟直接用工具没区别还多绕一层。我后来的判断标准是如果这个技能用一句 30 个字以内的话说不清“什么时候用、能拿到什么结果”那就说明粒度不对要么拆要么合。还有一个经验技能最好是“状态无关”的。同一个技能不要依赖上一次 Executor 里的内部状态每次调用都是一个完整的原子过程。因为 Agent 的调用顺序和上下文是不可控的如果技能内部残留状态第二次调用很可能出诡异的结果。我写过的一个文件合并技能早期就吃了这个亏第一次合并结果会被第二次调用追加进去后来把所有中间状态改成只从参数重新构建问题就没了。1.2 项目的目录结构和命名规范动手写代码之前建议先把目录结构和命名规范定下来。我见过很多项目一开始没在意这个技能多了之后找文件全靠搜索维护成本极高。我当前项目里的目录结构大致是skills/ search_local_docs/ SKILL.md schema.json executor.py requirements.txt assets/ send_email_report/ SKILL.md schema.json executor.py requirements.txt data_analysis/ SKILL.md schema.json executor.py requirements.txt registry.yaml shared/ auth_provider.py network_client.py logging_conf.py每个技能独立成一个目录目录名是技能的唯一 ID命名用 snake_case一眼能看出这个技能是干嘛的。SKILL.md 是给模型看的描述文档schema.json 是给系统看的参数定义executor.py 是真正干活的入口。registry.yaml 是全局注册表用来登记哪些技能对哪些场景可用。这样不管是人还是 Agent都能快速定位一个技能的位置和用途。命名规范这地方多说两句。技能名称不要用太长的一段话最好是“动词_名词”比如 search_local_docs、send_email_report、generate_chartAgent 在选择时更容易理解。避免用项目专属的缩写词比如内部叫 “MCP” 但别人不知道什么意思模型也可能被你绕晕。技能目录里的 SKILL.md 和 schema.json 一定要有这是技能能被 Agent “发现”的关键。没有这两个文件就算 executor 写得再多Agent 也不知道这个技能该怎么用。2. 技能层的核心设计思路设计技能层不是写几个 Python 模块那么简单关键的决策集中在三个点上怎么注册、怎么描述、怎么调度。这三个点直接决定这套体系用起来顺不顺手、维护起来痛不痛苦。先讲注册机制。我采用的是“声明式注册配置文件扫描”的方式。一个新技能要加入系统只需要两步在 skills 目录下新建一个技能文件夹填好 SKILL.md 和 schema.json然后在 registry.yaml 里登记一条记录指定技能 ID、启用的场景标签、权限级别。系统启动时扫描 registry.yaml 加载技能运行时按场景动态把技能暴露给 Agent。这种方式比在代码里硬编码注册要灵活得多新增技能不用改主程序代码改完配置文件重启即可。但配置驱动有一个隐患加载顺序和依赖关系容易出问题。比如技能 A 依赖共享库里的 auth_provider如果技能 A 被单独加载时没有把那个共享模块所在目录加入加载路径import 就直接失败。我在项目里把 shared 目录做成一个动态插入 sys.path 的模块技能 Executor 里所有共享依赖都以绝对包名导入避免相对路径出现问题。这个是第一次部署时踩到的坑当时整整查了两个小时才定位到是路径问题。再讲描述文件。SKILL.md 的作用是“教模型怎么用这个技能”而不是“向程序员解释这个技能怎么实现”。写法和项目文档完全不是一回事。我一般分成几块写一句话说明这是做什么的什么时候应该用这个技能什么时候不應該用必要的前置条件和上下文要求一个简短的调用示例。语言保持简短不要超过 300 字。模型读 Prompt 是有长度限制的技能描述写得越长系统能装下的技能数量就越少。schema.json 则是给系统读的参数定义。定义 Agent 需要传哪些参数、类型是什么、哪些必填、边界值是什么。我会把 description 字段写得非常具体。模型填充参数时依据的是这个 description描述得越细参数填得越准。比如你要一个日期参数不能只写 “date”要写 “支持 YYYY-MM-DD 格式的日期指任务执行当日不要接受历史日期或未来超过 7 天的日期”。模型真的会认真读这些小字所以别嫌麻烦。最后说调度。调度层接收到模型输出的技能调用指令后要做几件事校验技能是否存在、校验参数是否符合 schema、执行权限检查、把参数传给 executor、捕获执行过程中的异常并格式化返回结果。这里最容易被忽略的是“结果反馈格式”。如果 executor 返回的是一整段自由文本模型后续的推理会很难受如果返回的是结构化 JSON比如 {code: 0, data: {...}, message: ...}模型就能精准地拿其中某个字段做下一步操作。我的项目里所有技能都必须返回结构化结果未达标的一律在测试阶段打回。2.1 参数字段设计让模型少犯错的技巧参数字段设计是整个技能层里对“模型调用正确率”影响最大的一环很容易被低估。我之前写过几个技能参数只定义了名称和类型没有写边界条件和说明结果模型的错误率高得离谱——日期格式五花八门、缺了必填项、传了会导致越界的值。后来把描述写细之后正确率直接上了一个台阶。一个完整的参数定义模板大致是这样{ name: query_text, type: string, description: 要搜索的关键词2~50个字符不要包含特殊符号多个关键词用空格分隔, required: true, default: null, allowed_values: null }每个字段都有它存在的意义。description 给模型语义理解required 告诉模型这是不是必填default 提供安全和兜底allowed_values 则是在枚举场景下做硬校验。特别建议在描述里写清楚“不要”做什么模型对否定约束的理解能力比许多人想象的要好。比如“不要传 HTML 标签”“不要传已经被合并的分支名”这类约束显著减少错误调用。枚举类和范围类参数能用 allowed_values 或 min/max 描述就尽量写全。模型有概率生成一个在 schema 上合法但业务上不可用的值。有一回我的“图表生成”技能接受一个颜色参数类型是 string 且必填模型传了一个 “blue-ish”图表库直接报错。后来把可选值规定为 “blue, red, green, yellow, purple, orange” 几种枚举同样场景下错误率就从接近三成降到了接近零。如果技能内部有内部状态或依赖全局配置不要在参数里暴露给模型。比如技能需要“当前用户 ID”通过全局上下文注入不让模型传既避免恶意篡改也减少出错。总之一句话你能给模型设定的边界越清晰模型的表现越稳定。2.2 技能描述怎么写才不会被模型误解技能描述的撰写原则可以总结为“三短一明确”名称短、描述短、示例短但适用条件要明确。很多人的技能描述犯一个通病——强调“能做什么”却不说“什么时候该用”。举例说“数据分析”技能的描述如果只写“该技能可以执行 Pandas 数据分析支持分组、聚合、可视化、统计检验等”模型面对一个简单的求和需求时很可能不调用技能而是自己瞎算或者用了一个复杂度远超需求的技能。我自己的习惯是把描述拆成两句。第一句用最多 30 个字说明“这个技能做什么、产出什么”比如“对上传的 CSV 文件执行分组统计并输出结果表格”。第二句写“适用于什么场景”比如“当用户上传 CSV 并询问平均、合计、分维度统计时使用如果只是简单一两行列表直接用内置计算能力就好”。多写一句触发条件模型选择准确率会有明显提升。还要注意的一点不要把命令式细节写进描述。有些技术博主喜欢在描述里写上“内部调用了 xx 库的 yy 函数”这没有任何帮助反而让模型困惑。对模型而言它要的是“做什么”和“什么时候做”不是“怎么实现”。实现细节应该放在 SKILL.md 最后面的人话备注里仅给维护的人看。示例也非常重要。给一个参数填充的录例模型会照着你的格式来。比如日期参数你示例写 “2025-03-15”模型大概率会输这么多格式而不靠猜。示例要穷尽边界条件要给出正常、空值、异常三种情况下的处理方式。代码里记得处理边界比如空列表、空字符串、空操作。Agent 的指令可能来自用户的随意表达遇到边界情况必须能兜底而不是抛异常。3. 实操一个可落地的技能注册与调度系统讲了这么多原则没有代码始终是空谈。这里把我在 agent-skills 项目里实际用的一套最小可运行系统写出来。它不依赖任何特定框架只用 Python 标准库加一个轻量的 schema 校验。你可以直接把这一套迁到 LangChain、AutoGen 或者自研 Agent 框架里。先看整体流程。系统启动时读取 registry.yaml 得到可用技能列表Agent 的 Prompt 中会注入所有技能的“名称摘要参数字段摘要”模型决策后输出一个结构化的技能调用指令调度器收到指令后执行参数校验、权限校验、调用 executor、标准化返回结果如果执行中出现异常统一抛给上层由 Agent 决定是否重试或返回给用户。这一条链路里的每一步都可以独立测试和替换。我实际用的注册表结构是这样的version: 1.0 default: [search_local_docs, send_email_report] skills: - id: search_local_docs enabled: true scopes: [default, research, office] permissions: [read_local_files] executor: skill_search_local_docs.executor:run max_retries: 2 timeout: 30 - id: send_email_report enabled: true scopes: [default, office] permissions: [send_email] executor: skill_send_email_report.executor:run max_retries: 1 timeout: 15 - id: data_analysis enabled: false scopes: [] permissions: [run_python_code] executor: skill_data_analysis.executor:run max_retries: 0 timeout: 120每个技能后边的字段都不是随便写的。enabled 是总开关false 的技能不会出现在 Agent 视野里。scopes 控制“这个技能在哪些业务场景下可见”避免理财场景的 Agent 误挂一个发邮件技能。permissions 用于执行前的权限校验一个只读任务的技能就不该有任何写操作的权限。max_retries 和 timeout 根据技能实际耗时来决定——发邮件这种操作重试一次就够数据分析可能要 2 分钟不能用一个统一值。核心调度器代码大致如下import importlib import jsonschema import yaml import logging from pathlib import Path class SkillRegistry: def __init__(self, config_pathregistry.yaml): self.config_path Path(config_path) self.skills {} self._load() def _load(self): with open(self.config_path) as f: config yaml.safe_load(f) for item in config[skills]: if not item[enabled]: continue self.skills[item[id]] item logging.info(loaded skills: %s, list(self.skills.keys())) def list_skills_for_scope(self, scope): return [ {id: s[id], description: self._read_description(s[id])} for s in self.skills.values() if scope in s.get(scopes, []) ] def _read_description(self, skill_id): skill_path Path(skills) / skill_id / SKILL.md return skill_path.read_text(encodingutf-8)[:500] class SkillExecutor: def __init__(self, registry): self.registry registry def execute(self, skill_id, params, scope, contextNone): skill self.registry.skills.get(skill_id) if not skill: raise KeyError(fskill {skill_id} not found) if scope not in skill.get(scopes, []): raise PermissionError(fskill {skill_id} not allowed in scope {scope}) self._validate_params(skill_id, params) module_path, func_name skill[executor].split(:) module importlib.import_module(module_path) func getattr(module, func_name) try: raw_result func(params, context or {}) return self._normalize(raw_result, skill_id) except Exception as exc: logging.exception(skill %s execution failed, skill_id) return {code: 500, message: str(exc), data: None} def _validate_params(self, skill_id, params): schema_path Path(skills) / skill_id / schema.json with open(schema_path) as f: schema json.load(f) jsonschema.validate(instanceparams, schemaschema) def _normalize(self, raw, skill_id): if isinstance(raw, dict): return {code: 0, data: raw, message: ok} return {code: 0, data: {result: str(raw)}, message: ok}这段代码看着不复杂但几个细节还是值得琢磨一下。jsonschema.validate 会直接抛异常如果不想让模型看见冗长堆栈可以在调用处统一捕获并转成一条友好的错误消息。importlib 动态导入让每个技能成为独立模块按 skill 的 executor 字段导入即可新增技能无需修改主程序。context 参数用来传入用户身份、全局配置等技能运行需要的上下文技能运行时不能自行去读环境变量或者全局单例否则在并发场景下会互相污染。还有一个容易踩的坑sample 里用了 Path(skills)这个路径是相对当前工作目录的。如果程序从别的目录启动路径就会失效。建议改成根据file计算绝对路径或者把 skills 目录做成一个安装包。第一次部署时我因为在 systemd 里设置了 WorkingDirectory 没注意到导致生产环境加载不到技能还是用绝对路径后稳定了很多。3.1 一个真实技能的例子本地文档搜索为了让你看清“技能包”里每个文件该长什么样我拿项目里的search_local_docs技能做例子拆解一下。这个技能的作用是根据用户输入的关键词在本地某个目录中检索文本文件返回匹配文件的路径和摘要片段。先看 SKILL.md# search_local_docs 核心功能在已授权的本地文档目录中按关键词搜索文本文件返回文件路径、修改时间和匹配片段。 适用场景用户要求查找/搜索/找到某个文档、某段内容且目标范围在本地文档库内。 不适用场景找不到任何本地目录或需求涉及网络公开信息检索。 使用示例用户说帮我查一下关于季度汇报的文档则传入 query季度汇报。这段描述既告诉模型“什么时候用”也告诉模型“什么时候别用”后者的价值有时候更大。模型不会因为描述短就少干活反而因为触发条件清楚了调用的准确率提高不少。schema.json 长这样{ type: object, properties: { query: { type: string, description: 搜索关键词2~50个字符多个词用空格分隔不要包含引号或特殊符号, minLength: 2, maxLength: 50 }, max_results: { type: integer, description: 最多返回结果数默认5不要超过10, minimum: 1, maximum: 10, default: 5 } }, required: [query] }executor.py 内部实现的核心逻辑就是遍历目录、读文件内容、做一次简单的关键词匹配、按匹配次数排序返回def run(params, context): query params[query].strip() keywords [k.lower() for k in query.split()] doc_dir context.get(doc_dir, docs) max_results params.get(max_results, 5) matches [] for p in Path(doc_dir).rglob(*.md): content p.read_text(encodingutf-8, errorsignore) lower_content content.lower() if all(k in lower_content for k in keywords): snippet _make_snippet(content, keywords[0]) matches.append({ path: str(p), modified: p.stat().st_mtime, snippet: snippet, }) matches.sort(keylambda x: x[modified], reverseTrue) return {matches: matches[:max_results]}这里有一点很关键executor 不应该承载任何业务策略它就是个执行器。要不要对结果排序、按什么排序虽然也是代码逻辑但我更愿意把这种“偏好”放在技能内部的代码里而不是让 Agent 传参。因为模型的判断不稳定同一个排序需求在不同对话里可能生成不同的传参方式给出带默认值的参数是最稳妥的。3.2 测试框架每个技能都能独立验证技能一旦多了手动测根本测不过来。我后来给每个技能配了一个独立的测试脚本放在技能目录下的tests/里用 pytest 统一跑。测试要覆盖几个维度正常输入是否符合预期缺参、错参、超范围参数是否能正确拦截技能在模拟的异常环境中是否能返回结构化错误而不是裸异常参数校验不通过时错误信息是否能在不泄漏堆栈的前提下让上层 Agent 看懂。一个典型测试用例大致长这样def test_search_local_docs_normal(): ctx {doc_dir: tests/fixtures/docs} result run({query: 季度汇报, max_results: 3}, ctx) assert result[code] 0 assert len(result[data][matches]) 1 def test_search_local_docs_bad_param(): ctx {doc_dir: tests/fixtures/docs} try: run({query: x}, ctx) except Exception: return raise AssertionError(should not reach here)一套完整健全的技能测试会让你后续迭代模型时放心很多。我每次换一个底层模型都会把所有技能测试跑一遍看调用成功率、参数正确率有没有变化。这比在对话里一个一个试要快得多。如果你现在还没有任何回归测试我建议立刻从最重要的两个技能开始建这个投资非常值。4. 常见问题与排查技巧实录实操过程中一定会碰上各种奇奇怪怪的问题。这里挑几个在 agent-skills 项目里出现过的典型问题记录一下排查思路和解决方案。这些问题普遍性很强你大概率也会遇到。4.1 模型总是选错技能怎么办最典型的场景有两三个技能功能很接近比如“搜索本地文档”和“总结本地文档”模型面对“帮我整理一下这个目录下的季度总结”这种问题经常选了搜索而不是总结。排查下来根本原因通常出在“技能描述不够有区分度”上。两个相近技能的描述如果都能覆盖同一个用户意图模型分不清是很正常的。解决办法是给每个技能写一个“排他性描述场景”搜索技能写明“只负责找到文档的具体位置和片段不生成总结内容”总结技能写明“接收一组明确列出的文档路径对内容进行归纳不负责查找文件”。描述之间要有互补性而不能是重叠性。另一种情况是技能本身使用门槛太高导致模型回避。比如技能需要三个参数而用户只提供了一半信息模型发现参数不足可能就放弃了。这时候应该在技能内部支持可选参数和默认值让模型即使参数提供不全也能安全执行或者在描述里明确写“缺少参数时会使用默认值无需向用户确认”。把模型调用技能的心理负担降到最低准确率自然会上去。4.2 技能执行成功但结果不符合预期这种问题真的很磨人。技能没有报错code 返回 0但拿到结果一看根本不是用户想要的。定位这种问题得把“模型决策”和“技能执行”两头拆开来看。我习惯的做法有三个第一详细记录模型实际传入的参数很多时候是参数在边界处被模型填了一个语义相近但完全不同的值比如把”项目负责人“填成了“邀请函”这个看日志立刻就能发现。第二打印技能返回的中间过程。如果技能的第一次输出和最终结果不一样那说明是后续处理步骤出了问题。这里建议在技能内部逐步记录中间结果而不是只记录最终返回值。像是做数据分析的技能我会把“接收到的数据形状”“清洗后的结果”“聚合后的结果”分别打印出来问题出现在哪一步就一清二楚了。第三要重视”将用户问题的原始表述与参数实际值做对比“。有时候模型在参数里擅自做了改写比如用户说“最近一个月”模型把参数填成了“last_7_days”这种问题不是报错级别的问题但结果是错的。针对这种情况我会在 schema 的 description 里强调“必须原样使用用户的时间描述不要自行换算”这比在代码里做一堆日期转换要有效得多因为模型才是理解歧义的关键节点。4.3 并发和多租户场景下的状态串扰这个问题可能比较进阶但如果你开发的 Agent 要服务多个用户或跑在服务端上几乎必然遇到。典型症状是用户 A 触发了“发送周报”技能结果收到邮件的却是用户 B。根因是技能内部把“当前用户”作为全局变量存储了两个请求并发执行时互相覆盖。解决这个问题强制要求所有技能的状态都从 params 和 context 参数里面读不依赖任何全局可写变量。context 中每个用户的上下文是独立的是由上层 Agent 框架负责注入的。规则虽然很简单但在实际落地时总有技能不小心用了模块级变量或缓存对象。我在代码评审时会专门盯这一点。另一个办法是给技能实例化加上用户级的隔离每个用户持有一个独立的技能执行器实例但那样成本偏高还是尽量从代码规范上解决。4.4 技能数量太多导致 Prompt 超长或选择困难技能从几个涨到几十个之后即使每个技能描述压缩到 200 字光技能列表就占了 5000 字以上的 Prompt 空间。模型面对二三十个选项时选择准确率也会下降。这里的解法是两层。第一层按场景分组Agent 每次对话只加载与当前场景相关的技能子集比如“写作场景”就只挂文案技能“办公场景”只挂文档和邮件技能。上一节说的 scopes 字段就是这个用途。第二层技能描述再做一次摘要处理。给模型看的描述可以压缩到 30 个字以内只保留触发条件完整描述放在开发者后台供人工查看。模型对简洁的条目反而更敏感。我曾经在 20 个技能的配置下测试过完整描述版的选择准确率反而低于摘要版因为模型分配给每个技能的注意力更少干扰项更多。所以为模型做减法对效果提升是很明显的。4.5 技能执行超时和卡死有些技能偶尔会出现运行时间超出预期甚至完全卡死的情况。比如搜索本地目录时遇到一个巨大的文件、数据分析技能读了一个几十 MB 的 CSV都会让整个 Agent 回复变慢。超时控制在注册表里有配置字段但真正重要的是技能 executor 内部要主动配合。避免一次性读取超大文件进内存文件行数多时建议设置行数上限网络请求要设置显式的超时时间不要依赖系统默认值数据分析类的技能对数据集做个行数/列数检查超限时立刻返回友好错误而不是硬跑。还有一个容易被忽略的点技能内部不应该有无界循环。比如“重试直到成功”这种逻辑要设置最大重试次数。一种更隐蔽的情况是技能内启动了一个后台线程但主线程返回了导致看起来执行完成但实际上后台还在占资源。我的要求是技能执行结束后必须保证没有挂在后台的未完成任务。在测试环境里我会用 eventlet 或 gevent 的 monkey patch 配合超时断言强制暴露这类问题。5. 维护成本与性能优化技能体系建立起来之后的维护才是真正考验工程能力的地方。代码层面的维护相对好做最难的是“技能功能跟实际业务需求之间的匹配”。经常出现的情况是模型升级了以前不擅长的事现在能直接做了原来为了弥补模型能力而写的技能就变得多余或者业务逻辑变了技能内部的数据源、权限模型、输出格式全都要跟着改。我会定期做“技能清理”和“技能合并”的复盘把调用量低的、描述与新模型能力冲突的技能下线这个动作对整体性能的提升很明显。性能优化里最值得投入的一项是技能加载的缓存机制。技能加载时大部分开销在读取 SKILL.md 和 schema.json、编译 Python 模块、初始化网络连接。如果每次运行都重新来一遍耗时感人。我会做一个带时间戳和文件哈希的缓存文件没变化就直接用缓存的加载结果实测能节省 30% 以上的冷启动时间。但一定要注意缓存的失效问题技能代码内容变了但缓存还在就会加载到旧代码。最简单有效的方式是在加载时计算文件的 mtime 做比对代价小且绝对可靠。网络连接相关的技能也要做连接复用。比如发邮件、调 API 的技能如果每次都新建立连接TCP 握手和 TLS 握手都要浪费几百毫秒。维护一个全局连接池技能运行时从连接池里取连接用完还回去这是比较常见的优化手段。还要注意技能如果超时了要把连接标记为失效并销毁否则拿一个坏连接去重试只会持续失败。我上一版邮件技能就吃过一个坏连接一直重试的亏后来加了健康检查才稳定下来。日志和可观测性也是维护时很容易忽略、但恰恰是最重要的部分。每个技能的调用都应该记录模型选择的技能 ID、实际的入参、执行耗时、返回码、错误信息必要时要记录技能内部的关键中间步骤。有了这些日志你才能回答“这个技能到底有没有被用上”“哪些参数最容易填错”“哪些技能超时率最高”。没有数据支撑的优化都是盲人摸象。我在项目里做了一个按技能维度聚合的 dashboard每周看一次调用数和成功率决策要不要淘汰或调整技能就都有依据了。团队协作时还需要注意技能的版本管理。我把每个技能的 schema 和 executor 放在同一个 Git 仓库里采用语义化版本号。技能 ID 不变但 schema 出现不兼容变更时版本号要升大版本同时在 SKILL.md 中写明兼容性说明。这样上层 Agent 框架和各个业务方都有明确的依赖管理方式。如果出现一个旧环境的 Agent 调用了一个新版本技能参数可能对不上那时候就能通过版本号快速定位问题。我给技能加的一个额外能力是“技能自检”也就是技能在被调用前能主动检查自己的前置依赖是否可用。比如邮件技能的自检会检查 SMTP 配置是否完整、数据库技能会检查连接是否能 ping 通。如果自检失败技能能提前返回一个明确的错误码Agent 可以根据错误码判断是否需要跳过这个技能或者询问用户。这种设计极大减少了“技能一直被调用但一直失败”的空转问题。结尾的一点个人体会折腾了这么久的技能体系我自己最深的体会是不要一开始就追求大而全的框架先把两三个技能做成能稳定处理真实任务再慢慢扩。Agent 开发里最磨人的地方往往不是模型本身而是那些看似不起眼但每天都在踩的边界问题——参数少传了一个、描述多了一句容易误导、缓存没刷新、并发把全局变量搞乱了。技能层的价值不在于它有多么炫酷而在于它把这些脏活累活都收拢到一个可管理、可观测、可测试的位置。你搭好之后回头看会觉得这是整个 Agent 项目里最划算的一笔投入。如果你也在做 Agent 开发建议从今天开始把手头的工具函数按这套思路拆一拆先跑通一个技能的完整链路剩下的慢慢补齐就行。