这两年我一直在用SKILL做智能体能力封装写了不少脚本式的技能定义。说实话写的时候很爽用起来很痛苦。每次换一个输入场景技能就像换了一个人要么答非所问要么在细节上自由发挥。以前我一直觉得是模型能力不够直到最近我把SKILL的写法整体推倒改成“框架细节”的双层结构又专门写了一份测试项目文档来做验证才发现问题出在写法本身不在模型。这篇就把这次改造的思路和验证过程完整记录下来给正在折腾智能体框架、SKILL开发、插件化技能封装的朋友一个参考。先说结论把SKILL拆成“稳定框架层”和“可迭代细节层”之后技能的稳定性和可维护性都明显上了一个台阶而这一切靠的是一份结构化的测试项目文档来托底。这篇文章会和你聊清楚旧写法的问题、新写法的拆法、验证方法以及我在落地过程中踩过的几个坑。1. 旧写法的三个瓶颈为什么零散SKILL总是“一用就废”在说“框架细节”之前我得先自曝一下以前是怎么写SKILL的。过去的做法很典型脑子里有一个目标打开编辑器就开始写提示词开头是“你是一个擅长XX的助手”中间堆上几个步骤结尾加一句“请按照要求输出”。整个SKILL像一段絮絮叨叨的说明书写完就丢给模型去跑。表面上看该有的指令都有但实际上这种写法存在三个很隐蔽的瓶颈。第一个瓶颈是没有能力边界。脚本式SKILL默认模型能把所有事情都干了所以很少写“什么情况不该处理”。我举个例子有一次我写了一个人物信息整理技能功能是从简历和访谈材料中抽取人物经历。测试时我随手输入了一段产品介绍这个技能居然把产品功能当作人物经历来拆分输出了一堆“该产品擅长协作”、“该产品有三年迭代经验”这类荒谬字段。原因很简单SKILL里没有设置禁区模型面对边界外的输入不会拒绝只会硬生生套模板。第二个瓶颈是细节全靠临场发挥。传统写法里细节通常以长段落的形式藏在描述文字里比如“注意格式要统一语气要严谨内容要覆盖全面”。这些细节看起来存在但没有任何结构模型只能根据上下文猜测每条细节的权重和适用范围。上午测试同一个技能输入A场景时正常下午换输入B场景就崩溃。复盘之后发现上午能成功是因为某条隐式规则碰巧和模型的当前输出习惯对齐了而下午换了一种输入格式那条规则就失去锚点了。第三个瓶颈是最要命的改无可改验无可验。脚本式SKILL的信息是线性排列的改了一个细节你根本判断不了它会波及后续哪一步。每一次修改都等于全量改动全量改动就要全量回归而回归测试又因为没有明确的验收标准只能靠肉眼观察输出“像不像”。到了这个阶段整个SKILL就变成了一团说不清道不明的黑箱越改越不敢动。这三个瓶颈汇总起来指向同一个方向SKILL写作缺少层次。稳定不变的东西和频繁调整的东西混在一起导致维护成本全部集中在了最不该集中的地方。真正成熟的写法应该把“骨架”和“血肉”分开让前者保持稳定让后者随时可替换。2. 框架先行把能力边界、工作流主线与内部目录先定死这次全新尝试我给自己定的规矩是先写框架不碰任何细节。只用框架回答四个问题这个SKILL给谁用、在什么范围内用、完成任务分哪几步、每一步的输入输出是什么。这四个问题全部回答完框架层才算完成。我最后沉淀出来的框架层模板长这样SKILL_NAME: 适用对象: 描述该技能面向的角色或岗位 能力边界: 明确能做什么、不能做什么 输入协议: 启动技能需要哪些信息 输出协议: 交付物应包含哪些模块或章节 工作流: W1: 解析输入 W2: 确认结构 W3: 逐模块生成 W4: 对照检查 W5: 输出最终结果 禁用场景: 列出不该调用本技能的情况 依赖项: 外部工具、模板、资料清单这套模板本身不复杂难的是往里面填真实内容。以我这次的实践为例我的目标是让SKILL负责生成一份测试项目文档那么框架层我填的内容是这样的适用对象测试工程师、QA、自动化测试设计人员。能力边界只负责测试文档的生成、结构设计和评审辅助不负责实际测试执行不负责需求分析。输入协议项目背景、功能列表、接口说明、测试环境信息、可选的既有模板。输出协议一份包含文档信息、项目概述、测试目标、测试范围、测试环境、测试用例设计、缺陷定义与管理、风险与依赖这8个章节的完整测试项目文档。工作流主线解析输入信息 → 锁定文档8章节结构 → 逐章节生成内容 → 逐章节对照检查 → 输出终稿。禁用场景输入信息为空、需求尚未冻结、用户只给了一句“帮我写个测试文档”没有任何背景信息。依赖项功能列表清单、接口文档、测试环境配置表。这套框架的价值第一体现在“能力边界”和“禁用场景”上。当模型在执行细节时它会时不时回看框架层凡是超出边界的请求要么拒绝要么先补齐信息再说。以前那种把产品介绍当人物经历拆解的低级错误从根上就被拦截了。第二体现为“输入协议”和“工作流”的高度确定性。无论用户输入长什么样模型都会先走解析流程把信息映射到规定的字段上再决定下一步动作。这就像写代码之前先定义接口接口定了函数体怎么写都不会跑出调用方预期。另外我还做了一件以前从没做的事给SKILL定义内部目录。这里的目录指的不是文件系统目录而是技能在执行过程中将要生成的文档的知识结构。我把输出协议里的8个章节固定成了唯一允许的目录结构任何一次执行都必须围绕这8章来组织内容。别小看这个动作它让输出结构的可预期性大大提升。模型不再是每次自由想象文档该怎么组织而是像一个员工拿着公司标准模板在工作。写框架层的过程给我最大的感受是以前觉得“把话说清楚”是细节的活实际上恰恰相反真正决定一个技能质量的是那些不变的硬约束。细节负责把约束执行到位而框架负责保证执行方向正确。3. 细节兜底参数表、可执行步骤与异常分支一个都不能少框架层定完之后细节层才有地方安放。这次我对细节做了一次“去描述化”处理把所有散落在长段落里的规则全部转成结构化表格和可检查条目。细节层的信息来源有三个一是过去踩过坑的经验总结二是团队模板里反复出现的必填字段三是我对模型在长文本生成时易犯错误的主观预判。我把它们归类成四张表参数细节表、步骤细节表、异常细节表、输出细节表。细节类型作用说明实际示例参数细节规定变量名、默认值和允许取值范围用例优先级限定为P0/P1/P2未填写时默认P2步骤细节规定每个工作流步骤的具体动作和判定标准写完用例后必须检查每条用例是否包含“预期结果”字段异常细节规定输入残缺或冲突时的处理方式缺少功能列表时不生成文档先输出追问清单输出细节规定格式、措辞、禁止项和自检要求用例标题中禁止出现“测试一下”、“验证”等模糊动词别看这几张表很简单它们才是细节层里真正让技能脱胎换骨的部分。我举一个具体场景以前写“测试环境”这一章旧SKILL最多给出一句“请根据项目情况填写环境信息”。这句话看起来无害实际上模型经常把“建议配置”当成“实际环境配置”写进文档导致生成的文档与真实环境完全对不上整个文档的可信度直接崩盘。这次我在输出细节表里加了一条硬规则所有环境信息必须以用户输入的实际软硬件清单为准尚未提供的项目一律标注“待补充”禁止自行假设配置。只加了这一条文档中环境章节的准确率就从原来的“看运气”变成了稳定可用。步骤细节的写法也同样做了升级。过去是“确认文档结构”这种动作描述模型不知道确认到什么程度算结束。现在我在步骤细节表里把每一步都改成“动作判断输出”三段式结构。以步骤“锁定文档结构”为例动作将输入的功能列表与8个章节逐一比对。判断每个功能是否都能在测试范围或测试用例设计章节中找到对应。输出若发现某个功能缺少映射输出“功能未覆盖清单”并列出缺失项。这样写看起来啰嗦但价值巨大。模型拿到的是可判定的执行标准而不是一个模糊的方向。任何一个环节执行完都可以明确地说“完成了”或者“未完成”不存在含糊地带。异常细节这块受篇幅限制我不打算全列出来但有一个点值得单独说一下“缺失追问”策略。以前模型在输入不全时倾向于硬着头皮编内容现在我在异常细节表里明确写了触发追问的条件和追问格式。比如功能列表缺失时不生成草稿而是输出一个带编号的待补充清单。这个行为模式一旦在细节表里固化模型输出的专业感会明显增强因为它看起来像一个合格的测试负责人在做需求确认而不是一个闷头瞎写的生成器。4. 验证动作用一份可执行、可对照的测试项目文档检验改造效果框架和细节都写完并不代表这套写法就成立了。整个改造过程中最重要的一环是验证。我选择的验证载体就是一份真实的测试项目文档。这份文档既是SKILL的产出物也是验收测试的检查清单。我给它定位了两个特性可执行、可对照。可执行是说文档里的每个章节都能往具体的输入数据和功能列表上映射而不是一堆空话可对照是说文档生成之后我能拿着它逐条反查SKILL的框架层和细节层判断每一步是否按设计生效。验证分成三步来做。第一步准备一份“半残缺”的输入数据。我构造了一个测试项目的背景描述提供了一段项目目标文字一个包含5项功能的列表但其中2项功能故意不提供接口说明测试环境信息也只写了一半。为什么要故意残缺因为“框架细节”这套写法的真正优势只有在异常情况下才显现得出来。如果在标准输入下测试所有技能看起来都差不多只有塞入缺失信息、模糊信息和冲突信息才能验证细节层里的异常分支是否真的被执行了。第二步按框架层的工作流逐步执行。我先让模型解析输入数据然后锁定8个章节结构再逐章节生成内容。每个章节生成后我都对照输出细节表做一次检查。第一次跑下来发现两个问题一是缺失接口说明的那两个功能模型在测试范围章节里完全没提二是环境章节里模型果然试图自行补全一个“推荐配置”。这两个问题都在细节层的异常规则里被设计为“应追问”或者“应标注待补充”但实际并没有触发。问题出在我把检查动作放在“逐章节生成之后”而模型在单次生成时不会主动去翻异常表。修正方式是将异常检查动作提前到“解析输入”完成时执行一次然后每生成一个章节再检查一次。第三步用三个维度做最终验收。第一是功能性检查生成的文档是否覆盖全部5个功能点每条用例是否有预期结果第二是边界性检查遇到残缺输入时是否按细节表的要求追问或标注而不是自由发挥第三是自洽性检查文档内部前后引用是否一致比如环境章节的版本号和用例章节里的版本号是否对齐。三轮检查下来文档最终达到可评审状态整个验证过程一共迭代了3次。验证完成后我还做了一件以前忽略的事保留最终版本的输出样例。以前写SKILL总觉得“抽象规则写清楚就够了”模型应该能理解。实际上对模型来说一份具体、完整的输出样例比十条抽象规范更有效。样例一放模型对“什么是合格的交付物”就有了锚点生成质量的稳定性明显上升。5. 落地后的复盘四个值得展开说的坑验证通过不意味着万事大吉。在整个“框架细节”改造过程中我实际踩了四个坑每个都值得拿出来细说。第一个坑框架定得太粗细节直接失控。我第一版框架对输出协议只写了一句“输出一份完整的测试项目文档”没有锁定8章节结构。结果模型生成时自由发挥把风险分析写成了产品讨论把测试环境写出了方案建议书的味道。后来我把目录结构在框架层明确锁定这个问题立刻消失。经验是框架层宁可过度明确也不要留白太多。任何你觉得“模型应该懂的常识”在框架层补一句都不亏。第二个坑细节过细反而削弱模型能力。这句话听起来和上面的经验矛盾但实际两者并不冲突。有一版细节表我写得极其机械连每个章节的字数、段落顺序、标题层级都想控制。结果模型生成的内容非常死板遇到特殊情况完全不会变通。后来我删掉了所有“版式类细节”只保留“决策类细节”模型在保持结构稳定的前提下重新拥有了应变能力。我的判断标准很简单如果一条细节删掉后输出格式会乱保留如果删掉后内容质量会变也保留如果只是影响排版美观果断删。第三个坑测试文档写得太晚。我一开始是先把框架和细节写完再动手写测试项目文档结果发现细节无处安放逻辑特别绕。第二次迭代时我调整了顺序先想清楚测试项目文档该长什么样再反推SKILL需要哪些细节来支撑这个产出。这就是典型的TDD思维——先写验收标准再写实现。效率提升非常明显推荐每一个想尝试“框架细节”的人从这条路径入手。第四个坑变更记录必须配齐。框架细节分层之后细节层的修改频率会远高于框架层这是个好现象但也带来跟踪难题。改过三版细节之后我自己都记不清某条规则是刻意设计还是拍脑袋。后来我在SKILL文档头部固定一个CHANGELOG小节记录日期、改动点、改动原因、影响范围、关联测试用例。这个动作看起来最没有技术含量却是后期维护里最有用的一环。6. 这次改造带给我的几个直接变化改造前后同一个SKILL的实际表现差异相当明显。我列几组对比数据全部来自我自己的实测记录。改造前编写一个测试项目文档的技能从输入到输出平均需要人为干预2到3次通常发生在“模型漏掉功能点”和“环境信息编造”两个环节。改造后同样的输入一次生成加一轮自检即可定稿。以前文档上线前我需要从头到尾人工读一遍现在只需要抽查重点章节因为异常情况会被细节层的追问机制提前暴露出来。这类改造带来的第二个变化是问题定位速度变快了。旧写法下如果生成质量出问题我得把整个提示词从头读一遍猜测是哪句话导致跑偏。现在直接查三层先查框架层是不是没定边界再查细节层是不是没给判定标准最后查测试样例是不是过期了。定位一个问题的平均时间从小时级压缩到了分钟级。第三个变化体现在迭代方式上。以前改技能总担心改一处坏全局现在框架层稳定后我可以在细节层放心大胆地增减规则改完用测试文档跑一遍对照检查结果判断改动是否成立。迭代周期从“不敢改”变成了“快速试错”。这三个变化叠加在一起让我第一次有了“SKILL也可以像代码一样被结构化维护”的实感。7. 下一步迭代计划与一个实操建议这次验证通过之后我已经把“框架细节”定为后续SKILL开发的标准写法。下一轮迭代有三个方向第一把框架层模板进一步抽象成项目内可复用的公共片段新技能起步时直接引用不需要每次白手起家第二把细节层的四张表拆分成独立子模块按任务类型组合使用比如写测试文档用一套写需求文档用另一套第三把这次构造的“半残缺输入验证法”扩展到更多场景覆盖多语言输出、多角色协作、跨系统引用等更复杂的情况。最后分享一个实操建议也是这次改造中最值钱的一条经验如果你也想尝试这种写法不要从零开始重写现有SKILL那样风险太大而且容易返工。正确的切入姿势是找一个你已经在用、但维护起来最头疼的SKILL先给它补一段能力边界和禁用场景再挑一个你自己都看不下去的高频失败点补一条输出细节。一次只改一处改完跑一遍测试文档观察两三轮效果再决定要不要继续。这个方法进度不算快但每一步都踩得实。只有等你自己验证过一轮你才会真的理解“框架细节”这几个字的分量。