1. 为什么我想给 AI Agent 装上一套“肌肉记忆”第一次认真琢磨 Skill 这件事是因为我实在受够了每次开新会话都要把同一套规矩重新讲一遍。你肯定也经历过让 Agent 帮你写周报它给你整出一堆“首先其次最后”的废话让它改代码它把注释删得干干净净让它整理资料格式每次都不一样。问题不在于模型笨而在于它没有“肌肉记忆”——每次动作都要靠大脑临时想想出来的结果自然飘忽不定。所谓 AI Agent 的肌肉记忆说白了就是把那些反复要用、又不想每次都交代的操作规范固化成一个可复用的能力单元。这个单元就是 Skill。它不是什么高深的东西本质上就是一份写给 Agent 看的说明书告诉它“遇到这类任务按这个流程、这个格式、这个边界来做”。你可以把它理解成给新员工准备的 SOP 手册只不过读者从人换成了模型。我之所以想从零手撸一遍再研究自动生成是因为直接抄别人的 Skill 你永远不知道哪些字段是必须的、哪些是摆设。只有自己踩过一遍坑才能判断一个 Skill 写得好不好、能不能复用、会不会互相打架。这篇内容适合两类人一类是刚开始搭 Agent、被提示词管理搞得焦头烂额的开发者另一类是已经有一堆零散提示词、想把它工程化沉淀下来的实践者。下面我会把设计思路、字段细节、手撸过程、自动生成方案和排查经验全部摊开讲。2. Skill 到底是什么把提示词从“一次性”变成“可复用资产”2.1 从提示词堆砌到能力封装的心智转变大部分人用 Agent 的起点是在对话框里敲一大段指令。这种方式在单次任务里没问题但一旦任务重复出现你就会陷入复制粘贴的泥潭。更麻烦的是提示词散落在各个会话里改了一处忘了另一处最后自己都不知道哪个版本是对的。Skill 要解决的就是这个问题把提示词从“一次性消耗品”变成“可版本管理的资产”。我习惯用一个类比提示词像是你临时给朋友指路说“往前走两个路口左转”Skill 则像是你在路口立了一块路牌谁路过都能看懂而且内容固定、不会因为今天心情不好就指错方向。路牌立好之后你不需要每次都亲自指路Agent 自己就能按路牌走。这个转变的关键在于Skill 是有结构的、可被程序读取的而不是一段自由文本。从工程角度看Skill 带来的最大价值是确定性。模型本身是概率性的同样的输入可能给出不同输出。但当你把操作步骤、输出格式、边界条件都写进 Skill模型的发挥空间被压缩到一个可控范围内结果就稳定多了。这也是为什么我坚持认为Skill 不是可选项而是 Agent 从玩具走向工具的必经之路。2.2 SKILL.md 与 YAML一个管“说什么”一个管“怎么被找到”一个标准的 Skill 通常由两部分组成元数据和使用说明。元数据用 YAML 写在文件头部负责描述这个 Skill 叫什么、什么时候该用它、需要什么参数使用说明用 Markdown 写在后面负责告诉 Agent 具体怎么做。这两者分工明确缺一不可。YAML 部分的核心字段一般包括name、description、triggers和inputs。name是唯一标识不能重复description是一句话说明Agent 靠它判断这个 Skill 是否匹配当前任务triggers是触发条件可以理解为关键词或场景描述inputs定义需要用户提供哪些信息。这里有个容易踩的坑description写得太模糊Agent 就不知道该不该调用写得太具体又容易漏掉变体场景。我的经验是描述里要包含“动作 对象 产出”比如“把网页内容整理成结构化 Markdown 笔记”而不是笼统的“处理网页”。Markdown 部分则是真正的操作手册。我一般会分成几个固定小节适用场景、操作步骤、输出格式、注意事项。适用场景帮 Agent 二次确认是否该用这个 Skill操作步骤是核心要写成可执行的序列输出格式最好给出模板或示例注意事项用来兜底防止 Agent 在边界情况下乱来。这套结构不是官方规定而是我在反复调试后总结出来的实测下来最不容易出歧义。2.3 为什么选 Markdown YAML 而不是 JSON 或纯文本有人会问为什么不用 JSON 存元数据、用纯文本写说明我的理由有三点。第一Markdown 对人类友好你随时可以打开看、直接改不需要专门的解析器第二YAML 比 JSON 更适合写配置支持注释、换行、多行字符串写触发条件时不用把一长串关键词挤在一行里第三这两种格式在各类工具链里支持度极高几乎不用担心兼容性问题。纯文本的问题在于没有结构Agent 很难区分“这是元数据”和“这是正文”容易把说明文字当成指令执行。JSON 的问题在于可读性差写多行说明时要疯狂转义维护成本高。Markdown YAML 的组合刚好平衡了机器可读和人类可维护这两个需求。当然如果你的 Agent 框架只认 JSON那也没办法但至少在设计 Skill 内容时我建议先用 Markdown 起草再转成目标格式。3. 手撸第一个 Skill从需求拆解到文件落地3.1 先想清楚“这个 Skill 到底解决什么问题”动手写之前我强迫自己先用一句话回答这个 Skill 解决什么问题如果一句话说不清楚说明需求还没想明白写出来的 Skill 大概率是四不像。我第一个练手的 Skill 是“把网页内容整理成结构化 Markdown 笔记”因为这是我每天都要做的事痛点足够真实。拆解下来这个任务包含几个子动作抓取网页正文、去掉广告和导航、提取标题和关键段落、按固定模板输出。每个子动作都可能出问题比如正文抓取不准、模板套错。所以 Skill 里必须把这些步骤写清楚还要给出异常情况的处理方式。这里的关键是不要贪多一个 Skill 只解决一类问题。我见过有人把“写代码 写文档 发邮件”塞进一个 Skill结果 Agent 每次调用都像在猜谜。3.2 YAML 头部字段逐个填name、description、triggers、inputs下面是我实际用的 YAML 头部逐字段说明为什么这么写。name: web-to-markdown-note description: 把网页正文整理成结构化 Markdown 笔记保留标题层级和关键信息 triggers: - 网页整理 - 网页转笔记 - 保存网页内容 inputs: - name: url description: 需要整理的网页地址 required: true - name: template description: 输出模板可选 default 或 meeting required: false default: defaultname用英文小写加连字符避免空格和特殊字符方便程序引用。description我反复改过三版最终定成“动作 对象 产出”的结构因为 Agent 在匹配时主要看这句话。triggers我列了三个近义表达覆盖用户可能的不同说法。inputs里把template设为可选并给默认值是为了让 Skill 在大多数情况下不需要额外询问就能执行。这里有个细节required为 true 的字段如果用户没提供Agent 应该主动追问而不是瞎猜。3.3 Markdown 正文怎么写步骤、格式、边界一个都不能少YAML 只是门牌Markdown 正文才是真正的操作间。我的写法是固定四个小节每个小节都有明确目的。适用场景部分我会写“当用户提供网页链接并希望整理成笔记时使用”。这句话和 YAML 里的description形成呼应帮 Agent 二次确认。操作步骤部分我写成编号列表每一步都是可执行动作比如“第一步获取网页正文内容第二步识别并移除导航、广告、评论区第三步提取主标题和各级小标题第四步按模板组织内容”。步骤之间不要有歧义不要写“适当处理”这种模糊词。输出格式部分我直接给一个 Markdown 模板用代码块包起来Agent 照着填就行。边界情况部分我列了几种异常网页无法访问时返回错误提示正文过短时提示用户确认遇到付费墙时说明无法获取完整内容。这些边界如果不写Agent 遇到时就会自由发挥结果往往不是你想要的。提示Markdown 正文里不要写“你应该”“你必须”这类命令式语气改成“执行以下步骤”“按此格式输出”更中性模型执行起来更稳定。3.4 第一次实测Agent 到底会不会用这个 Skill写完文件后我做了三组测试。第一组直接说“帮我整理这个网页”看 Agent 能否自动匹配到 Skill第二组说“把这个链接存成笔记”看触发词是否生效第三组故意不给 URL看它会不会追问。实测下来第一组和第二组都能正确调用第三组也追问了说明required字段起作用了。但问题也来了Agent 在提取小标题时有时候会把网页里的广告标题也带进来。我回头检查 Skill发现操作步骤里只写了“提取主标题和各级小标题”没有说明如何区分正文标题和广告标题。于是我补了一句“只保留与正文语义连贯的标题孤立出现的短句视为广告并移除”。改完之后再测准确率明显提升。这个经历告诉我Skill 不是一次写完就完事的必须拿真实任务反复磨。4. 让 Skill 自动生成把重复劳动交给流程4.1 自动生成的核心思路模板 变量 校验手撸几个 Skill 之后你会发现大部分内容都是重复的YAML 头部结构一样Markdown 小节一样区别只在具体步骤和触发词。这时候就可以考虑自动生成。我的思路很简单准备一套模板把可变部分抽成变量再用一个校验环节确保生成的 Skill 符合规范。模板我用的是 Markdown 文件里面用占位符标记可变区域比如{{name}}、{{description}}、{{steps}}。变量来源可以是一份结构化配置也可以是从已有提示词里抽取的信息。校验环节负责检查必填字段是否齐全、name是否重复、triggers是否为空。这套流程跑通之后新增一个 Skill 的时间从半小时压缩到几分钟。4.2 用脚本把零散提示词批量转成 Skill 文件我写了一个 Python 脚本做这件事核心逻辑是读取一个 YAML 配置列表逐条渲染模板并写出文件。下面是我用的简化版代码你可以直接改成自己需要的。import yaml from pathlib import Path TEMPLATE --- name: {name} description: {description} triggers: {triggers} inputs: {inputs} --- ## 适用场景 {scenario} ## 操作步骤 {steps} ## 输出格式 {output_format} ## 注意事项 {notes} def render_skill(config): triggers \n.join(f - {t} for t in config[triggers]) inputs \n.join( f - name: {i[name]}\n description: {i[description]}\n required: {i.get(required, False)} for i in config[inputs] ) return TEMPLATE.format( nameconfig[name], descriptionconfig[description], triggerstriggers, inputsinputs, scenarioconfig[scenario], steps\n.join(f{idx1}. {s} for idx, s in enumerate(config[steps])), output_formatconfig[output_format], notes\n.join(f- {n} for n in config[notes]), ) def main(): configs yaml.safe_load(Path(skills.yaml).read_text(encodingutf-8)) out_dir Path(skills) out_dir.mkdir(exist_okTrue) for cfg in configs: content render_skill(cfg) (out_dir / f{cfg[name]}.md).write_text(content, encodingutf-8) print(fgenerated: {cfg[name]}) if __name__ __main__: main()这个脚本的关键在于把steps和notes都当成列表处理渲染时自动加编号和短横线。这样配置里只需要写纯文本不用操心格式。实测下来一次生成二三十个 Skill 文件毫无压力而且格式统一不会出现手写时漏掉某个小节的情况。4.3 生成之后必须做的三项校验自动生成最大的风险是“垃圾进垃圾出”。配置写错了生成的文件也是错的而且批量生成会放大错误。所以我强制自己每次生成后跑三项校验。第一项字段完整性校验。检查每个 Skill 是否包含name、description、triggers、inputs四个必填项缺一不可。第二项命名冲突校验。把所有name收集起来看有没有重复重复的会导致 Agent 调用时行为不确定。第三项触发词覆盖校验。检查triggers是否为空、是否有明显重复、是否和description语义一致。这三项用几十行代码就能实现但能挡掉八成低级错误。注意自动生成不要追求一次到位。我的做法是先小批量生成五到十个人工抽查确认没问题再放大批量。直接生成上百个再检查工作量反而更大。5. 踩坑记录那些文档里不会写的经验5.1 触发词写太多反而互相打架我一开始觉得触发词越多越好恨不得把用户可能说的所有话都列进去。结果发现当两个 Skill 的触发词有重叠时Agent 会随机选一个或者干脆两个都调用输出变得混乱。比如“整理网页”和“总结文章”这两个 Skill如果触发词都包含“整理”就会打架。后来我定了一条规矩每个 Skill 的触发词控制在三到五个且必须和description强相关。如果两个 Skill 确实容易混淆就在description里写清楚区别比如一个强调“保留原文结构”一个强调“提炼核心观点”。实测下来触发词精简之后匹配准确率反而更高。5.2 description 写得太“聪明”会导致匹配失败有段时间我喜欢在description里用比喻和修辞觉得这样显得高级。结果 Agent 匹配时经常找不到对应的 Skill因为它不理解比喻。比如我写“把网页变成知识卡片”Agent 不知道“知识卡片”是什么匹配就失败了。改成“把网页正文整理成结构化 Markdown 笔记”之后匹配立刻正常。这件事让我明白Skill 的元数据是写给机器看的不是写给人类看的。准确、直白、包含关键名词比文采重要得多。你可以把description理解成数据库里的索引字段它的唯一任务就是让 Agent 快速判断“这个 Skill 是不是当前任务需要的”。5.3 输出格式不给模板Agent 就会自由发挥我早期写的 Skill 里输出格式部分只写了“按 Markdown 格式输出”。结果 Agent 每次输出的结构都不一样有时候用一级标题有时候用三级标题有时候干脆不分段。后来我学乖了直接在 Skill 里贴一个完整模板用代码块包起来Agent 照着填就行。模板不需要很复杂但必须包含所有固定部分。比如笔记类 Skill模板里要有标题、来源、正文、要点四个区块。Agent 看到模板后会自觉把内容往对应位置放输出一致性大幅提升。这个技巧看起来笨但效果立竿见影。5.4 Skill 之间也会“抢活”需要明确优先级当 Skill 数量超过十个之后我遇到了新问题有些任务同时符合多个 Skill 的触发条件Agent 不知道该用哪个。比如“把网页整理成笔记”和“把网页内容翻译成中文”如果用户说“帮我处理这个网页”两个 Skill 都可能被调用。我的解决办法是在 Skill 里加一个priority字段数值越小优先级越高。同时在description里写清楚适用边界比如翻译类 Skill 明确写“当用户要求翻译时使用”。另外我会定期检查 Skill 列表把功能重叠的合并或拆分保持每个 Skill 职责单一。这套组合拳打下来抢活的情况基本消失了。6. 常见问题速查与排查思路6.1 Skill 不生效的排查顺序遇到 Skill 不生效我一般按这个顺序排查先看 YAML 头部有没有语法错误比如缩进不对、冒号后面没空格再看name是否和文件名一致有些框架要求两者匹配然后看description和triggers是否覆盖了用户的表达方式最后看 Skill 文件是否放在框架指定的目录里。这四步能解决大部分问题。如果四步都查了还是不生效我会把 Skill 内容打印出来手动模拟 Agent 的匹配过程看它在哪一步卡住。有时候问题出在框架的加载逻辑上比如缓存没刷新、文件编码不对。这种时候重启服务或者清缓存往往能解决。6.2 输出格式不稳定的三种可能原因输出格式不稳定通常有三个原因。第一Skill 里没给模板Agent 自由发挥第二模板给了但不够具体比如只写了“用列表”没写用有序还是无序第三Skill 和其他 Skill 冲突Agent 混用了两套格式。对应的解决办法分别是补模板、细化模板、排查冲突。我还会在 Skill 的注意事项里加一句“严格按模板输出不要增删区块”。这句话看起来多余但实测能明显减少 Agent 的“创意发挥”。模型有时候会自作主张优化格式明确禁止之后它就老实了。6.3 自动生成脚本报错的常见原因自动生成脚本报错八成是配置文件的格式问题。YAML 对缩进极其敏感多一个空格少一个空格都会报错。我建议用支持 YAML 语法高亮的编辑器写配置能提前发现大部分问题。另外字符串里如果有冒号或特殊字符记得用引号包起来否则解析会出错。还有一个容易忽略的点是编码。配置文件如果保存成非 UTF-8 编码读取时可能乱码导致生成的 Skill 内容错乱。我统一用 UTF-8并且在脚本里显式指定encodingutf-8避免依赖系统默认编码。问题现象可能原因排查动作Skill 完全不触发YAML 语法错误或目录不对检查缩进、文件名、存放路径触发但输出混乱触发词冲突或缺少模板精简触发词、补充输出模板生成文件内容错乱配置编码或占位符错误统一 UTF-8、检查占位符拼写多个 Skill 抢活职责重叠、缺少优先级合并拆分、增加 priority 字段6.4 我个人的避坑清单最后分享几条我踩坑后总结的规矩。第一Skill 文件命名和name字段保持一致减少心智负担。第二每次修改 Skill 后用至少三个真实任务回归测试确认没有破坏原有行为。第三定期清理不再使用的 Skill避免列表膨胀导致匹配变慢。第四把 Skill 纳入版本管理每次改动都有记录出问题能回滚。第五不要在一个 Skill 里塞太多步骤超过十步就考虑拆分。这些规矩看起来琐碎但每一条都是真金白银换来的。Skill 这套机制本身不复杂复杂的是如何让它稳定、可维护、可扩展。手撸一遍是理解它的最好方式自动生成是放大它的最好手段而踩坑记录则是让后来者少走弯路的唯一途径。我现在维护着几十个 Skill日常任务基本都能自动匹配执行偶尔出问题也能快速定位。这套东西一旦跑顺你会发现自己从“反复交代”的循环里彻底解放出来了。