说明本文讨论的是 Agent 里「技能」这一层新封装以及它和工具、提示词、工作流之间的划界判据属于 Agent 工程落地话题不涉及具体模型版本与价格。AI 领域版本迭代极快凡涉及版本号、价格、可用性请以你阅读时的官方页面为准。文中代码为结构示意请按自己的技术栈调整后再上生产。一、为什么工具和提示词之外又长出了技能这一层这两层各自的封装单位到 2026 年中Agent 的能力供给基本只有两样东西工具和提示词。工具是能力接口一个名字、一段参数约束、一个可调用的实现。它把系统能做什么暴露成一个入口一次调用办完一件事。模型决定调不调参数决定做什么返回值就是结果。工具不关心这件事在业务流程里排第几也不关心里面要不要分步。提示词是行为约束语气、格式、禁止事项、角色设定。它常驻上下文对所有请求生效改一句影响全部链路。它是静态的不描述步骤也不带资源。两者之间留了一块空白这件事怎么做这类程序性知识没有地方放。它比一次调用长——包含若干步骤比一句约束具体——每一步有自己的输入输出还常常要带文件模板、脚本、字段清单。空白被塞进提示词之后的代价这块内容过去没有专门的容器于是被塞进系统提示词把一套五步流程整段写成自然语言。代价不在字数在生效范围。系统提示词里的东西对所有请求生效而其中绝大多数请求根本走不到那套流程。为了百分之几的请求每次请求都要付出这份常驻开销还要承担它带来的干扰——模型可能把那段流程误当成当前任务的指引。另一种常见做法是塞进工具描述工具描述本来讲参数一旦开始讲流程调用方就得先读懂内部步骤才能正确传参。技能skill就是针对这块空白的封装把一类任务怎么做连同步骤说明、可执行脚本、模板与参考资料打成一个按需取用的单元。三种封装放在一起看封装层封装的东西生效范围加载方式变更影响面工具一次能力调用被选中时生效调用时进入上下文单点改参数影响调用方提示词行为约束与风格所有请求常驻上下文全局改一句影响全部链路技能一套做事流程加资源被选中时生效按需逐级展开单个任务类型但含脚本与文件命名之争没有意义。真正决定该封在哪一层的是复用单位一次调用、一条约束还是一套流程。工具像一个函数提示词像一份团队规范技能像一个带说明和脚本的小工具包。二、技能里装什么四类内容必要性各不同说明与适用条件。技能名、一句话用途、什么时候用、什么时候不要用、需要什么前置输入。这一段是索引会先于正文被模型看到也是技能能不能被选对的第一道闸。步骤编排。这件事分几步、每步的输入输出、步与步的依赖、出错该退回哪一步。这是技能的主体也是提示词装不下的部分。可执行脚本。确定性部分交给脚本格式转换、字段映射、批量校验、数值计算。凡是能用一段代码稳定做对的事不要再写成自然语言步骤让模型推理一遍——每推理一遍都是一次新的出错机会。模板与参考资料。输出模板、字段对照表、检查清单。它们是被读取的资源不是每一步都要进上下文的正文。把它们和步骤放同一层等于每次执行都把整个技能包读一遍。哪些不该放进去一次性流程。只做过一次、不会再复用的流程封进技能的唯一效果是给未来每个请求多一个候选。主观判据。写得更吸引人这类目标没有可判定的对错放进去只是把主观性固化成一个文件日后没人能验证它。凭据与密钥。技能包是被复制、分发、共享的东西凭据一旦进去就会跟着走而且没人会记得在哪一份副本里。模型选型与参数。技能不该绑死用哪个模型、用什么采样参数绑死之后既不能迁移也没法横向对比。全局行为约束。始终用简体中文回答这类对所有请求都成立的要求属于提示词不属于任务层。内容清单内容是否放进技能理由适用与不适用条件放决定它会不会被选中也是误加载的第一道闸多步流程与依赖关系放程序性知识的主体提示词装不下确定性脚本放能用代码稳定做对的事不该再交给推理输出模板、字段对照表放被读取的资源按需进上下文一次性步骤不放不是复用单元只会稀释索引主观判据不放没有可判定对错固化后无法验证凭据、密钥、内部地址不放技能会被复制分发凭据会跟着泄露全局行为约束不放属于提示词层不属于任务层⚠️ 代码待验证# 技能包的结构示意把步骤和资源分开资源只在需要时被读取name:report-consolidatedescription:把多份同口径日报合成一份周报。适用于输入已经是结构化日报、 只需按字段合并去重的场景。不适用于日报口径不一致或需要重新采集的情况。when_to_use:-输入是两份以上结构化日报-需要按同一业务字段合并when_not_to_use:-日报口径不一致先统一口径再来-需要重新采集数据steps:-id:normalizescript:scripts/normalize.py# 确定性部分交给脚本不写成自然语言-id:mergeneeds:normalizeinstruction:按业务字段合并重复项只保留最新一条-id:renderneeds:mergetemplate:templates/weekly.md# 模板作为资源按需读取resources:-templates/weekly.md-references/field_map.mdsecrets:[]# 凭据不进技能包由运行环境注入三、与工具的边界复用一次调用还是复用一套流程判据是复用单位不是复杂度一条能覆盖大多数情况的判据这个能力被复用的方式如果是被调用一次做成工具如果是每次都得按同样的步骤走一遍做成技能。工具内部可以很复杂几十上百行逻辑都正常但它对外只有一个入口和一组参数调用方不需要知道里面分几步。技能对外是一套流程加若干资源调用方也就是模型必须看懂步骤才能执行。两个方向的误封把流程封成一个工具。症状是工具的参数里出现了步骤“模式”阶段这类枚举调用方必须先知道内部流程才能正确传参。这时工具已经从能力接口退化成了流程入口流程每调整一次参数就变一次所有调用方跟着改。一旦发现参数里有这类枚举先把流程拆出来单独放。把纯函数封成技能。症状是技能内容只有一句话说明加一个脚本中间没有任何判断和编排。这种情况下直接做成工具更省技能多出来的索引、加载、资源管理换不到任何东西还多出一份需要维护的描述。工具与技能的判据判据做成工具做成技能复用单位一次调用一套流程对外接口名字加参数约束名字加说明加资源步间是否要按结果分支不需要对调用方暴露需要且分支由条件决定是否携带文件不携带常带模板、脚本、清单变更的传播面改参数要通知调用方改步骤对调用方基本透明典型反例参数里出现步骤或模式枚举只有一个脚本、没有任何编排⚠️ 代码待验证defchoose_wrapping(need:dict)-str:# 只回答一个问题这个东西的复用单位是什么ifneed.get(carries_files)orneed.get(branching_between_steps):returnskill# 带资源或步骤之间要按结果分支ifneed.get(params_include_step_or_mode):# 参数里出现步骤/模式说明流程漏到了接口上先拆开再看returnneeds_splitifneed.get(done_in_one_call):returntool# 一次调用办完一件事工具就够了returnneeds_split四、与提示词、工作流的边界三种东西管的时间尺度不同提示词管每一次请求它常驻上下文约束所有请求的行为时间尺度是整个会话。工作流管一次执行它决定这次任务里谁先谁后、哪一步失败怎么走、失败退回哪里。它是运行时装配出来的执行计划顺序和分支依赖这一次的输入。技能管一类任务它把反复出现的一类流程固化下来被选中时才展开。它的时间尺度跨请求但只覆盖这一类。一句话概括提示词是常量工作流是这一次的执行计划技能是可复用的流程库。互相渗透到哪一步就该拆开技能里写死顺序就长成了工作流。如果技能把先做甲、再做乙、最后做丙写成不可变的硬顺序而每次任务的条件其实不同这个技能很快就要加条件分支加到第三、四层分支它就只是一份装在技能目录里、没写好的工作流。正解是把顺序由条件决定交回运行时技能只描述每步的前置条件先后由工作流决定。工作流里塞说明就长成了技能。如果编排配置里出现大段操作说明、模板引用、参考资料说明这个工作流实际在履行任务层的职责。把内容抽成技能工作流只留一个调用点。提示词里写流程是最常见的一种也最隐蔽它在早期确实能用只是随着流程变多变细开始对无关请求产生干扰而这时已经没人敢删了。三者各自的位置维度提示词工作流技能时间尺度每次请求这一次执行一类任务是否常驻上下文常驻不常驻按需逐级展开谁决定它生效全部请求运行时编排被选中典型内容语气、格式、禁止事项步骤顺序、分支、失败走向步骤说明、脚本、模板改动后的重测范围全局单条链路单个任务类型越界症状写了具体流程塞了大段说明写死不可变顺序⚠️ 代码待验证# 划界的顺序判断从上往下问第一个命中就是答案 1. 这条内容对所有请求都成立吗 - 是提示词 2. 这条内容每次执行都一样、且与本次输入无关吗- 是技能里的说明或资源 3. 这条内容的顺序依赖本次输入吗 - 是工作流 4. 这条内容能用一段脚本稳定做对吗 - 是技能里的脚本 5. 以上都不成立 - 先别封把判据写清再来第 5 条不是兜底话术。判断不出该封在哪一层通常意味着这件事的判据本身还没想清此时封装只是把不确定性挪了个位置。五、加载与上下文占用渐进披露是三级不是一次性全给技能通常按**渐进披露progressive disclosure**的方式加载模型先只看到技能名和一句话说明判断要用时才把说明正文展开只有真正执行到某一步才去读脚本和模板。三级之间的上下文代价差一个量级。级别模型看到什么上下文代价什么时候进入一级索引名字加一句话用途每个技能几十字会话建立时二级说明步骤、适用条件、边界数百到上千字判定要使用时三级资源脚本、模板、参考清单按实际读取量执行到该步时一级的代价是整个机制的关键技能数量乘以每个几十字就是常驻开销。技能库到几十个之后索引这一段写不精开销就跟着涨而它是每个请求都要付的。这里有一个容易被忽略的工程判断不是所有步骤都值得二级展开。一个技能里十步本次只走到第三步剩下的说明可以留在三级。展开粒度做细收益比压缩索引文字更大。此条在实践中的置信度中等——它依赖运行时能否按步读取资源不具备这个条件的实现只能整体展开。误加载的代价高于漏加载该加载没加载任务按普通对话做完了结果质量差但问题显式可见——用户会看出来或者下游校验会拦下。不该加载却加载了技能正文进了上下文模型按技能里的步骤做了本不该做的事。多花的上下文是小的真正的代价是技能里的步骤改变了任务的做法而这个改变没有对应的判据去发现它。所以一级描述要写成过滤器不是广告。两条写法上的要求一句什么时候用一句什么时候不要用。缺了第二句选择逻辑只剩相关性匹配。写任务特征不写能力形容词。前者能被触发条件匹配上后者只能匹配到感觉。对照着看合并多份同口径日报按业务字段去重是可匹配的强大的报告生成能力匹配不到任何东西。命名也是接口技能名是模型选择时的唯一标识规则是动词开头加对象不要用抽象名词。report-consolidate比report-tool有用后者不说做什么。另外不要用同义词区分两个技能summarize-doc和doc-summary同时存在时模型分不出来你排查选中率时也分不出来。⚠️ 代码待验证{skill:report-consolidate,index_line:{name:report-consolidate,use_when:输入是两份以上同口径的结构化日报,do_not_use_when:日报口径不一致或需要重新采集数据,cost_hint:二级展开约数百字},expansion:{level:2,loaded_steps:[normalize,merge],skipped_steps:[render],reason:本次只需中间数据不需要渲染模板}}index_line里三项缺一不可use_when决定召回do_not_use_when决定精度cost_hint让上层知道展开一次的代价。少了第三项上下文预算就只能事后拍脑袋。完整版资料清单本文用到的技能描述写法对照表与加载成本记录都整理在里面了扫码即可获取六、版本、分发与信任说明和脚本要一起进版本技能是自然语言说明和可执行脚本的混合体。这意味着版本号要同时覆盖两类内容改说明会改变模型行为改脚本会改变执行结果两者都不是文档更新。一条可用的规则说明和脚本一起进版本任一处改动就升版本号不要在记录里出现说明是 v2、脚本还是 v1这种状态——真到排查的时候没人说得清当时生效的是哪一份。第三方技能等于引入一个外部脚本这一点必须写进规范里技能包里的脚本会在你的运行环境里执行。它的风险类别和引入一个第三方依赖相同但少了两层兜底——第三方技能没有包管理器那样的签名校验与版本解析体系也没有漏洞通告渠道。所以来源要显式记录从哪来、什么时候引入、引的是哪一版写进仓库里的引入清单。版本要钉死不用浮动引用升级是一次显式动作不是自动跟随。权限要显式收技能声明的文件访问范围、网络出口、需要的环境变量逐项过一遍能删的删。先影子跑第三方技能先只记录选中与执行结果不直接进关键路径。信任分级来源版本策略权限范围适用位置自己写、自己维护随仓库走版本按需最小化核心流程允许改运行环境内部团队共享固定版本加引入记录限制到工作目录跨团队复用第三方公开分发固定版本加来源留痕只给只读与受限出口先影子跑不进关键路径权限不该由技能自己声明了算技能说明里写一句这个技能不会删文件是没有强制力的——说明是给模型看的不是给运行时看的。权限必须在运行环境这一层收技能只负责报告它需要什么由环境决定给不给。⚠️ 代码待验证# 引入技能时的固定与留痕示意用具体命令按你的包管理方式调整# 1) 钉到具体版本不用浮动引用skilladdreport-consolidate--version1.4.2--sourceyour-registry# 2) 把来源与引入时间写进仓库内的引入清单skill lock--writeskill.lock# 3) 升级是一次显式动作先在影子模式下跑skill upgrade report-consolidate--to1.5.0 --dry-run第一行的版本号固定住的是说明加脚本这个整体不是只钉脚本第三行的--dry-run之后要接的是观测数据不是直接替换。七、什么不该封成技能以及观测与落地顺序四类不该封的场景一次性任务。只做一次的事情封成技能唯一效果是给未来的请求多一个干扰项。判据主观的任务。对错由人定的任务——措辞、命名、风格——封成技能后你能改的只有说明文字而说明文字改不出对错判据。单次查询类任务。查一条记录、拉一个状态、重算一个数工具就是它的正确封装。技能多出来的编排层换不到任何东西。下游已有强制校验的任务。下游是编译器、类型系统、字段校验这类会硬报错的环境时把校验步骤写进技能是重复劳动还把一份会过期的规则复制到了两个地方。先看有没有被选中再看有没有起效技能上线后有两个数要分开看选中率该用技能的任务里实际选中它的比例。偏低说明一级描述不够可匹配或者命名有歧义。误选中率不该用技能的任务里选中了它的比例。偏高说明缺do_not_use_when。这两个数之后才是起效比选中并执行之后结果是否真的比不用技能时好。它最难拿因为需要用和不用的对照而对照要额外花一次执行。技能失效的典型样子不是报错而是静默不生效技能一直在库里模型就是不选它链路退化成普通对话而结果看起来也还行。这种情况不产生任何异常信号只能靠选中率发现——这也是为什么选中率要单独统计不能等它混进整体成功率里。落地顺序到 2026 年中比较稳的顺序是这样先把说明写全名称、用途、适用条件、不适用条件四件齐全再动手封第二个技能。先封确定性最强的步骤固定、判据明确、脚本占比高的任务先封主观任务往后排。先进影子技能被选中但结果不落地只记录选中率与起效比跑够一段时间再决定是否接入。权限在运行环境收这一步和技能上线并行做不要等出了问题再补。技能库到几十个时回头重写索引这时候一级描述的常驻开销开始明显值得重新过一遍。⚠️ 代码待验证{trace_id:req-0001,skill_selection:{candidates:[report-consolidate,doc-extract],selected:report-consolidate,selection_basis:index_line,should_have_selected:report-consolidate,false_positive:false,expansion_level:2,index_cjk_cost:42,expanded_cjk_cost:860,outcome_better_than_baseline:null,mode:shadow}}should_have_selected和false_positive是这套记录的核心没有它们选中率只是一个没有分母的分子。outcome_better_than_baseline先留空等对照跑出来再填——留空比填一个估出来的值有用。完整版资料清单本文用到的观测字段定义与技能落地顺序清单都整理在里面了扫码即可获取附表 A关键取舍一览工程取舍原因依据章节封装层次的划分依据是复用单位不是命名命名之争不影响实现复用单位决定接口形态第一章程序性知识要从提示词里搬出来提示词全局生效为少数请求付全量开销第一章说明里必须写什么时候不要用缺这一句选择逻辑只剩相关性匹配第二章确定性部分写成脚本不写成步骤能让代码稳定做对的事不该再推理一遍第二章凭据不进技能包技能会被复制分发凭据会跟着走第二章参数里出现步骤枚举时先拆分说明流程漏到了接口上流程一改调用方全改第三章只有一个脚本的技能改回工具多出的索引与资源管理换不到任何东西第三章顺序由条件决定时交给工作流技能写死顺序最后会长成一份难维护的工作流第四章工作流里的大段说明抽回技能编排层承担任务层职责两边都改不动第四章索引写任务特征不写能力形容词能力形容词只能匹配到感觉匹配不到触发条件第五章误加载的代价高于漏加载漏加载显式可见误加载会静默改变任务做法第五章说明与脚本一起进版本否则说不清当时生效的是哪一份第六章权限在运行环境收不写进技能说明说明是给模型看的没有强制力第六章第三方技能先影子跑再进关键路径等同引入外部脚本且没有社区审查兜底第六章静默不生效只能靠选中率发现它不报错结果看起来也还行第七章附表 B术语速查表术语含义技能skill把一类任务的步骤、脚本、模板与参考资料打成包的按需加载单元工具tool一次能力调用对外是名字加参数约束提示词prompt常驻上下文的行为约束对所有请求生效工作流workflow运行时装配的一次执行计划决定步骤顺序与失败走向程序性知识procedural knowledge一件事怎么做含步骤、依赖与判据比一次调用长渐进披露progressive disclosure先只暴露索引用到时才逐级展开说明与资源索引index line技能名加一句话用途会话建立时进入上下文误加载不该用技能的任务选中了技能静默改变了任务做法选中率该用技能的任务里实际选中它的比例误选中率不该用技能的任务里选中它的比例起效比选中并执行后结果好于不用技能的比例需对照才能得到静默不生效技能存在但未被选中链路退化为普通对话且无异常信号信任分级按来源给技能分配版本策略与权限范围影子模式shadow mode技能被选中但结果不落地只记录观测数据写在最后这篇用到的资料写这篇文章时我把技能包的几种封装形态、加载策略与观测口径都过了一遍顺手整理成几份配套的东西大模型学习路线图从 LLM 基础到 Agent 开发各阶段该学什么、用什么资料大模型全套教程按主题分好的视频与文档清单大模型实战好书24 本附每本适合的阶段资料是我自己整理的放在下面这个码上扫码即可获取添加时备注「大模型」优先通过。拿到之后建议先看学习路线图那一份先定位自己在哪个阶段再决定学什么比一上来就啃框架效率高得多。