AI代理营销技能库搭建实战：从技能定义到评测闭环

最近半年我一直在做营销场景的AI代理项目，最头疼的从来不是大模型本身跑得好不好，而是怎么让模型稳定、可控地调用各种营销能力。今天想通过梳理 Marketingskills 这个项目，聊聊我搭建AI代理营销技能库时的完整思路。这个项目解决的核心问题很直接：营销团队有大量分析、内容生成、投放优化、用户分群的需求，但这些能力分散在不同系统里，模型要么不知道怎么用，要么用起来全靠运气。技能库做的事情，就是把营销能力组织成一套标准化的、可注册、可调用、可评测的模块，让AI代理真正听得懂、调得动、还调得准。这篇文章适合两类人：一类是正在做AI代理落地的工程师，另一类是负责营销自动化或数字化转型的产品经理，看完整套技术路径，基本能判断自己的项目适合同样的做法。

1. 技能库的整体设计思路

1.1 为什么AI代理需要"技能库"而不是一堆Prompt

我在项目前期走过一段弯路，当时团队的想法很简单：把各种营销分析需求写成Prompt模板，塞给模型，让它"自由发挥"。结果很惨烈。同样一个"帮我分析上周各渠道的广告效果"的问题，模型今天会自己编一个ROI算式，明天又会把口径完全搞错，后天干脆拒绝回答。问题出在哪？出在模型只能靠"语义理解"猜测你的意图，但它不知道你的数据表结构、不知道你的定义口径、更不知道该调用哪个内部接口。

后来我换了个角度看这件事：大模型就像一个刚入职的高智商实习生，它不缺理解力，缺的是岗位说明书和工具手册。你说"分析一下投放数据"，它想问：去哪拉数据？什么叫分析？口径是什么？输出什么格式？当你给它一套标准化的"技能库"，每个技能都明确写清楚"这个技能能干什么、需要什么参数、会返回什么结构、遇到什么情况不适用"，它就能像一个干练的助理一样，先选工具，再执行任务，不再自由发挥。

这背后的核心逻辑是：把模型"会思考"的优势，和程序"确定性执行"的优势结合起来。模型负责意图识别和表达组织，技能库里的每个技能负责确定性的数据和动作。两者一组合，既有灵活性，又有可控性。这才是AI代理能落地的关键，也是我在做 Marketingskills 这个项目时最重要的一个认知转变。

提示：技能库本质上不是"模型追加的知识"，而是一层介于大模型和业务系统之间的"能力编排层"。它的好坏，决定你的代理是专业助理还是花哨玩具。

1.2 技能库的四个核心模块

在设计技能库时，我没有一开始就写代码，而是先梳理了它必须包含的四个核心模块，缺一个都会在后面的迭代里踩坑。

第一个是技能描述描述文件，用自然语言和结构化字段说明技能的用途、适用场景、参数约束和输出格式。它解决的是"模型什么时候该选这个技能"的问题，这一层会直接影响意图路由的准确率。

第二个是参数Schema，定义每个技能的输入输出结构。比如一个"广告账户日报"技能，入参需要账户ID、日期范围、数据维度，出参需要曝光、点击、花费、转化数、成本等字段。参数Schema的主要作用是让大模型知道该怎么"格式化"地向技能传递数据，避免出现"模型传了个字符串、接口却要数组"这种鸡同鸭讲的状况。

第三个是执行函数，也就是技能真正触达业务系统的逻辑。它可以是内部接口的封装、SQL查询的模板、投放平台的操作脚本，甚至可以是另一个模型的调用。执行函数必须幂等、可重试、有超时处理，因为AI代理发起的调用频率和人为操作完全不同，系统崩溃和重复提交的概率会高很多。

第四个是评测用例，这是很多人容易忽略但又最重要的部分。每个技能都要配一组可执行、可断言、可回归验证的测试数据。比如"渠道ROI对比"技能，就要准备一组已知答案的历史数据，用来验证每次改动后，技能输出是否依旧正确。

这四个模块合在一起，就构成了一个完整的技能节点。单个技能节点好写，难的是把它们组织成一套能让产品快速扩展的体系。后面的章节我会展开讲技术细节。

2. 技能定义标准与营销场景拆解

2.1 用"接口文档"的思路定义技能

我是做后端出身，所以从一开始我就用"接口文档"的思维来定义技能。每个技能的本质，就是一份同时写给人和机器看的说明：人读了知道这个技能做了什么，模型读了知道该在什么场景下调用它。

这里我分享一个实测效果很好的技能描述模板，类似YAML结构：

skill: name: campaign_roi_analyzer description: 计算各渠道广告投放的ROI，支持按时间范围和转化口径进行筛选。 trigger: 当用户提到"广告效果""ROI""投产比""渠道表现"等关键词时优先考虑该技能。 avoid: 当用户只询问营销活动的创意内容或文案建议时，不要使用该技能。 category: data_analysis version: 1.2.0 input: - name: date_range type: string required: true description: 日期范围，格式为 YYYY-MM-DD~YYYY-MM-DD，最多支持90天。 - name: channels type: array required: false description: 渠道列表，允许的枚举值包括 natural_search、paid_social、paid_search、email。 - name: conversion_metric type: string required: false default: roi description: 转化口径，支持 roi / cpa / ctr 三种枚举。 output: type: array fields: - name: channel type: string - name: spend type: number - name: revenue type: number - name: roi type: number notes: 数据来自数据仓库，每天凌晨2点更新，查询当天数据可能不完整。

你可能注意到我特意写了trigger和avoid两块，这是我在实践中总结出来的重点。只写一段笼统的 description，模型经常误判。比如一个同时掌握了"内容创作"和"数据分析"技能的代理，用户问"帮我看看上个月哪条文案转化最好"，它可能用内容创作技能生成一段新文案，而不是用数据分析技能去查历史转化数据。加了触发词和排除条件后，命中率会明显提升。我自己的经验是，加了这两个字段之后，技能选择的准确率能提升至少十个百分点。

写技能描述本身不是纯粹的技术活，它需要大量业务语感。最好的写法是：想象一个新人运营入职，你用一句话告诉他"什么情况下用这个工具，什么情况下千万别用"，这句话就是技能描述的核心。

2.2 营销技能的分类粒度

营销领域的技能库如果不做分类，很容易变成一个大杂烩。我在 Marketingskills 项目里，把技能按业务逻辑分成了五个大类，这个分类现在已经沉淀成了一块比较稳定的能力地图，分享给大家参考：

分类的意义不仅仅是文档好看，它决定了两件事。第一，技能库的检索范围可以按类别缩小，模型对几十个技能的误选率远高于对五六个技能的误选率；第二，评测和权限控制可以分类进行，比如"分析类技能开放给全员，投放优化类技能只开放给投放总监"，这样既能保护业务安全，也能让代理的权限粒度更细。

关于粒度，我想多说一句。很多团队做技能库容易走极端，要么一个技能管一大堆事，要么一个技能只做一个小函数。我的建议是"可交付、可维护、可复用"三个标准：一个技能必须能独立完成一个完整的业务动作，而不是一个碎片函数；同时它的实现逻辑要能被一个不熟悉代码的运营看懂；最后它得能被多个场景复用。满足这三点，粒度基本就是合适的。

2.3 技能的版本管理与数据组织

技能库的目录结构看起来是小事，做不好却会直接拖垮团队协作。我在初期曾把几十个技能文件全部扔在一个目录里，叫skills/，结果两周之后谁都不敢改文件，因为改动一个可能导致其他依赖它的技能一起出问题。后来我彻底重构了目录结构，按"类别/技能名/版本"来组织：

skills/ content/ ad_copy_generator/ 1.0.0/ skill.yaml impl.py tests.yaml 1.1.0/ skill.yaml impl.py tests.yaml landing_page_writer/ 1.0.0/ skill.yaml impl.py tests.yaml data_analysis/ campaign_roi_analyzer/ 1.0.0/ skill.yaml impl.py tests.yaml

为什么要把版本目录做得这么重？因为AI代理的迭代速度和传统软件开发完全不同。今天你改了一个技能的描述，明天所有依赖它的流程都可能发生变化。如果没有版本化，出了问题根本没法回滚。我现在的习惯是：任何一个技能只要被线上流程引用，它的当前版本就不可变，任何修改必须开启一个新版本，并且新版本必须通过全部评测用例之后才能切换。听起来繁琐，但这是保证线上代理行为稳定的基础。

除了目录，我还会在每个技能目录里维护一个CHANGELOG.md，记录每次版本的改动原因、变更内容和影响范围。这也有一个实用目的：后续模型评测如果发现某个行为发生了漂移，我可以快速定位是哪个技能的哪次改动引起的。

3. 工程实现：从技能注册到模型路由

3.1 技能注册与大模型函数调用

技能定义好了，接下来就是让模型"看见"这些技能。这一步我采用的做法是把技能库的Schema暴露给大模型的函数调用机制。

具体拆分下来有三步：

1. 启动时扫描技能目录，读取所有skill.yaml，解析出技能名称、描述、参数Schema；
2. 把解析结果转换成模型平台要求的函数定义格式；
3. 把函数定义随每次请求发给模型，模型根据用户问题决定是否发起调用以及传入什么参数。

这里有个细节值得注意：技能的参数定义不要直接复制接口原始参数，而是要在中间加一层"面向问题的参数翻译层"，然后在这个逻辑层里处理从自然语言到业务参数的各种细节处理，把"用户说上周"翻译成具体的日期，根据默认值补齐缺失参数，这类工作都应该在这一层完成。换句话说，模型的函数调用结果不是直接对接API，而是先进到一个参数解析和执行调度器里。

我贴一段简化版的注册核心逻辑做个示意：

import yaml from pathlib import Path def load_skills(skills_dir: str) -> list[dict]: schemas = [] for skill_file in Path(skills_dir).rglob("skill.yaml"): with open(skill_file, "r", encoding="utf-8") as f: skill = yaml.safe_load(f) schema = { "name": skill["skill"]["name"], "description": build_description(skill["skill"]), "parameters": build_parameters_schema(skill["skill"]["input"]), } schemas.append(schema) return schemas

每次请求把几十个函数全部塞给模型，评测下来效果不错，因为技能schema本身包含的token量不大，决策效率高，适合快速响应场景。同时我也加入了按分类分组加载的能力，比如"数据类对话"只加载数据分析和用户分析两类技能，这样更稳也更省。

3.2 技能执行链路的容错设计

模型把参数传回来，不等于任务就完成了。真正执行时，链路中的不确定性非常高。我在技能执行器里重点设计了下面几个环节。

第一步是参数严格校验，也就是先启动一次严格的schema校验，用校验函数检查必填字段是否完整、枚举值是否合法、日期格式是否正确。校验失败时，不是直接报错，而是返回一个"参数缺失清单"，再把清单抛回给模型让它补参数。我之前试过让模型直接执行错误请求，体验极其糟糕，用户看到的就是一堆晦涩的报错。

第二步是执行策略，包括超时控制、重试机制、幂等控制。内部接口调用设3秒超时，重试一次，超过就降级；外部投放平台调用设10秒超时，配合接口登录状态检测，因为外呼的稳定性和内网完全不同。重试必须考虑幂等性，比如"创建订单"这种操作不能因为网络抖动就重复提交。

第三步是结果回填，目前我采用的是一种轻量方案：先由执行函数产出结构化结果，再由模型基于结果做进一步整理和自然语言表达。这里大家可以注意一下，建议不要让模型直接操作原始数据表，而是把已经算好的指标格式化好再交给模型包装措辞，能大幅减少生成内容出错的风险。

def execute_skill(skill_name: str, params: dict) -> SkillResult: validator = get_validator(skill_name) errors = validator.validate(params) if errors: return SkillResult(status="param_error", error_payload=errors) skill_fn = get_impl(skill_name) try: raw = skill_fn(params) return SkillResult(status="ok", data=raw) except SkillTimeoutError: return SkillResult(status="timeout", message="技能执行超时，请稍后重试") except SkillApiError as e: return SkillResult(status="upstream_error", message=e.message)

这个封装的价值在于：模型不再直接面对各种异常，而是收到结构化的状态码和提示语。这样不仅出错时用户看到的反馈是友好的，代码调试时也能清晰归因。

3.3 评测闭环：让技能库可持续迭代

如果说技能注册和执行构建了代理的"骨架"，评测闭环则是注入的"血液"，没有它，技能库会不断腐化。我在项目里建设了两层评测机制。

第一层是离线回归集。每个技能都要配20-30条典型测试用例，覆盖主路径、边界路径和反例。拿"渠道ROI对比"技能来说，主路径是一组标准查询期望返回指定表格，边界路径是"查询天数超过90天"应返回截断提示，反例是"用户问情感文案"应判定不触发该技能。每次技能改动，我都要全量跑一遍回归集，任何一条用例挂了就必须修复后才能上架。

第二层是在线行为指标。我设计了一个很简单的日志系统，记录每次模型调用的完整链路：用户问题、模型选技能的结果、参数解析结果、执行状态、用户是否追问。每周我会把"模型选错技能率""参数解析失败率""执行超时率"三个指标拉出来比一比。这个方法很土但很管用，能直观反映模型和技能库的健康度。

这里我也想强调一下：技能评测不要只看"答案对不对"，还要看"路径稳不稳"。同一个问题，今天走技能A，明天走技能B，哪怕结果一样，也是不稳定。对AI代理来说，确定性有时候比创造性更重要，因为业务方要的是一个可预期的系统。

4. 踩坑实录与排查方法

4.1 模型经常选错技能，怎么排查

这类问题在技能库上线初期的频率非常高。我处理"模型选错技能"问题的路径通常是：翻日志，看用户原话、模型选中的技能名称、模型给出的理由，把错误case归类，是描述不清晰、字段缺失、还是相似技能太多导致的混淆。

如果是描述不清晰，就按前面说的trigger和avoid语法重写描述。如果是字段缺失，比如用户说"看一下最近的数据"但没有指明技能必须的转化目标，那我就把旧的必填参数改成带默认值，让模型不必追问也能完成执行。如果是相似技能太多，比如同时存在"广告文案生成"和"邮件文案生成"，它们描述高度重叠，我一般选择合并成一个技能，用参数区分场景，反而效果更好。

还有一种坑很多人想不到：模型的系统提示词里如果写了太多关于"你是营销专家"之类的身份设定，它会倾向于自由发挥而不是调用工具。我的经验是，系统提示词越精简越好，只保留必要的角色边界和输出风格，把一切业务能力交给技能库去承载。

4.2 参数传递老是出错

模型传参数出错的症状很多，比如把paid_social写成paid-social，日期格式写成2024.05.01而不是2024-05-01，字符串串传给数组字段等。我和团队做过一次统计，参数类错误占技能执行失败原因的六成以上。

解决问题的一个有效做法是在参数Schema中提供枚举值列表时加上"也包括xxx的说法"这类对语义的补充说明，同时把每个参数的合理格式写更绝对一点，比如"只使用标准ISO格式，不接受点号分隔"。说实话，模型还是经常漏看，因此必须做一层宽松解析兜底，例如日期解析函数里多支持几种分隔符，渠道枚举词做一次别名映射，把"百度""巨量""广告"映射到标准channel ID。工程上做兜底，不一定非要模型完全遵守格式，实用为主。

4.3 技能执行结果与业务期望不符

还有一种情况，参数调用完全成功，没有报错，但输出的结论业务方完全不认同。这种问题不是模型的原因，而是技能本身的分析口径或数据链路配置有问题。

我遇到过一个典型case：渠道ROI分析技能返回结果偶尔跟业务方自己导出的报表不一致。查了几个小时后发现，数据仓库的表有一个分区延迟，技能读的是当天分区，业务方报表读的是前一天分区，两边基数不同自然对不上。后来我在技能说明里明确标注了数据更新时间，并且给技能加了一个data_freshness字段，由执行函数强制校验，超过延迟阈值就在结果里提示"数据截至XX时间，可能不完整"。这样至少不会让业务方拿着过期数据做决策。

这个案例给我的启发是：一个技能的好坏，不只看执行是否正确，还要看它在数据链路异常时是否"诚实"。宁可让代理说"数据暂未更新"，也不要让它拿着半成品数据硬算出一个自信满满的结论。

4.4 性能与成本如何平衡

技能库数量成长之后，性能问题会慢慢浮现。我带项目时技能总数从十几个涨到五十多个，每次请求都要把所有技能的Schema发给模型，token开销变大，响应变慢，单次成本也随之上涨。

我做了三个维度的优化。第一，按对话场景做技能预分组，把技能打上"sales_bot""analysis_bot""content_bot"等场景标签，启动不同bot时只加载对应的子集；二是为高频查询做结果缓存，比如"本周各渠道消耗汇总"这类重计算且数据变化不频繁的技能，按照缓存key匹配并在十分钟内直接命中缓存；三是把大段技能描述里相同的内容（比如通用的时间格式说明、公共枚举值定义）抽出来作为公共字段复用，减少每个技能重复复制导致的token膨胀。

降本增效的核心其实是"不让模型做重复的苦力"。凡是能用缓存、规则和预计算解决的计算，都不要浪费模型的窗口长度和调用次数，模型只负责它真正擅长的语义调度和表达。

5. 扩展方向与实践心得

5.1 从"单技能调用"走向"技能编排"

技能库稳定运行一段时间后，我明显感觉到下一个瓶颈不是单个技能的鲁棒性，而是多技能的协同编排。比如用户问"这个季度预算有限，建议怎么分配到各渠道"，只靠单个技能对象跑不出来的，需要先调"预算结构分析"技能算出现状，再调"渠道效率对比"技能找到高效渠道，最后可能还要调"历史活动复盘"技能寻找可复用经验。

我在 Marketingskills 项目的后期已经尝试把这些复合任务流程沉淀成"流程模板"，每个模板定义一个技能调用序列和执行条件。这样用户只需要表达一次目标，代理就能按照预设的最佳路径逐步执行，而不是每次都从零推理。这一步跨过去后，整个项目的价值会从"一个高效助理"跃升为"一套可复用的营销自动化工作流引擎"。

5.2 技能库的生态共建比孤岛建设重要

最后说一点组织层面的体会。技能库如果只是工程团队自嗨，价值有限。我做过一个尝试：邀请业务团队的核心运营和投放同学一起参与技能描述评审，请他们给每个技能写出他们认为的最典型的触发场景和最容易被误用的情况。结果他们写出的trigger单词比我们工程师写的精准得多。从那以后，我基本固化了一个流程：新技能上线前要做一次"业务侧操作性问答"，至少找两位一线使用者确认描述，再进评测。

这种做法本质上是在"行为层面"对齐预期，效果远远好于让业务只看一份技术文档。如果你也是刚开始搭技能库，这个建议能帮你省掉大量后期的纠错成本。

关于这个项目，我个人最大的体会是：搭建技能库最大的难点，不在于写多少行代码，也不在于调优某个模型，而在于你是否能持续维护一套"人和模型都能理解的业务共识"。它既像一份严谨的接口契约，又像一本不断更新的营销操作手册。只要这套共识在，任何模型平台、任何营销系统，都可以被平滑地接入你的代理体系。希望我踩过的这些坑和沉淀下来的方法，能帮你少走一些弯路。