Agent Skills实战：从Prompt封装到生产级工具的关键设计

最近圈子里到处在聊 agent-skills很多人以为它只是把 prompt 封装一下、变成可复用的函数这么简单。但实际上一套设计良好的 skills 体系能直接把一个“偶尔能用”的 demo 变成“稳定交付”的生产级工具。这篇文章我就从实战角度聊聊skills 到底解决什么问题、底层机制长什么样、怎么从零手写一个属于你自己的 skill以及我在实现和调优过程中踩过哪些坑。1. 为什么说 Skills 是 Agent 从“玩具”走向“工具”的关键一步先讲一个我反复遇到的场景。几个月前我拿一个大模型 API 做了一个内部问答机器人刚开始的效果很惊艳能回答问题、能总结文档、能写周报。但用了一周之后大家开始反馈“这东西时灵时不灵”——同一个问题换个说法答案质量就断崖式下跌。问题就出在我把所有能力都塞在一个巨大的 prompt 里没有对模型的行为做任何结构性约束。这时候我才意识到单纯堆 prompt 是一件非常脆弱的事。你把“会用计算器”“会查数据库”“会做格式转换”这几种能力混在一个上下文里模型的注意力会被分散输出质量也会随之波动。因为你实际上是在要求一个概率模型同时记住并执行很多条隐式的规则它不可能每次都精准命中所有要求。Skills 的思路完全不同它把每种能力拆成独立的模块每个模块只负责一件事并且有明确的输入、输出和执行逻辑。模型不再需要“猜”你要干什么而是通过意图识别快速匹配到对应的 skill然后按预设的路径去执行。这就像你不再让一个厨师同时管切菜、炒菜、摆盘而是给后厨配了三个岗位各管一段出菜自然又快又稳。是 prompt 不值钱了吗当然不是。prompt 仍然重要但它的角色变了——从“全能说明书”变成了“调度中枢”。它只需要负责理解用户的意图、决定该调用哪个 skill并且把执行结果组装成用户能看懂的语言。真正的脏活累活交给了每个 skill 内部去处理。所以我给“是否应该把能力升级成 skill”定义了一个判断标准当一个任务需要三步以上的固定操作或者同一个逻辑需要被多个场景复用或者这个逻辑涉及外部工具调用时你就该考虑把它抽成 skill 了。别等 prompt 写到五千字、每次改动都像拆地雷的时候才动手。2. 拆解 Skill 的底层骨架意图识别、参数契约与执行策略在我接触过的各种 agent 框架里无论它叫 tool、skill、action 还是 capability底层结构其实都有共通之处。搞清楚了这三个核心组件你就不容易被任何框架绑架甚至可以自己手写一套轻量的实现。2.1 意图识别让 Skill 知道什么时候该被触发意图识别是 skill 体系里最容易忽视、也最影响体验的一环。你不是把所有 skill 的描述一股脑塞给模型就完事了而是要提供一个清晰的“触发条件列表”。我在实际项目里会为每个 skill 维护一份带权重的关键词和语义描述。比如一个“天气查询”的 skill触发词可能包括“天气”“气温”“会不会下雨”“要不要带伞”而语义描述则写明“用于查询某地某时的天气状况”。更进阶一点的做法是加一层“排除逻辑”。我遇到过可怕的误触发用户说“我想查一下明天的会议安排”结果 agent 调用了天气查询。原因就是“明天”这个词在意图识别里的权重太高。后来我在 skill 定义里显式加了“不处理时间安排类请求”的负向描述效果好非常多。在意图模块里正例和反例同样重要。2.2 参数契约给大模型的“函数签名”意图识别告诉你“该用哪个 skill”参数契约则告诉你“这个 skill 需要哪些信息才能跑起来”。这一步非常像写函数的签名——定义参数名、类型、是否必填、以及每个参数的解释。举个例子一个发邮件的 skill参数至少包括收件人、主题、正文可能还有抄送和附件。如果收件人是必填的而模型没提取出来你不能直接让它硬跑而是应该返回一个“缺参提示”引导用户补充信息。我在实现里常用 JSON Schema 来做这层约束这样既能校验参数完整性又能让大模型按照固定格式返回提取结果。这里有一条关键经验参数描述一定要写清楚“从用户原话里怎么找到这个值”。模型不是真正理解“日期”这个抽象概念你说“会议时间”它可能提取成“明天上午”但你的业务系统需要的是“2025-06-15 09:00”。所以你最好在参数描述里给出转换规则比如“必须将相对时间转换为绝对时间格式为 YYYY-MM-DD HH:mm”。很多参数提取失败不是模型太笨而是你没告诉它该怎么转换。2.3 执行策略LLM 调度、确定性代码与混合编排拿到参数之后skill 内部怎么执行我在实践中总结出三种模式分别适用不同场景。第一种是纯代码执行也叫确定性执行。比如写一个“计算两个日期之间相差多少天”的 skill完全没有必要让模型来算日期直接用 Python 的 datetime 库处理就行。这类 skill 输出的结果是 100% 可预期的可以放心大胆地用。第二种是纯模型执行比如“总结一篇长文的核心观点”。这种任务没有标准答案必须依靠模型的语义理解能力。这时候 skill 内部其实就是一段优化过的独立 prompt只专注于做好总结这一件事不受其他上下文干扰。第三种是混合编排也是实践中最常见、最能体现工程难度的模式。比如一个“舆情分析”的 skill可能要先去搜索引擎抓数据、再调用模型做情感分类、最后用代码把结果聚合渲染成报告。这种链路里我一般用代码控制主流程在需要语义理解和判断的节点才调用 LLM最大化确定性的比例。这三种策略没有哪个更好关键在于你对自己的任务的确定性要求有多高。我的习惯是能确定的部分绝不让模型碰需要发散理解的部分才交给模型。这会让你的 skill 整体非常可靠而不是在某些 case 上惊艳、某些 case 上翻车。3. 手把手搭建一个 Skill从需求拆解到注册调用理论说再多不如动手做一个。接下来我以“生成规范化 Git 提交信息”为例完整走一遍 skill 的设计与实现。选这个例子是因为它足够小、足够常见但又完美涵盖了意图识别、参数提取、模型调度和确定性校验这几个核心环节。3.1 需求拆解明确输入、输出与边界任务的输入是用户的一段话比如“我改了登录页面的 bug还优化了数据库查询性能分别是两个 commit”。输出则是一段可执行的 git commit 命令或直接生成符合 Conventional Commits 规范的提交信息。在动手写代码之前先划清边界。这个 skill 只负责“分析 diff 或描述并生成规范的提交信息”它不负责替你执行 git 命令避免权限风险也不负责理解你把代码改成了什么样——如果你不给 diff 内容它就只能基于你的描述来生成。边界划得越清楚后面做意图识别和参数设计就越轻松模型的发挥空间也越可控。3.2 设计意图描述与参数 Schema我给这个 skill 起的名字是generate_commit_message它的触发条件包括“生成提交信息”“写 commit”“提交消息”“git commit”“一句话/一段话描述我的改动”等。然后定义参数 Schema。我的思路很简单用户至少要提供“改动描述”或“diff 内容”其中一种所以我做了两个可选字段但要求至少有一个非空。如果两个都为空就返回提示让用户补充。{ name: generate_commit_message, description: 根据用户描述的代码改动或提供的 diff 内容生成符合 Conventional Commits 规范的 Git 提交信息。, parameters: { type: object, properties: { change_summary: { type: string, description: 用户用自然语言描述的改动摘要例如修复了登录页在移动端样式错乱的问题 }, diff: { type: string, description: 用户粘贴的 git diff 内容如果提供了该字段优先基于 diff 分析改动 } }, required: [] } }这个 Schema 看起来简单但有一个坑我在早期经常踩required字段如果写了[change_summary]用户在对话中只贴了一段 diff 而没写任何描述意图识别模块就会卡住或者反复追问用户“请描述您的改动”体验非常差。后来改成“二选其一”的可选参数再用代码做非空校验才彻底解决。3.3 用 Prompt 模板实现 Skill 内部逻辑由于这个 skill 的核心是语义理解所以内部逻辑以 LLM 调用为主。但它不是简单地把参数拼进 prompt 就完了关键在输出约束。我要求模型返回一个 JSON里面包含type提交类型、subject标题、body正文可选和breaking_change是否有破坏性变更。用 JSON 结构化输出后续才能顺利做自动化处理而不是让模型直接吐一段散文。你是一个专业的 Git 提交信息生成器。根据用户提供的改动描述或 diff 内容生成一条符合 Conventional Commits 规范的提交信息。 要求 1. type 必须是以下枚举之一feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert 2. subject 不超过 50 个字符使用动词开头如“修复”“新增”“优化”“重构” 3. 如果存在 breaking change请在 body 中明确标注 BREAKING CHANGE 及说明 4. 直接从 JSON 输出不要任何解释或 Markdown 代码块标记在真正实现的时候我还会在 prompt 的末尾加上一则 few-shot 示例因为单纯给规则而不给样例模型很容易在 type 选择上任性发挥。比如用户说“改了下按钮颜色”如果你不给例子模型可能返回style这从规范角度其实不算错但很多团队会把这类改动归为style之外的fix或者chore所以示例可以帮你把团队的约定固化下来。3.4 用代码做确定性兜底与参数校验模型生成结果之后不能直接信要做校验和兜底。我用 Python 代码对模型返回的 JSON 做几件事尝试解析 JSON失败时重试一次且要求模型只输出纯 JSON校验type是否在枚举列表内不在则映射到最接近的值比如“bugfix”映射成“fix”“update”映射成“chore”校验subject长度超过 50 个字符时截断并把被截掉的内容自动放到body里这样信息不丢。这一步看似简单但正是它让 skill 从“演示可用”升级成了“生产可用”。大模型的输出天然带有随机性如果你不做这种系统性的兜底同一段 diff 跑十次可能有一两次结果就是坏的。3.5 注册到 Agent 并完成端到端调用写好了 skill 的核心逻辑最后当然要把它注册进 agent 主调度系统。如果你用的是 LangChain 之类的框架注册方式通常是装饰器或字典注册如果自己维护调度就是维护一个 skill 列表把 name、description、参数 Schema 和可调用函数关联起来。完成这一步之后我建议立刻跑三个端到端的用例正常描述、仅提供 diff、什么都不给。第三个用例应当主动引导用户补充信息而不是直接报错。这本质上是一个体验兜底很多用户第一次接触 agent 时根本不会按照你的预期把信息一次性给全引导话术就非常重要。4. 实战踩坑记录Skill 设计中最容易翻车的四个细节在真实项目里skill 不是写出来就完事而是要扛住各种奇怪输入的考验。曾经吃过的亏太多了这节我挑四个“一踩一个准”的坑来详细聊聊。4.1 参数设计过宽把意图识别带偏早期我在设计一个“发送 HTTP 请求”的 skill 时把 URL、方法、请求头、请求体的描述写得特别宽泛结果模型动不动就把简单的“帮我查一下某网站情况”理解成要发 HTTP 请求完全跳过了正常的上下文判断。后来我把 skill 的描述收窄成“仅当用户明确要求调用外部 API 或抓取指定 URL 时才使用”并在系统 prompt 里加了一条“优先使用已选技能不要主动请求外部接口”误触发率大幅下降。这里有个教训skill 的参数描述不是写给开发者看的而是写给意图识别模块看的。你写得越具体模型越知道边界在哪里。模糊的描述等于把判断权交给了随机的注意力分布不翻车才怪。4.2 过度迷信大模型没有留确定性后门另一个翻车点是把所有操作都交给模型比如让模型去解析日期、做数字计算、处理 JSON。当时觉得“大模型这么强肯定没问题”结果发现它在简单计算和格式规范化上经常出错而且每次错的还不一样。后来我改成能用 datetime 库算日期就绝不让模型算能用json.loads解析就绝不让模型写解析逻辑。模型只负责理解意图和生成自然语言文本剩下的脏活全交给代码。这也是我在设计 skill 时定下的一条铁律做加法时多问一句“这一步能不能用代码实现”如果能就不要用模型。一个 skill 里的模型调用越少它的行为就越可控测试成本也越低。4.3 上下文污染Skill 之间“互相打架”多个 skill 共存时最大的问题不是单个 skill 不好用而是它们之间会互相干扰。具体表现是用户提了一个问题A skill 和 B skill 都被触发了agent 不知道该走哪条路于是把两边的逻辑混合着执行输出四不像。这个问题我从两方面解决。第一skill 的触发条件写得更具排他性比如天气查询和日程查询都涉及“明天”那我就在天气 skill 里明确写“不处理会议、日程、待办类请求”在日程 skill 里明确写“不处理天气类请求”。第二在调度层面加了“互斥技能组”的概念同一组技能共享一次意图打分得分最高的才执行其他自动屏蔽。这样模型不会纠结。4.4 没有评测集改一处崩三处这个坑其实最要命。中期迭代时我优化了一个 skill 的 prompt结果它自己的效果变好了却导致另一个不相关 skill 的调用率暴跌。如果没有一套回归评测集你根本发现不了这种“连带伤害”。后来我花了两天时间把项目里所有 skill 的高频输入和典型边界输入整理成了一个 JSON 评测集每一条都标注了期望输出。每次改任何一个 skill 的 prompt 或参数逻辑我都会先跑一遍全量评测集。只有这种回归测试通过才敢把新版本放进实际环境。评测集本身不复杂难的是你有没有这个意识。很多项目死在“这次改完好像挺好的”这种错觉上过了两周才发现线上积累了一堆坏结果全都无从追溯。5. Skill 的测试、评估与迭代建立越用越稳的飞轮Skills 真正落地以后能不能持续变好主要看你的测试和迭代机制。哪怕你只有一个 skill我也建议从第一天就把这套机制搭起来。这节我来展开讲讲如何建立评测集、如何做回归测试、以及在实际迭代中如何利用日志驱动改进。5.1 构造评测集从真实日志里挖边界用例我构造评测集的方法非常简单粗暴把上线后的真实用户输入全部记录下来然后人工筛选出有代表性的样本。样本分成三类高频正常请求、同义改写请求、边界/恶意请求。比如对提交信息生成 skill 来说高频正常请求是“修复了登录页面闪退的 bug”同义改写请求是“登录页崩了帮忙搞一下 commit”边界请求是“我啥也没改就是想试试这个功能”。每一类样本能帮你抓住不同的问题。高频正常请求保证核心功能不退化同义改写保证意图识别足够鲁棒边界请求保证系统不会崩溃或者出现幻觉操作。有人会觉得维护评测集很麻烦但比起每次线上翻车后花半天去排查提前把这几十条用例跑一遍的成本低太多了。5.2 回归测试与断言不是“跑一下看看”而是“自动判定”有了评测集还不够你得能自动判定结果好坏。我看过很多团队的做法是“跑完人肉看一遍”这本质上还是不可持续的。我的做法是给每个评测样本配一个断言函数。有些是硬断言比如输出 JSON 的type必须在枚举内、subject长度不能超过 50有些是软断言比如用语义相似度判断生成结果和期望结果的关键词是否一致。可自动化判定的部分尽量用代码判定只有涉及主观质量的部分才保留人工抽检。这样每次改动 skill 后一条命令跑完所有用例输出通过率报告。如果通过率低于上一次说明改动引入回归如果持平或提升再进入下一步实际测试。5.3 日志驱动迭代记录触发失败与隐性失败最后也是我最看重的一点线上日志是 skill 迭代的最佳燃料。除了记录正常调用日志我还会额外记录“意图识别不确定性高”的请求——也就是模型给出的意图打分非常接近阈值的情况这些样本正是最容易误触发的场景。另一种值得关注的是“隐性失败”skill 明明被调用了也返回了结果但用户看完后又换了一种问法再问一遍。这通常说明结果没满足需求。想捕捉这一点我通常会给每个 skill 输出加一个 trace id关联到会话上下文再关注同一会话中是否出现对同一主题的二次请求。这些日志数据积累到一定数量后每两周我固定做一次分析把误触发和隐性失败的 bad case 整理出来针对性地调整意图描述、参数 schema 或 prompt 模板。这样 skill 的准确率就能沿着真实使用反馈一路往上走而不是靠拍脑袋优化。6. 更进一步Skill 的复用、组合与演进方向当你的 agent 里积累了十几个、几十个 skill 之后面对的就不再是单个 skill 的调优问题而是整个技能体系如何组织、如何组合、如何持续演进的问题。这一节我从实际工程角度聊聊长期规划的思路。6.1 从单体 Skill 走向技能库每一个 skill 本质上都是一小段“行为资产”。如果你换了一个项目或者换了一个基座模型好的技能库可以直接平移过来因为你只需要让新模型理解每个 skill 的意图描述和参数契约而无需重新定义这些任务本身。我现在会把常用的、与具体业务无关的 skill比如生成 commit、格式转换、URL 抓取、摘要总结单独整理成一个公共技能库大有“一次编写、处处复用”的好处。组织技能库时有一条重要的原则命名和描述要做到“自解释”。当你技能数量超过 20 个时意图识别模块会把它们全部过一遍如果你的描述含糊新接入的模型根本不知道该选哪个。我调试后的经验是描述第一句写清楚“这个 skill 能做什么”第二句写清楚“什么时候不要用”这两句比任何复杂配置都能提高命中率。6.2 技能组合从一个 Skill 编排成一条 Workflow单点 skill 解决的是单一任务但真实场景往往是一条链路。比如“分析一份 PDF 里的财务数据并生成周报”这涉及抓取文件、解析表格、抽取指标、生成周报文本等多个步骤。你可以把每一步都做成一个 skill再写一个编排层按顺序调用它们这其实就是最简单的 workflow。在这个编排层里我倾向于把一个 skill 的输出直接作为下一个 skill 的输入但一定要做“中间结果的校验”。比如解析表格这一步可能返回空数据如果直接往生成周报的 skill 里塞它会一本正经地生成一段毫无依据的周报。有了中间校验空数据就能被及时发现并触发重跑或向用户求助而不是一路错下去。6.3 演进方向从规则编排到模型自主规划但不盲目现在很多框架都在宣传“让模型自主决定调用哪些 skill、以什么顺序调用”听起来很美好但我个人的经验是对于已有明确流程的业务场景写死编排链路往往比让模型自由发挥更可靠。模型适合做“开放域的探索”比如你也不知道用户最终想干嘛而生产系统更适合“固定流程的高执行度”。所以我的建议是分而治之在确定性要求高的核心链路上用代码编排把技能负责的灵活判断限定在局部等到模型本身的可靠性进一步提升再去尝试更大胆的自主规划。这种思路也许不够“酷”但在真实业务里它才是能持续交付价值的选项。回到开头那个问题——agent-skills 是不是只是“给 prompt 换个名字”我觉得答案已经很清晰了。它把大模型从“什么都能聊”变成了“什么能干好”它是行为模块化、工程化和资产化的过程。这中间没什么神秘魔法无非是把意图、参数、执行、校验、评测这些环节一个不漏地做扎实。希望这篇文章能帮你少走几步弯路早点摆脱 prompt 一把梭的处境。