智能体技能：把重复任务封装成可发现、可验证、可治理的能力包

智能体技能的收益来自复用：反复加载同一套规范、执行同样的安全步骤、产出同类的制品。正因为收益建立在“重复”之上，一次性的开放探索不适合先写成技能。这类任务的目标在不断变化，又无法事先定义通过条件，如果过早把它固化，封装起来的只会是还没被验证的错误假设。

因此，判断一个任务是否值得封装，看的是它是否同时满足两个条件：一是足够重复，二是能够验收。重复意味着同一类任务会再次出现，值得为它沉淀稳定的触发方式、执行步骤和资源清单；可验收意味着存在一个稳定的通过标准，能够判断一次执行到底做没做对。只有满足这两个条件的任务，封装后的技能才真正可执行、可验证、可回退，而不是一段只能看不能用的文字。

封装智能体技能的过程，就是把一类重复任务的触发、步骤、资源和验收组合成一个版本化能力包。它的输入是多次真实的任务轨迹，加上从中提炼出的稳定通过条件；它的输出是一个可发现、可执行、可回退的复用制品。这里的输入不是凭空想象的任务描述，而是已经跑过多次的真实成功与失败记录——只有从这些轨迹里提炼出的稳定部分，才值得写进技能。

反过来，如果任务的目标持续变化，或者始终无法定义“什么算通过”，那么技能就不该承担这份工作。此时强行封装只会固化错误假设，让后续每次复用都在重复同一个错误。正确的做法是保留通用 Agent 的回退路径：让通用 Agent 在开放探索中继续寻找稳定的做法，等到某个模式被反复验证、通过条件能够稳定定义之后，再把它提炼成技能。技能的边界就在这里——它负责把已经验证的、可验收的重复工作固化下来，而不是替探索性的工作提前下结论。

提示、工具、技能、工作流都能“告诉 Agent 怎么做”，但它们回答的问题不同，承担的职责也不同。把四者混为一谈是初学者最常见的错误，而它们的差别可以从“回答什么、产出什么、典型内容是什么”三方面看清楚。

提示回答的是“这一轮怎样回答”。它作用于单次交互，典型内容是具体的指令与示例，目的是指导本轮表达。

工具回答的是“能执行什么动作”。它的典型内容是 schema 与执行器，作用是提供可以被调用、被验证的动作能力。

技能回答的是“某类任务怎样完成”。它的典型内容覆盖触发、流程、资源与验收，作用是把一整类重复任务组织成一个可复用的能力包。

工作流回答的是“系统状态怎样持久流转”。它的典型内容是节点、分支、重试与补偿，作用是持久地编排系统状态的变化。

这四者可以组合，但不能互相替代。一个技能可以调用工具，也可以挂接某个工作流，但技能本身并不授予任何权限，也不能替执行器保证副作用是安全的。换句话说，技能描述的是“应该怎样执行”的方法，而权限的授予发生在工具和执行器那一层，现实世界副作用的最终安全责任也落在执行器上，而不是落在技能的文字描述上。

从层级辨析的角度看，这个过程接收一个 Agent 制品及其应承担的责任，输出它属于提示、工具、技能还是工作流的分类。分类的关键不是看文字长短，而是看它回答的问题：只影响单轮表达的是提示，提供可调用动作的是工具，组织一整类任务的是技能，编排状态流转的是工作流。理解这一层区别，才能在设计时把每类职责放到正确的层，避免让技能承担它根本承担不了的权限和安全责任。

只写一份 README 的技能难以稳定复用，因为它把适用边界、输入输出、操作步骤、参考资源和治理规则全部堆在一起，无法在需要的时候精确取用。一个能被反复执行并验收的技能包，至少应当具备六类契约，各自回答不同的问题。

第一类是描述，说明技能的适用与不适用条件，以及用户可见的能力边界。它回答“这个技能什么时候该用、什么时候不该用”。

第二类是输入与输出，明确字段、文件、schema 与示例。它回答“数据以什么形态进入、以什么形态离开”，让调用方和执行方对数据契约有同一份理解。

第三类是步骤，按依赖关系排序，并标注关键判断与停止条件。它回答“按什么顺序做、每一步在什么条件下停下”，避免执行者在中间态自行发挥。

第四类是资源，也就是按需读取的参考、模板和资产。它回答“还有哪些材料可以在需要时取用”，而不是被无条件地全部加载。

第五类是脚本，承担确定性计算、转换与验证。它回答“哪些计算必须由代码而非自然语言完成”，把结果可复现的工作交给可执行逻辑。

第六类是治理，记录版本、依赖、权限、负责人和回退方式。它回答“这个技能由谁负责、依赖什么、出问题时怎么退回去”。

六类契约的读取方式并不相同。入口说明必须完整读取，因为触发条件、数据契约和执行步骤决定了后续一切；扩展资源则应随着任务进展逐步加载，避免把整套文档永久塞进上下文。这样既保证执行时信息充分，又不会让上下文被一次性撑满。

技能包结构的整体过程是：输入适用任务、数据契约、操作步骤、参考资源、脚本和治理信息，输出能够独立执行与验收的六类契约。入口完整读取、扩展资料按需加载、确定性工作交给脚本，这三点共同保证了复用的稳定。需要警惕的是，六类齐全只表示责任可以被追踪，并不表示其中的脚本、模板或规则永远正确；当依赖发生变化时，仍然必须做回归验证，否则技能会带着过期假设继续被执行。

散落的写作提示、计算脚本和品牌模板各自有用，却难以形成稳定可靠的能力。把它们封装成一个“生成并验收月度 PDF 报告”的技能，就能看清六类契约如何在实际任务里落到具体对象上。

这个技能的触发条件写得非常明确：输入是已核验的 CSV 和报告日期，外加品牌规则。技能不负责数据清洗，也不负责事实补全——那些缺失的、未经验证的内容不在它的职责范围内，而是上游的工作。

执行时的分工是分层的。入口读取字段字典与品牌规则，据此选择对应的模板。脚本负责计算汇总数字，并输出一份机器可读的中间 JSON；模型只负责解释趋势，不做数字计算。生成文档之后，再调用渲染脚本检查页数、溢出、字体和表格，把版式问题挡在交付之前。

验收闭环是这套技能区别于“请写一份漂亮报告”的关键。每个数字都要逐项回连到中间 JSON，每条引用都要回连到输入行；只要有一处回连失败，就停止而不交付。最终输出包含 PDF、校验报告、技能/模板/脚本的完整版本，以及尚未解决的警告。

这样做的价值在于，多出来的不是文字量，而是三样东西：清晰的输入边界、确定性的计算、可验证的验收闭环。整体来看，这个案例的输入是已核验 CSV、报告日期和品牌规则，输出是 PDF、校验报告、完整版本信息和未解决警告；它解决的是散落提示、脚本和品牌模板如何形成可靠能力的问题。系统用脚本算数字、模型解释趋势、渲染器检查版面，再把数字和引用回连输入，从而做到“通过”二字有据可依。需要强调的是，“通过”只表示本次制品满足声明的内容与版式验收，并不负责清洗缺失数据，也不负责凭空补全事实——这两件事始终属于上游和输入数据的责任。

“选择准确率 90%”听起来很好，但放在低基率场景里仍可能频繁打扰用户。技能选择本质上是一个分类问题，而分类问题的表现必须同时看两个比例，不能只看一个。

设想 100 个请求里只有 20 个真正需要技能 S。选择器召回了 18 个正确请求，召回率达到 18/20 = 90%。但与此同时它误触发了 16 个普通请求。这时精确率只有 18/(18+16) = 52.9%。也就是说，近一半的触发是错的。

这里的两条公式对应两个不同的问题。精确率（Precision）等于真阳性除以真阳性加假阳性，回答的是“在触发了技能的请求里，有多少真的该触发”。召回率（Recall）等于真阳性除以真阳性加假阴性，回答的是“在真正需要技能的请求里，有多少被找回来了”。其中 TP 是正确触发技能的请求数，FP 是不需要技能却误触发的请求数，FN 是需要技能却未触发的请求数。

低基率是让高召回显得危险的根源。当真正需要技能的请求占比很低时，描述之间的重叠会让误触发大量涌入，即便召回率很高，精确率依然会被拉低。这正是“90% 召回”仍频繁打扰用户的原因：触发的总量被假阳性撑大了。

因此，技能选择的过程接收请求与技能描述，输出的是三者之一：选中某个技能、需要澄清、或者无技能。为相邻技能准备对比反例、允许“无技能”这个选项，都能帮助分类器在有把握之前不轻易下结论。对于副作用较高的技能，宁可先澄清，也不能为了追求高召回而牺牲精确率——错误的触发可能带来不可逆的现实后果。这些比例都依赖请求的基率，所以在高风险、低基率的场景里，首要目标是减少误触发，而不是把召回率推满。

把所有技能的全文都放进系统提示，会同时让系统变慢又变差。原因在于上下文是有限的竞争资源：全文堆进去后，每个技能都在争夺注意力和位置，真正需要的信息被稀释，处理速度也被拖慢。渐进披露正是为了解决这个问题而设计的分阶段加载方式。

整个过程可以画成一条从发现到验收的路径：请求先匹配轻量的技能描述，选定之后才加载完整的技能入口，再按需读取参考、脚本和资产，最后在受限条件下执行并验收制品。这条路径把“发现的成本”和“执行所需的知识”分开了——发现阶段只需要轻量的描述，执行阶段才需要完整材料。

从输入输出的角度看，渐进披露接收任务和一份轻量描述目录，输出的是所选技能的入口，以及在执行过程中按需加载的参考、脚本和资产。发现阶段只比较各技能的适用边界，谁的描述匹配当前任务，谁才进入下一阶段；选中之后才完整读取该技能的入口，随后加载执行所必需的资源，最终完成验收。

这样做的收益是降低上下文竞争，让每一份材料只在其真正需要的时刻进入上下文。但这并不意味着那些未加载的材料没有用，也不意味着可以随便压缩。入口承载着关键的约束，如果入口里遗漏了这些约束，后续执行就会失真——因为执行者从来没有见过它需要遵守的规则。渐进披露优化的是“何时加载”，而不是“能否丢弃”。

把计算交给脚本之后，技能并不会自动变得可靠。脚本确实擅长精确、可重复的操作——解析、计算、格式转换和验证都应当优先交给脚本，而不是交给模型靠自然语言硬算。但脚本要真正可用，必须像产品代码一样受到治理。

一个合格的确定性脚本，输入应当是经过 schema 校验的数据，输出是可重复的计算、转换或验证结果，外加明确的错误码。它的作用是解决模型不擅长精确重复操作的问题，同时用几类约束把副作用控制住：输入 schema、错误码、幂等、超时、沙箱和测试。这几项共同保证脚本在同样的条件下给出稳定的行为，且失败可以被识别和处理。

在副作用和权限上，脚本默认应当是只读的。任何写操作都要先展示差异并请求批准，路径、网络和凭证的范围都要最小化。脚本不能用自己的输出去掩盖源数据的问题，也不能把秘密写进日志——这两条看似是工程细节，实则是安全边界：掩盖源数据会让错误被美化后继续流转，日志泄密则会把凭证扩散出去。

需要注意“确定性”这个词的边界。确定性只表示在相同条件下行为稳定，它并不表示代码是安全的、输入是可信的、或者写操作已经获得了批准。稳定地重复一个错误的计算，仍然是一个错误的计算。因此，确定性脚本解决的问题是“可重复性”，而安全性、输入可信度和写操作授权，仍然要靠 schema、沙箱、测试和批准流程各自去保证。

只改一份参考文档，也可能改变整个技能的行为，因为技能的组成部分之间是互相依赖的。入口、资源、模板、脚本、依赖和运行环境，任何一处发生变化，都可能通过连锁反应改变最终执行结果。所以版本治理必须同时锁住这些对象，而不是只给入口一个版本号。

技能版本清单要记录的内容包括：入口、所有被引用的资源、模板、脚本、依赖，以及兼容的模型与运行时。发布时产出不可变的版本，并保留迁移说明，让使用旧版本的人知道新版本改了什么、怎么迁移。运行时则要记录解析后完整的版本集合，也就是这一次执行实际用到了哪些版本，这样事后才能解释“当时为什么会得到这个结果”。

外部链接不能当作稳定依赖。链接指向的内容随时可能变化，正确做法是快照它、校验哈希，或者在链接不可用时明确失败，而不是静默地换一份内容继续执行。

更新触发的是回归。任何引用发生变化，都应当触发一次回归验证；高风险更新更要先回放历史任务，比较选择、工具轨迹、制品和权限是否发生了不该有的偏离。这样能在发布前发现变化带来的副作用。

整体来看，版本治理的输入是入口、资源、模板、脚本、依赖和运行环境，输出是不可变的技能版本，以及一套可重放的完整版本集合。版本锁定的价值在于支持解释旧结果，但它无法阻止外部服务自身的变化；当链接失效时，系统必须明确失败，而不能悄悄替换内容。前者是可控的内部治理，后者是必须诚实面对的外部边界。

端到端失败时，最需要回答的问题是：到底是在“选技能”这一层错了，还是在“执行任务”这一层错了。一个笼统的端到端分数无法区分误触发和执行错误，所以评测必须拆成两层，各自用各自的指标。

选择层衡量的是技能有没有被选对。测试集要包含正例、近邻反例和无技能请求，评测的指标是精确率、召回率、澄清率和错配成本。精确率与召回率回答“触发得准不准、该触发的有没有找回”，澄清率回答“系统是否在不确定时及时停下来询问”，错配成本则回答“一次误触发带来多大的代价”。

执行层衡量的是技能在确认选对之后，任务本身有没有做对。评测指标包括任务是否成功、步骤是否遵循、脚本是否通过、制品质量是否达标、是否发生权限违规、token 与时间的节省情况，以及需要多少次人工纠正。这些指标只有在“选择正确”这个前提成立时才有意义，否则执行再漂亮也是在执行一个错误的技能。

两层评测的输入是请求集、近邻反例、确认选对的任务和旧版本基线，输出是选择指标与执行指标。先判断是否选对技能，再判断步骤、脚本、制品和权限是否通过，就能把失败精确地定位到某一层。

此外，评测还要有参照系和切片。要拿通用 Agent、仅提示的做法和旧技能版本做比较，看新技能到底带来了什么增量；还要按输入缺失、环境变化和异常数据做切片，看技能在不同条件下的表现。漂亮示例不能代替失败分布——几个成功案例说明不了系统在异常输入上的真实表现。总体端到端分数不能区分误触发与执行错误，同样，漂亮成功示例也不能代表异常输入的分布。

两个技能功能重叠时继续共存，会让选择变得越来越混乱，也会让风险成倍累积。技能目录如果只增不减，过时的、重叠的技能会持续争夺选择器的注意力，误导分类，增加误触发。因此技能需要完整的生命周期管理，而不仅仅是创建和发布。

生命周期管理的第一步是定期审计。目录要定期检查每个技能的所有者、使用率、失败情况、依赖和权限状态。这些信息决定了每个技能接下来该保留、合并、弃用、立即禁用还是回退。

处理方式分几种。功能重叠的技能应当合并，把重叠的描述合并成一份更清晰的边界。需要弃用的技能，弃用前必须给出替代方案和明确的期限，让还在使用它的人有时间迁移。对于高风险漏洞，则应当立即禁用，并回退到通用流程，不等常规的弃用周期走完。

删除一个技能时，它的版本与历史运行证据仍然要保留。这样做的目的只有一个：保证旧产物可以被解释。过去某个产物是哪个版本的技能生成的、当时执行了什么，这些记录不能随着技能删除而消失。但要区分清楚：保留历史只用于解释旧产物，绝不表示旧技能仍然可以被触发。

整体来看，技能生命周期管理的输入是目录中每个技能的所有者、使用率、失败、依赖和权限状态，输出是保留、合并、弃用、立即禁用或回退的决定。它解决的是重叠和过时技能持续增加选择混淆与风险的问题。其中有一条优先级是固定的：高风险漏洞要优先停止使用，其次才是常规的合并与弃用流程。

当一个请求同时命中多个技能时，比如“把 Excel 数据做成 PDF 汇报”既符合表格技能、又符合文档技能，就不能靠任意选择一个来解决，必须显式地消歧或组合。

选择器先按硬条件过滤，输入类型、输出制品和权限不匹配的技能直接排除；然后再按描述相关度排序。如果过滤之后仍有两个技能，就要进一步判断它们的关系：是目标重叠的竞争关系，还是前后阶段的互补关系。

对于目标重叠的技能，应当选择更具体、且版本受支持的那个，并用近邻反例来验证选择没有偏到错误的一方。对于前后阶段互补的技能，管理者可以按它们声明的输入输出来组合，把它们串联起来，而不是任选一个。组合的关键在于，必须有一个唯一所有者和一份中间制品 schema，用来定义两个技能之间交接的数据契约——否则两个技能可能各自按自己的理解去解释中间产物。

最危险的情况是两个技能同时写同一个资源。此时必须禁止并发，或者指定唯一所有者，用 diff 和锁来保证不会出现两个技能同时编辑同一份文件的局面。

为了实现这些判断，技能需要在声明里写清 conflicts_with、requires 和可组合接口，把冲突关系和组合约束显式暴露出来。遇到高风险冲突，或者两个候选的置信度差距很小时，应当向用户澄清；不要因为某个技能先被加载、恰好处在上下文里靠前的位置，就给它隐式的优先权——加载顺序不应当成为决定权限的依据。

整体来看，冲突解析的输入是多个候选技能的输入输出、权限、依赖和冲突声明，输出是单一选择、按 schema 组合、澄清或无技能回退四者之一。先用硬条件过滤，再判断重叠还是互补，并为共同资源指定唯一所有者。组合成功只表示接口能够衔接，它绝不意味着允许两个技能并发写同一资源，也不意味着加载顺序可以决定权限。

把整条因果链连起来看，智能体技能是从一个具体问题出发，逐步收敛到可验证实践的过程，每一步都建立在前一步之上。

起点是识别重复且可验收的任务。只有这类任务才值得封装，因为技能的全部收益来自复用，而无法验收的任务只会固化错误假设。这一步决定了后续所有工作是否有意义。

识别出任务后，从多次真实的成功与失败轨迹中提炼稳定步骤。稳定步骤不是凭空设计出来的，而是从已经跑过的历史里沉淀下来的，只有经过验证的做法才值得写进技能。

有了稳定步骤，接下来写清适用与不适用条件，以及输入输出契约。这一步把技能的边界固定下来，让调用方和执行方对“什么时候用、数据怎么进怎么出”有同一份理解。

然后把确定性的工作放进受限脚本。解析、计算、格式转换和验证这些可重复的操作交给代码，并用 schema、沙箱、超时、幂等和测试约束它的副作用。

参考与资产按需组织，不一次性塞进上下文。入口完整读取，扩展资源在执行过程中逐步加载，让上下文竞争降到最低。

技能成型后，评测要分两层：先看技能是否选对，再看技能是否做对任务。选择层看精确率、召回率、澄清率和错配成本，执行层看任务成功、步骤遵循、脚本通过、制品质量和权限违规。

发布前锁定完整依赖，并灰度发布。入口、资源、模板、脚本、依赖和运行环境全部纳入版本锁定，高风险更新先回放历史轨迹，逐步放量而不是一次性全量切换。

上线后持续监控、升级、合并或下线。目录定期审计，功能重叠的合并，过时的弃用并给出替代与期限，高风险漏洞立即禁用回退，删除时仍保留历史版本与运行证据以解释旧产物。

这条链从“值不值得封装”的判断开始，经过提炼、契约化、脚本化、按需加载、分层评测、版本锁定和灰度发布，最后进入持续治理。每一环都在回答同一个问题：如何让一类重复任务，成为可发现、可执行、可验证、可回退的能力包。