用Skill.md定义AI Agent技能：模块化提示词的工程实践

最近一段时间我在折腾AI Agent。做完几个Demo之后一个很明显的感受是大部分Agent的“智能”不是靠模型参数撑起来的而是靠你怎么把能力边界写清楚。我最近一次比较大的调整就是把智能体的某个技能从系统提示词里拆出来单独用一份Markdown文件去定义也就是标题里说的Skill.md。这个方法不算新但真的值得试一次尤其是当你发现系统提示词越来越长、改一句要动全局、Agent还时不时“精神分裂”的时候。这个文件解决的核心问题很简单把“技能”当作一个可独立维护、可单独调试、可反复复用的模块而不是塞进一段又长又杂的提示词里。它适合所有在对话式Agent平台上做配置的人不管你是刚接触智能体搭建的新手还是已经被复杂提示词折磨过一阵的老手这篇内容应该都能给你一些可直接落地的思路。我以一份“城市48小时旅行规划技能”为实例把从设计、写文件、调参数到排查问题的完整过程拆开讲一遍所有代码和模板都可以直接抄走改。1. 为什么我会尝试用 Skill.md1.1 三个让我不得不改的痛点先说以前的做法。我一直习惯把所有行为规则都堆在系统提示词里面比如“你是一个旅行助手”“你说话要简洁”“你输出格式要按日期分块”“如果用户提到美食你优先推荐本地老店”……听起来没问题但实际跑起来之后三个问题会越来越明显。第一个痛点是提示词越来越长。一个Agent叠加三五个技能之后系统提示词经常冲到三四千字。模型对长上下文的注意力不是均分的写在后半段的规则很容易被“遗忘”经常出现用户问“第二天下午去哪玩”Agent却只记得早上安排的情况。第二个痛点是技能之间互相干扰。我想同时给旅行助手加入“行程规划”和“美食推荐”两个方向结果只要用户问“附近有什么好吃的”Agent不但推荐餐厅还硬要排一个三天的行程表完全不管用户只是想吃个午饭。本质上就是边界没画清楚。第三个痛点是迭代成本高。每次要调行程技能都得改整段提示词改完还要担心会不会影响美食推荐的部分。更麻烦的是同一个技能想复用到另一个“商务出行助手”上基本只能复制粘贴然后再手工删掉不相关的句子。这三个痛点叠加起来让我开始认真找替代方案。后来我在一些平台的能力配置里看到了用Markdown文件定义技能的方式仔细研究了一下决定完整试一轮。1.2 Skill.md 的本质把“能力”变成“文件”Skill.md说白了就是一份用Markdown语法编写的能力说明书。它和普通提示词最大的区别在于提示词描述的是“你是谁、你要干什么”而Skill.md描述的是“你什么时候启动这个能力、启动之后按什么步骤执行、执行时受什么约束”。这个区别往深了说其实是把技能从“身份设定”里剥离出来了。以前你写“你是一个旅行助手”Agent会把所有跟旅行沾边的请求都照单全收而Skill.md的方式更像给Agent装了一个“插件模块”只有用户明确表达了某种意图比如要安排行程、比较线路模块才被激活。这样做带来的直接好处有三个一是系统提示词能保持精简只负责全局人设和安全底线二是每个技能都能单独测试出了问题只改一个文件三是技能本身变成了可复用的资产换个Agent项目把同一个Skill.md放进去就能用。我个人的体会是这种“身份与能力分离”的思路在Agent从Demo走向实际可维护的过程中几乎是必经之路。你可以在初期靠一段长提示词快速验证想法但一旦功能点多起来必须转向模块化的管理方式。1.3 适合用 Skill.md 来组织的典型场景那是不是所有Agent能力都应该用Skill.md去定义呢也不是。我试了一圈之后觉得有三类任务特别适合。第一类是边界清晰、需要稳定输出格式的任务。比如行程规划、生成周报、数据分析报告等。这类任务的核心价值在逻辑结构而不是自由发挥所以特别适合用明确定义的文件去约束。第二类是高频出现的任务。用户会反复触发类似请求如果不做成独立技能系统提示词会被这些重复逻辑占掉一大半。独立成文件之后一次定义、反复生效省下来的上下文空间非常可观。第三类是涉及较多分支判断的任务。比如“根据预算决定推荐什么等级酒店”“根据出行人数调整行程节奏”。这种复杂条件写进提示词很容易自相矛盾但在Skill.md里可以用清晰的段落和列表逐层展开模型理解起来会轻松很多。反过来说一些高度依赖创作自由的任务比如“写情诗”“讲故事”就不太适合用这种结构化去约束强行套模板反而会让结果变得生硬。这个边界我心里大概有个数后面的实操部分也会往这个方向继续展开。2. Skill.md 的结构拆解与模板设计2.1 front matter 里到底该写什么我第一天写Skill.md的时候以为这就是一个带标题和几个小标题的Markdown文档后来发现不是这么简单。一个能被平台正常识别和加载的Skill.md通常需要包含结构化的元信息区也就是类似YAML格式的front matter。这块是给系统看的不是给用户看的。以我实际测试过的结构为例最基础的front matter至少要包含这几个字段技能名称、技能描述、触发条件、版本号。如果平台支持还可以加上作者、创建时间、标签等辅助信息。name起一个短名字最好和实际行为强相关。我一般不会用“旅行助手”这种宽泛的名字而是用“城市行程规划”这种一眼能看出功能的。description一句话说清这个技能能干什么。这段描述在多数平台里会被用于技能激活的语义匹配所以一定要把用户可能用的自然表达包含进去。trigger触发条件。我会把高频的同义说法都列进来比如“安排行程”“帮我规划”“制定旅行计划”“想玩两三天”等。version版本号。这个很多人会忽略但一旦技能多起来、迭代次数上来没有版本号你根本不知道线上跑的到底是哪份文件。需要说明的是不同平台对front matter的支持程度不一样有的只解析固定的几个字段有的允许自定义字段。我给你的建议是先用官方文档里推荐的字段跑通了再加自定义内容。我自己踩过“自定义字段不生效 文件整体报错”的坑后面排查部分会详细说。2.2 正文部分别急着写流程先写约束很多人写到这里就迫不及待地上流程“第一步询问目的地第二步搜索景点第三步生成行程……”我的建议是反过来先写约束条件再写执行流程。为什么因为模型在执行流程的时候真正容易出错的地方不是“不知道下一步做什么”而是“不知道哪些不能做”。举个例子如果我不写约束模型在生成行程时可能一天塞进5个景点用户规划的是步行游览结果被安排到相距20公里的地方。约束条件是可以提前把这些坑填掉的。我在正文里通常分成四个区块。行为边界明确技能能做什么、坚决不做什么。比如“本技能只负责生成行程建议不负责酒店预订”“不推荐超出用户指定时间范围的行程”。执行流程用编号列表按顺序写步骤每个步骤说明输入是什么、输出是什么、需要做什么判断。输出格式定义最终回答的结构比如按天分节、每节包含上午/下午/晚间安排、包含交通方式和步行时间。示例给一个完整的输入输出样例让模型照着参考。这个对稳定输出格式非常有效。这四个区块写完一份Skill.md的骨架基本就成型了。我在实操中发现执行流程和输出格式的比例可以动态调整如果发现模型经常漏掉步骤就加重流程描述如果发现格式不稳定就加重示例的比重。2.3 一份可以直接抄的通用模板这里放一个我用了很久的通用模板结构上足够完整你拿到之后可以根据自己的场景改字段、改步骤。--- name: 技能名称 description: 一句话说明功能包含用户可能的提问方式 trigger: 触发词或触发条件描述 version: 0.1.0 --- # 技能名称 ## 技能目标 用一句话描述这个技能要达成的最终结果。 例根据用户的时间、偏好和预算生成一份可执行的城市行程表。 ## 行为边界 - 只处理与[领域]相关的内容不处理[无关领域]。 - 当用户输入信息不足时先追问关键参数不自行假设。 - 不提供[违规或不建议的操作]建议。 ## 执行流程 1. 读取用户输入提取[关键参数A、B、C]。 2. 如果缺少参数按重要性顺序追问。 3. 根据参数整理[候选内容]。 4. 按[输出格式]生成最终结果。 ## 输出格式 - 按天分节每天包含上午、下午、晚间安排。 - 每个地点标注预估停留时间和交通方式。 - 末尾增加一栏“备选调整”给出天气变化的替代方案。 ## 示例 用户输入示例 上海两天一夜喜欢历史建筑预算宽松。 期待输出示例 Day 1 上午武康路-安福路漫步约2.5小时…… 以下为完整示例内容用这份模板起步你会发现写一个技能其实不难难的是后面根据实际效果不断地修正。我的经验是第一版能覆盖60%的常见情况就算成功剩下的40%靠迭代补上。3. 实操从零写一份能用的旅行规划技能3.1 场景与目标一个城市48小时旅行助手为了把整个过程讲清楚我选了一个具体场景来跑完整流程做一个“城市48小时旅行规划”的Skill.md挂在某个对话式Agent上目标是让用户给出目的地城市、偏好和预算后Agent能生成一份完整、可执行、节奏合理的周末两日行程。这套技能为什么适合拿来练手因为它包含了完整的决策链输入解析、信息补全、内容组织、格式输出。每个环节都能体现出Skill.md不同写法带来的效果差异。我先设定了几个明确的要求一是时间必须控制在用户指定的范围内默认就是两天二是要区分步行和车程避免安排出“十分钟逛完A景点然后打车五十分钟去B”的弱智行程三是每半天最多安排一个核心景点和一个备选景点防止行程过满。这些要求看起来不难但如果你全都写进系统提示词会让提示词变得又臭又长而放到Skill.md里它们只是在技能被触发时才会被读取和执行长期看反而更省资源。3.2 第一版能跑但很“脆”我的第一版Skill.md写得很简单基本就是把需求翻译成了Markdown结构只包含了技能描述、触发条件和基础流程。当时想着“先跑通再看效果”结果跑下来发现确实能跑但是非常脆。最大的问题是触发经常失灵。我设置trigger是“安排行程”“规划旅行”“制定计划”但用户真实提问往往是“周末可以去哪玩玩”“两天一夜有什么推荐”“我想去重庆耍两天”。在平台默认的语义匹配机制下前三组词和后面的说法匹配度不够技能经常不被激活Agent只能靠残余的系统提示词勉强应对输出质量直线下降。另一个问题是流程太模糊。我在执行流程里只写了“根据用户输入生成行程”但没有定义“如果预算信息缺失怎么办”“如果用户没说偏好怎么分类”。结果Agent经常自己拍脑袋假设比如用户明明没说预算它默认给了经济型酒店选项。不是说这样不对而是这种假设可能完全偏离用户预期。看了几次测试结果之后我把第一版判定为“流程骨架可用但细节约束严重不足”。而这个判断直接驱动我去写了第二版。3.3 第二版加了触发词、约束和示例之后第二版的改动集中在三个地方。第一是触发区的写法我把关键词从短词改成了语义单元不再机械地罗列术语而是写“包含但不限于以下表述我想去X玩两天、X周末游、帮我规划X行程、X两日游攻略”这种更接近真实对话的写法明显提高了命中率。第二是行为边界里加了大量条件分支。比如“当用户给出预算数值时以此为准当用户未给预算时优先询问若用户表示随意则提供三种预算档位供选择”“当用户只说城市未说偏好时默认覆盖经典景点与本地美食两类行程中必须包含至少一次老城区步行体验”。这些约束让Agent在面对信息不全的输入时有个明确的兜底策略而不是自由发挥。第三是我加了一组完整的输入输出示例。示例在技能文件中起到“锚定”作用模型会模仿示例的格式和语气去生成答案。我从第一版“只写模板结构”改成“给一个具体城市的具体输出”效果立竿见影输出格式开始变得稳定不再出现表格和分点混用的情况。改完第二版之后我跑了十组不同风格的测试输入包括“北京周末游带父母不要太累”“成都两天爱吃辣预算三百一天”“长沙纯拍照打卡”等整体输出质量比第一版高了一个档次。3.4 怎么判断这个技能真的生效了技能文件写完之后最怕的就是“以为生效了其实没有”。我总结了一套自己用的验证流程每次写完新版本都必须过一遍。第一步是裸测。先把技能文件禁用直接问Agent同样的问题记录它“无技能”状态下的输出。这一步能帮你建立对比基线后面判断改进幅度才有依据。第二步是加载技能后再测同样的问题。如果输出和上一步差异不大说明技能根本没有被触发或者触发了但内容被系统提示词的风格压制了。这时候检查重点应该是触发条件和技能描述是否写得太窄了。第三步是检查平台日志。多数Agent平台在调试模式里能看到“本次对话命中哪些技能、激活了哪一段配置”之类的日志。我通过日志确认行程规划文件是否真的被调用而且能看出触发是靠关键词匹配还是语义匹配。第四步是做多轮对话测试。只测单轮是不够的因为实际用户会频繁补充信息和修改条件。比如用户先说“去杭州玩两天”然后接着补充“不要爬山喜欢吃面食”如果技能没有正确保存前文意图可能会重新触发生成一套完全不一样的行程这种体验非常糟糕。这四步走完一份Skill.md是否真的“能用”我心里基本就有底了。4. 常见问题与排查技巧实录4.1 技能就是不触发怎么定位这是所有人都会遇到的第一个问题我也不例外。写好的技能放在那里Agent就是不调用回答一点都不专业仿佛技能不存在。我排这个问题的顺序是固定的。先查trigger描述看是不是写得太窄或者太像文档用语。我第一次写trigger时用了“规划旅行”但用户真实说法十有八九是“帮我安排一下”“有什么推荐”这就是语义覆盖不够。改成“包含但不限于以下说法”后命中率明显高了。再查技能description看是否和Agent的人设冲突。有些Agent系统提示词里写了“你是一个旅行助手”如果系统提示词本身已经覆盖了类似意图平台可能优先走全局规则而不是调用技能。这种情况下可以在系统提示词里加一句“当表达旅行规划类需求时必须调用行程规划技能”把优先级关系明确起来。最后查平台日志。很多问题肉眼看是看不出来的日志能直接告诉你平台没有做技能召回还是召回了但生成阶段没按文件走。这一步能把排查方向瞬间缩小省掉大量盲目试错时间。4.2 输出了“看着很对用着很空”的内容这类问题比不触发更隐蔽。技能生效了格式也挺像回事但内容经不起细看。比如建议游客“上午去西湖下午去灵隐寺”但没说明灵隐寺需要提前预约也没提示下午过去排队可能要两个小时。我排查这类问题的时候重点看两个地方。第一是行为边界里有没有要求“信息完整性校验”。我在第二版里加了一条每个推荐地点必须附带开放时间与预约要求的备注如果无法确认必须在结果中标注“请出行前再次确认”。这一条能大幅减少“看起来很合理、实际不可执行”的内容。第二是执行流程是否定义了信息核验步骤。流程里只写“整理候选内容”是不够的我会更明确地写“对每个候选地点检查是否需要预约、是否周一闭馆、是否适合雨天游玩”。这些细节直接决定输出的可用度。另外一个很有效的技巧是给Agent补充“反向说明”也就是告诉它遇到什么情况不该推荐什么。比如“不要在夏季推荐需要长时间户外暴晒的中午时段景点”“雨天必须优先推送室内选项”。这种反向限制比正面要求更加刚性在实际使用中减少了很多不合理的建议。4.3 多技能同时命中时怎么避免打架当Agent里挂了多个技能时很容易出现同时触发两个功能模块的情况生成内容就会变成“四不像”。我最开始同时挂“行程规划”和“美食推荐”时用户问“去成都玩两天推荐火锅店”结果Agent给了一大段像行程表一样的火锅店安排非常滑稽。解决思路不是让触发变得更严而是给每个技能划分清晰的“专属领地”。我在行程规划技能里加了一条硬性约束“本技能不负责推荐具体餐厅除非用户明确询问‘吃什么’。”同时在美食技能里加了对应约束“本技能只推荐餐厅与菜系不生成完整行程。”如果平台支持技能优先级设置我会把更具体、更垂直的技能放在更高优先级。前面这个例子里用户的真实意图明显偏向美食推荐所以美食技能的优先级应该更高。这种“领地划分 优先级”的双保险基本能解决多数冲突问题。4.4 平台兼容与格式踩坑记录Skill.md看着就是普通的Markdown但不同平台解析起来还是有不少差异这些差异不亲测是发现不了的。第一个坑是front matter的解析规则。部分平台对未知字段要求非常严格写了不支持的字段可能导致整个文件加载失败。我的处理办法是严格按平台文档来文档里没出现的字段坚决不写自定义字段只放在正文区不放进front matter。第二个坑是Markdown语法的兼容层次。三级标题、加粗、列表、引用块属于基础语法基本都支持但表格在不同平台上的渲染稳定性不一致。如果你发现技能文件在预览时表格是乱的建议直接把表格改成列表形式虽然视觉上没那么精致但模型读取和执行的稳定性更高。第三个坑是中英文标点混用。我在某个版本里无意间把description的冒号打成了中文全角结果平台死活识别不了。这类问题很难肉眼发现排查思路是如果文件结构没问题但不生效就把标点、空格、缩进全部换成半角试一遍。还有一个很容易被忽略的问题结尾空行。有些平台要求文件末尾要有换行否则最后一行可能读取不完整。我现在的习惯是写完保存前在最后一行按一下回车确保文件以空行结束这个习惯已经被证明能规避不少诡异Bug。5. 结合个人经验的一些补充5.1 什么情况下真的别用 Skill.md写到现在好像Skill.md无所不能但必须承认这个方法不是银弹。我实际用下来有三类情况不适合硬上。第一类是高度依赖闲聊人格的任务。如果你的Agent核心卖点是“像朋友一样陪你聊天”那么每个回复都要有灵动劲儿这种风格很难被结构化文件的条条框框约束出来。这时候用Skill.md去定义行为边界很容易得到一个“正确但无聊”的聊天机器。第二类是知识覆盖面极广、几乎无法穷举触发词的任务。比如一个“百科问答”技能用户的问题千奇百怪你写trigger是永远写不完的。这种更适合把知识库做成检索增强RAG交给底层检索能力去解决而不是靠技能文件硬匹配。第三类是还在快速探索的试验性功能。如果需求三天两头变化、边界模糊不清一开始就写一套结构化文件反而会拖慢迭代速度。我的习惯是先用系统提示词快速验证逻辑确认可行之后再固化成Skill.md。过早固化大概率要反复重写得不偿失。5.2 我现在的日常使用习惯经过这轮尝试之后我基本形成了自己的工作流。新建Agent项目时我会先想清楚“哪些能力以后要复用”然后从一开始就把这类能力往Skill.md方向设计而不是全部堆在人设提示词里。具体写作习惯上我总结了几条铁律。每次修改后版本号必须递增不用多复杂0.1.0改到0.1.1就行trigger里永远写“包含但不限于”给自己留扩展余地每条输出格式的约束后都跟着一个具体示例只列规则不给示例如同空中楼阁。还有一条特别想强调的技能文件里的每句话都要有改动理由不要为了写而写。我在迭代过程中删掉过好几段“看起来很专业”但不是实际需要的内容比如某次我加了一长串关于酒店星级和价格带的分层规则结果是生成内容变得冗长而且僵硬删掉之后反而更自然。Skill.md这个方法本质上是用一点工程化的思路去组织Agent能力的描述方式。上手成本不高但带来的可维护性提升非常明显。我从一个“全塞系统提示词”的选手变成一个“按技能模块组织”的选手只花了不到一周的时间期间迭代出来的教训基本都写在上面了。如果你也正在被越来越长的提示词和越来越不听话的Agent折磨不妨挑一个高频功能试试这招。先写一版粗糙的跑起来再慢慢加约束你会明显感觉到整个搭建过程变得可控很多。这个尝试我觉得值得做。