2026/9/9 7:11:25
FEATURED · 精选文章 
1. 长 Prompt 不是 Skill别再混淆了先说个我最近遇到的真实场景有位朋友兴致勃勃地丢给我一份“精心打磨”了快半个月的 Prompt说这是他团队最新封装的 Skill希望我帮忙看看能不能“提效”。我打开文档屏幕上密密麻麻全是约束条件、否定式指令、 few-shot 示例洋洋洒洒上千行。我问他“这个 Skill 里面的工具定义长什么样模型怎么决定什么时候调用外部 API失败重试策略是什么”他愣住了反问“什么工具定义我这是纯文本 Prompt不是应该所有大模型都能直接用吗”这个片段基本代表了当下 AI Agent 落地过程中最大的误解把“长 Prompt”当成“Skill”。很多人觉得 Prompt 写得足够长、足够细、足够“没漏洞”就相当于给模型封装了一项技能。但从工程视角看这完全是两码事。长 Prompt 是给模型的一段“说明文字”而 Skill 是一个可复用、可校验、可组合、可升级的系统单元。我在多个实际项目里踩过这个坑后来把 Skill 的整套构建方法整理成了一套可复制的 SOP今天这篇文章就把它完整拆开。如果你正在做 AI Agent、Codex 插件、Claude 插件或者其他工具型 AI 应用这篇文章应该能帮你省下几周时间。先说结论长 Prompt 解决的是“让模型听懂”Skill 解决的是“让模型会做”。前者是输入后者是能力封装。把输入当能力等于把字典当成写作才华字都在那儿但不代表能写出好文章。2. Skill 的本质一套可封装、可验证的执行单元2.1 Skill 与 Prompt、Agent 的边界在哪里要搞清楚 Skill先得给它画一条清晰的分界线。Prompt、Skill、Agent 这三个概念在中文技术社区里经常被混着用但它们在工程上的定位完全不同。Prompt 是一段自然语言指令本质是“上下文输入”。它的特点是不可校验、不可复用换个模型效果就是另一回事、不可组合。你可以把 Prompt 想象成给临时工写的一份工作说明——今天这个人干完明天换个人来又得重新講一遍。而且你没法保证临时工一定会照着做。Skill技能是模型或 Agent可持续调用的一组能力封装通常由三部分构成能力描述什么场景下用、执行逻辑怎么做、按什么步骤、必要的外部资源工具定义、API Schema、知识库索引、示例库。它有自己的生命周期可以被加载、更新、停用也能被多个 Agent 组合使用。Skill 更像是给专业员工建的一份“岗位手册 工具清单 考核标准”的合订本。Agent 则是一个自主决策的运行时环境。它负责接收任务、拆解目标、编排调度、调用 Skill、处理结果。Agent 是大脑和四肢Skill 是专业技能。一个人可能懂编程但“懂编程”这个技能本身独立于人存在——你可以把这份技能文档交给另一个 Agent它也能学会。拿我做过的一个 SQL 生成 Agent 来举例Prompt 版本里我在 system prompt 里写了“你是 SQL 专家请根据用户问题生成 SQL注意表名、字段名要准确不要臆造不存在的字段尽量优化性能”。效果嘛简单查询没问题一到多表 join、复杂聚合、窗口函数就乱来甚至凭空捏造字段名。后来我把它重构成 Skill 方案先建一个sql_generation_skill目录里面放SKILL.md技能描述与调用条件、schema.sql数据库的真实表结构、examples/几十组问题-正确 SQL 的示例库、rules.mdSQL 书写规范、命名规则、特殊字段处理方式。运行时有一步专门做表结构注入和示例检索模型在下笔前就已经“看到”了真实 schema 和类似问题的标准答案。同样的模型正确率从 60% 左右提到 85% 以上。这就是封装和灌文字的区别。2.2 Skill 架构的三大核心模块拆解从工程角度来看一个合格的 Skill 需要三大核心模块能力描述层、执行逻辑层、外部依赖层。能力描述层解决的是“什么时候该用我”。这一层必须写清楚技能的适用场景、触发条件、不适用场景、使用的前置要求。很多 Skill 翻车不是因为执行逻辑不对而是模型在根本不该用它的时候调用了它。你让一个只负责文档翻译的 Skill 去处理代码审查不乱套才怪。所以这一层是“门卫”先挡掉 60% 的误用。执行逻辑层是整个 Skill 的心脏。它定义了任务拆解路径、每一步怎么做、中间结果怎么校验、失败怎么回退。在这一层你需要给出明确的步骤编号和判断分支。比如搜索类 Skill先做什么后做什么结果为空时怎么处理结果过多时怎么压缩展示。不要指望模型自己临场发挥它是一个优秀的“执行者”却不是天生的“决策者”。如果执行步骤是“调用搜索-筛选-摘要”那模型真会傻乎乎按这个顺序来哪怕第一步就失败了也不会跳过重试——你必须写好“第1步失败则执行第1.1步”。外部依赖层解决的是“做事需要什么工具和数据”。这里包括 API 端点定义、请求参数约束、鉴权信息、数据库连接逻辑、可查询的 Schema以及可检索的示例库。这一层是 Skill 与 Skill 之间差异最大的地方也是最需要投入维护精力的地方。我见过有人把外部依赖直接硬编码在 Prompt 里结果 API 升级后所有 Agent 全部瘫痪排障排了一整天。正确的做法是把依赖独立出来通过配置文件或环境变量注入让 Skill 变成可替换的“插件”。这三个模块缺一个Skill 就很难说“成立”。只有描述没有逻辑等于给模型一张菜谱但没告诉它怎么判断火候只有逻辑没有依赖等于让它炒菜却没给它锅只有依赖没有描述模型根本不知道什么时候该掏出这套工具。3. 从 0 到 1一个 Skill 的制作全流程3.1 场景选定什么样的任务才值得做成 Skill不是所有功能都配叫 Skill。我在刚开始做的时候也犯过“万物皆 Skill”的毛病只要是重复性的任务就想着封装结果封装出来的东西比直接用 Prompt 还难用维护成本却高了一倍。根据实际经验一个任务值得做成 Skill至少要满足三个条件第一任务边界清晰。输入输出都相对固定任务有明确的完成标准。比如“输入一段中文文本输出英文摘要”这就很清晰。而“帮我写个方案”这种边界模糊的任务不适合直接做 Skill更适合让 Agent 先拆解再匹配多个 Skill。第二执行路径可标准化。同样的输入交给 10 个人来做大家的步骤高度相似结果是可控可复现的。翻译、代码补全、SQL 生成、会议纪要整理都属于这一类。而“头脑风暴”“创意策划”这类高度依赖发散思维的任务不建议做成 Skill因为它的结果不可控模型自由发挥的空间反而更重要。第三重复频率足够高。这个 Skill 会被反复使用值得投入时间去打磨。如果是一个月才用一次的冷门任务还是直接用长 Prompt 处理更方便。我个人的经验阈值是每周使用次数不低于 5 次或者每次手动处理成本超过 30 分钟才值得做成 Skill。场景选定时还有一个容易被忽略的维度你要服务的对象是谁。如果是给自己用的个人 Skill自由度可以很高怎么顺手怎么来如果是团队共用就要考虑通用性、清晰度、维护交接成本如果是面向外部用户的产品级 Skill那还得多考虑容错、权限和安全边界。目标不一样Skill 的设计模式完全不同。3.2 核心链路设计从输入到输出的完整闭环场景定了之后下一步是把任务的执行链路完整画出来。不要直接在文字编辑器里写 SKILL.md先把链路想清楚。我常用的方式是画一张简易的流程表输入节点 - 预处理 - 核心处理 - 后处理 - 输出节点。拿“SQL 生成 Skill”举例链路是这样的输入用户自然语言问题“统计 2024 年第一季度每个地区的销售总额按降序排列”预处理识别问题涉及的实体和字段地区、销售额、时间范围检索相关的表结构从示例库中找相似 case核心处理根据 schema 和示例生成候选 SQL用 EXPLAIN 或格式校验器检查语法后处理检查是否遗漏字段、是否需要添加索引提示、是否包含多余的分号输出SQL 语句 简要说明每一条边都要写清楚数据怎么流转、哪一步出错要走什么分支。很多 Skill 不好用是因为链路太粗模型在中间环节迷路了。链路设计得越细模型的表现就越稳定。这里有一个技巧把链路里最脆弱的环节找出来设计兜底方案。脆弱环节通常是外部 API 调用可能超时、可能返回空、可能报错和格式校验模型输出格式不稳定。我一般会为每个外部依赖写至少一层 retry 逻辑并且设计“API 失败时降级为纯规则处理”的备选路径。虽然不是所有场景都能降级但这个思路值得保留。3.3 资源准备与工具定义链路设计完成后开始收集和整理 Skill 所需的外部资源。这一部分往往是区分“能用”和“好用”的分水岭。工具定义是重中之重。如果你的 Skill 需要调用外部 API一定要给模型提供结构化的 function/tool schema而不是在 Prompt 里用自然语言描述“你可以调用某 API参数是……”。为什么因为模型解析 JSON Schema 的准确率远高于解析自然语言描述。Schema 要包含接口的完整路径、请求方法、请求头要求、参数列表名称、类型、是否必填、取值范围、响应结构说明、错误码含义。一个常见的反面教材是给模型 API 地址但不给参数约束模型猜参数名接口返回 400然后它又把 400 当成结果返回给用户。示例库的质量同样关键。示例不能随便找几个 case 就放进去每个示例都应该覆盖一类典型模式或一个容易出错的边界情况。示例不是越多越好——信息量过大会稀释模型对关键特征的注意力。我通常的做法是先跑一版粗版示例看哪些场景下模型容易犯错再有针对性地补充对应场景的示例。示例库是“打补丁补出来的”不是一次性写完的。还有一类资源经常被忽略负面示例。即“什么不能做”的示例。比如 SQL 生成 Skill 里就要放上“禁止使用不存在的字段名”的反例用户问“查询 2024 年入职员工”模型捏造了hire_date字段但实际表里这个字段叫entry_date。这种负面示例对模型的约束力比十句“不要臆造字段”都强。3.4 SKILL.md 的写作技巧像写接口文档不要像写作文SKILL.md 是整个 Skill 的入口文件模型会先读它来决定是否调用、如何调用。很多人把 SKILL.md 写成了长篇大论的自然语言作文这在工程上是低效的——大段散文式的描述会挤占上下文窗口而且模型对长文本的细节记忆是有衰减的。我总结的 SKILL.md 最佳实践是结构化的接口文档风格包含以下板块技能名称简洁一眼看懂适用场景清单分点列出不适用场景清单明确告诉模型什么时候不要用调用前置条件需要哪些外部资源就绪执行步骤编号列表每一步尽可能细输出格式模板给一个具体样例告诉模型按这个结构输出常见错误与规避方法这个模板最大的好处是可解析、可校验、可更新。模型能在很短的上下文里抓到核心指令开发者也能通过文本 diff 看到版本变化。不要怕写得太干Skill 不是给人读的散文是给模型读的配置文档。还有个小技巧在 SKILL.md 里使用明确的“必须/禁止/允许”词汇体系。“必须”类指令表示强制执行“禁止”类指令表示绝对不要做“允许”类指令表示自由度。这三类混用时模型往往会优先满足“必须”然后是“禁止”最后才考虑“允许”。所以关键约束要写进“禁止”核心流程要写进“必须”不要所有指令都用同一个强度等级去写。4. 实操演示手把手构建一个“会议纪要 Skill”4.1 需求定义与输入输出模板设计前面讲了理论要落地还得看实例。这里我用一个最常见的场景——“会议纪要 Skill”——完整演示一遍构建过程。这个 Skill 几乎每个做 AI Agent 的人都需要而且边界足够清楚非常适合用来做教学案例。需求定义输入一段会议录音转文字或者多人对话文本输出结构化会议纪要。纪要包含会议主题、参会人、时间、讨论要点、决策结论、待办事项含负责人和截止时间。在设计输入输出模板时我先定义输入的格式要求原始文本作为输入主体可选参数包括会议标题、参会人列表、会议日期。如果输入里本身包含这些元信息模型可以从文本中自动提取如果输入中没有就要引导模型在输出中标记“未提及”。输出模板是三段式概览一句话总结、详细纪要分议题展开、行动项表格形式列出负责人、事项、截止时间。这里有个实操经验待办事项一定要用表格输出纯文本罗列的待办事项很容易被后续处理的代码解析失败。表格在结构化程度上远高于自然语言段落而且用户阅读体验更好。4.2 关键步骤实现分级处理与质量门控会议纪要 Skill 的核心链路可以拆成四步文本清洗、议题分割、要点提取、行动项识别。每一步都有自己的质量门控标准。第一步文本清洗。输入文本可能含有“嗯”“啊”这类语气词、重复表述、说话中断等噪声。清洗规则要内置在 Skill 里但注意不要过度清洗——语气词和口语化表达有时能帮助判断说话人的情绪和态度全删了会丢失语境线索。我采用的方案是“最小清洗”只去除明显的无用填充词保留主体内容。第二步议题分割。长会议往往包含多个议题模型要识别出议题切换点。这一步是纪要质量的瓶颈分割不对后面的要点提取和行动项识别全是空中楼阁。我会在 Skill 里内置一个“轮次转换”判断逻辑当说话主题、参与人组合、语气强度发生明显变化时判定为新议题开始。第三步要点提取。按议题为单位提取每个议题下各参与人的核心观点、分歧点、结论。这里遇到的最大问题是“模型容易把冗长的背景陈述也当成要点”。我的解法是在 Skill 内加入“信息密度过滤”规则只保留包含观点判断、数据、决策信号的句子过滤纯描述性内容。第四步行动项识别。这是整个 Skill 里对准确性要求最高的环节。误报把非任务句子识别为任务和漏报真正任务没被识别出来都会严重影响下游执行。我在实际调试中用过一个比较有效的方法行动项识别必须带上下文校验不能只看单句话。一句话“把方案发给客户”本身像行动项但前提是说话人身份是项目负责人且客户已确认。把上下文判断融入识别链路后误报率下降明显。每个环节完成后模型还要执行一次自检检查输出是否完整覆盖了所有输入的关键内容是否与原文产生冲突。这个自检步骤看起来多余实际上能堵住不少低级错误。4.3 测试评估如何知道自己做的 Skill 好不好用Skill 做完不能直接拿去用得先做一轮系统评估。评估维度我建议用四个召回率、准确率、格式合规率、端到端任务完成率。针对会议纪要 Skill召回率是“原文中的重要信息有多少被纪要覆盖了”准确率是“纪要中的信息有多少在原文中确实存在没有幻觉”格式合规率看输出是否严格符合模板端到端完成率看真实场景下用户对结果的满意度。评估数据集不必一开始就做很大10 组真实会议文本就能发现很多问题。我强烈建议用真实数据不要用合成数据——合成数据太干净了没法暴露真实场景里口音、打断、话题跳跃、多语混用这些麻烦。评测方式有两种自动化评估和人工评估。自动化评估用代码检查格式合规率、字段完整性、是否存在模板缺失语义层面的召回率、准确率跑批量对比时可以用大模型打分像用 GPT-4 当裁判给每条输出打 1 到 5 分。不过要注意用大模型当裁判本身也存在误判风险最后的结论还是需要人工抽检兜底。根据我的经验前三轮评测往往会发现三类问题一是特定发言模式下比如多人同时说话、插话抢话的行动项漏识别二是输出里出现了原文完全没有的信息幻觉三是模板格式偶尔不完整比如表格少了一列。这三类问题都需要回到 Skill 本身去修复要么补示例、要么加强规则、要么调整后处理逻辑。5. 实战中常见的“Skill 翻车”场景与排查技巧5.1 现象一模型死活不调用 Skill只按自己的理解回答这是最让人崩溃的问题。Skill 放在那里模型就是不调非要自己凭常识回答。排查方向有两步先检查 SKILL.md 里的触发条件描述是否清晰再确认模型加载 Skill 的机制是否正常。关于触发条件有些 Skill 侧是“在满足条件 A 时调用”但 A 描述得太模糊模型不确定自己是否满足条件索性不调用。解决方法把触发条件写得更“苛刻”。什么是苛刻就是给出明确的、可判定的关键词和数据特征。比如会议纪要 Skill 的触发条件写作“输入文本中有两个或两个以上说话人交替发言且文本长度超过 300 字”。模型能明确判断这个条件是否成立调用决策就果断得多。还有一类特殊情况多个 Skill 共享同一触发条件时模型容易“选择困难”哪个都不调。这时候要在每个 Skill 的触发条件里加入“排除词”——“当任务属于文档翻译时不要调用 SQL 生成 Skill”。排除词比正向条件管用得多。5.2 现象二Skill 调用了但执行步骤乱序模型调用 Skill 后不按 SKILL.md 里定义的步骤执行自己东一下西一下。这通常是因为 SKILL.md 里的步骤描述了“做什么”但没有说清“为什么按这个顺序做”。模型没有因果链感知时就容易自作主张调整顺序。解法是在每个步骤前加“前置条件说明”——明确写上“本步骤执行前必须已完成步骤 1 和步骤 2 的输出”。这种依赖关系说得越显式模型越不容易乱序。还有一种做法是把步骤间的数据传递写成变量——比如第 2 步的输出title_candidates作为第 3 步的输入——模型对变量依赖的遵循度通常高于对自然语言顺序描述的遵循度。5.3 现象二补充模型输出格式不对特别是表格缺失、JSON 截断AI 模型输出的一大特点是“不稳定”。同一套 Skill上一次输出规范的 JSON下一次就在中间截断了或者表格少一行。排查时要分清是模型能力问题还是 Skill 的预期管理问题。如果是 JSON 截断多半是输出长度受限或模型在超长输出时注意力衰减。对策是调整生成参数里的max_tokens或者把输出任务拆小——一次只生成一个 JSON 对象而不是一次生成整个大 JSON 数组。如果是表格缺行多半是后处理步骤没有加“行数校验”需要写一个验证器解析输出后统计表格行数与输入中识别到的行动项数量对比不一致就触发重新生成最多重试两次。这里有一个特别好用的小技巧在后处理里加一个“格式修复器”。很多模型输出不全是完全错误的只是局部不合法格式修复器可以尝试修正。比如把 markdown 表格里缺失的分隔线补上、把 JSON 里多余的逗号删掉、把被截断的数组补上闭合括号。这种规则型修复器不依赖模型能力效率高、成本低是锦上添花但也是雪中送炭。5.4 现象四同一个 Skill换一个模型就效果崩坏Skill 在设计时如果高度依赖特定模型的风格和习惯比如某人写 Prompt 习惯了某模型喜欢接受否定式表达换一个模型就完全不适用那这个 Skill 的移植性就差。我踩过的一个典型的“风格依赖”坑写了一套中文 SQL 生成 Skill在 Claude 上表现优秀迁移到某个轻量开源模型上后准确率直线下降。排查发现轻量模型对 SKILL.md 里的复杂分支条件理解不到位更依赖示例。解决方式是为不同模型维护不同版本的 Skill 示例库——轻量模型需要更多更接近真实问题的示例同时减少规则条数让规则更直白。所以做 Skill 时最好想清楚一件事你是要做一个模型专用的 Skill还是一个模型无关的 Skill。前者体验更好后者复用性更强。建议核心业务用模型专用版边缘场景用通用版。6. 进阶进阶如何把 Skill 做成一个可组合、可分发的产品6.1 Skill 的版本管理与打包分发思路当 Skill 从一个“自己用的小脚本”变成“团队共享的基础设施”版本管理和打包分发就提上日程了。我见过很多团队在这一步翻车——Skill 的修改没有记录、依赖的外部资源散落在各个聊天记录和网盘里、不同成员手里的 Skill 版本不一致。最后的结果就是运行结果对不上谁也不敢改代码变成了“祖传秘方”。建议的实践方式用 Git 仓库管理 Skill 目录每次修改提交都写清楚变更原因。Skill 目录结构与代码仓库直接对应一个 Skill 一个子目录里面包含 SKILL.md、示例库、工具定义、依赖配置、版本说明。版本号遵循语义化版本规范主版本号变化代表行为不兼容的大改次版本号变化代表新增能力或资源补丁版本号变化代表 bug 修复或文档修订。打包分发方面目前主流的方式是将 Skill 目录压缩成单一压缩包或者直接发布到内部/公共的 Skill 注册中心。分发时要带上完整的依赖说明讲清楚需要哪些 API Key、哪些数据库连接、哪些模型能力支持。没有依赖说明的 Skill 包别人拿到手大概率跑不起来。6.2 Skill 与智能体Agent的双向奔赴如何组织多个 Skill 协同单个 Skill 的能力再强也是有限的真正体现价值的是多个 Skill 组合在智能体里协同完成复杂任务。这里就涉及到编排层设计。编排层要回答三个问题当前任务涉及哪些 Skill 的组合它们的执行顺序是并行还是串行一个 Skill 的输出如何成为另一个 Skill 的输入我的一个推荐模式是“流水线Pipe”第一步意图识别分诊 Skill 判断任务类型第二步按任务类型从 Skill 库中检索匹配的 2 到 4 个 Skill第三步把上一个 Skill 的结构化输出作为下一个 Skill 输入的一部分。为了做到这一步每个 Skill 的输入输出都必须是有规范格式定义的——这正是前面强调结构化输出模板的原因。还有一个常见的坑多个 Skill 并行执行时结果冲突。比如“信息查询 Skill”和“文档摘要 Skill”同时处理同一段内容一个说“信息充足”一个说“信息不足以完成摘要”Agent 就不知道该信谁。我的解法是在编排时给每个 Skill 设置优先级和仲裁规则当结果冲突时以高优先级 Skill 的输出为准。这套规则看起来机械但在工程上非常有效。6.3 关于 Skill 的“无禁词/无审核”误区提醒最近逛社区经常看到有人在搜“无限制 AI 聊天”“无禁词 AI”之类的词也有一些帖子把 Skill 包装成“绕过内容安全限制”的万能钥匙。这里我必须把话说明白Skill 不是用来突破安全边界的工具。内容安全边界是大模型运行的基本前提你可以在 Skill 中设计更细致的业务规则让模型更懂你的领域但你不能也不应该试图通过 Skill 让模型输出违反公序良俗、触碰法律底线的内容。从工程角度来看就算技术上能够做到一定程度“绕开限制”这类 Skill 也毫无产品化价值你的服务上线需要过审核你的应用要面对真实用户风险完全不可控。Skill 的正道是提升模型在专业领域的执行能力而不是钻安全策略的空子。我在做 Skill 评估时会把“是否产生了不安全内容”作为一票否决项——一个 Skill 哪怕准确率再高只要在测试中有一次生成不安全内容就必须回炉重做。6.4 个人经验怎样判断一个 Skill 是否值得长期运维Skill 做出来后不是一劳永逸的示例库需要更新、工具定义随 API 版本迭代、规则要根据新场景持续优化。长期运维一个 Skill 的成本其实不低所以在立项之初就要想清楚它的 ROI。我的判断标准有三条一是有没有被更上游的技术替代——比如某个 Skill 解决的问题随着模型能力升级自然消亡了二是有没有足够稳定的用户群——只有自己用的话多于两个维护轮次就值得重新评估三是有没有形成正反馈循环——外部依赖方的反馈是否能持续输入到 Skill 的迭代里。根据个人经验一个 Skill 的生命周期一般在三个月到一年之间。有些会随着模型能力提升而被“吸收”比如模型原生就支持了你的 Skill 要做的事有些会因为业务方向调整而废弃只有少数核心领域的 Skill 能持续迭代超过一年。所以做 Skill 时从第一天起就要有“生命周期管理”意识不要觉得做出来就完事了。7. 最后分享一点实际体会写到这里再回头说一个我特别想强调的点。现在 AI Agent 领域火得不行各种概念层出不穷Skill 这个词已经被用滥了。但真正做事的人要沉住气不要被概念绑架。从长 Prompt 进化到 Skill核心不是“写得更长”“写得更细”而是工程化思维的引入——把不可控的模型行为变成可控的系统行为。Skill 的价值在于它把一次性的“灵光一现”变成了可持续迭代的“基础设施”。你用的时候可能感觉不到什么但当你需要修 bug、换模型、加功能时那套工程化架构带来的底气才是 Skill 真正的回报。我个人在实际操作中最大的心得是别迷恋“完美 Skill”那是永远不存在的。先做一版能用的然后让真实场景去鞭打它、磨砺它。第一批用户哪怕只有你自己的每一次抱怨都是 Skill 迭代升级最好的线索。如果你正准备把某个长 Prompt 改造成 Skill我的建议是从最小闭环切入先做一个只含一个外部工具、三步执行链路的超简版跑通后再逐步加规则、加示例、加分支。路是一步一步走出来的Skill 也是这样。
从长Prompt到Skill：AI Agent能力的工程化封装指南
1. 长 Prompt 不是 Skill别再混淆了先说个我最近遇到的真实场景有位朋友兴致勃勃地丢给我一份“精心打磨”了快半个月的 Prompt说这是他团队最新封装的 Skill希望我帮忙看看能不能“提效”。我打开文档屏幕上密密麻麻全是约束条件、否定式指令、 few-shot 示例洋洋洒洒上千行。我问他“这个 Skill 里面的工具定义长什么样模型怎么决定什么时候调用外部 API失败重试策略是什么”他愣住了反问“什么工具定义我这是纯文本 Prompt不是应该所有大模型都能直接用吗”这个片段基本代表了当下 AI Agent 落地过程中最大的误解把“长 Prompt”当成“Skill”。很多人觉得 Prompt 写得足够长、足够细、足够“没漏洞”就相当于给模型封装了一项技能。但从工程视角看这完全是两码事。长 Prompt 是给模型的一段“说明文字”而 Skill 是一个可复用、可校验、可组合、可升级的系统单元。我在多个实际项目里踩过这个坑后来把 Skill 的整套构建方法整理成了一套可复制的 SOP今天这篇文章就把它完整拆开。如果你正在做 AI Agent、Codex 插件、Claude 插件或者其他工具型 AI 应用这篇文章应该能帮你省下几周时间。先说结论长 Prompt 解决的是“让模型听懂”Skill 解决的是“让模型会做”。前者是输入后者是能力封装。把输入当能力等于把字典当成写作才华字都在那儿但不代表能写出好文章。2. Skill 的本质一套可封装、可验证的执行单元2.1 Skill 与 Prompt、Agent 的边界在哪里要搞清楚 Skill先得给它画一条清晰的分界线。Prompt、Skill、Agent 这三个概念在中文技术社区里经常被混着用但它们在工程上的定位完全不同。Prompt 是一段自然语言指令本质是“上下文输入”。它的特点是不可校验、不可复用换个模型效果就是另一回事、不可组合。你可以把 Prompt 想象成给临时工写的一份工作说明——今天这个人干完明天换个人来又得重新講一遍。而且你没法保证临时工一定会照着做。Skill技能是模型或 Agent可持续调用的一组能力封装通常由三部分构成能力描述什么场景下用、执行逻辑怎么做、按什么步骤、必要的外部资源工具定义、API Schema、知识库索引、示例库。它有自己的生命周期可以被加载、更新、停用也能被多个 Agent 组合使用。Skill 更像是给专业员工建的一份“岗位手册 工具清单 考核标准”的合订本。Agent 则是一个自主决策的运行时环境。它负责接收任务、拆解目标、编排调度、调用 Skill、处理结果。Agent 是大脑和四肢Skill 是专业技能。一个人可能懂编程但“懂编程”这个技能本身独立于人存在——你可以把这份技能文档交给另一个 Agent它也能学会。拿我做过的一个 SQL 生成 Agent 来举例Prompt 版本里我在 system prompt 里写了“你是 SQL 专家请根据用户问题生成 SQL注意表名、字段名要准确不要臆造不存在的字段尽量优化性能”。效果嘛简单查询没问题一到多表 join、复杂聚合、窗口函数就乱来甚至凭空捏造字段名。后来我把它重构成 Skill 方案先建一个sql_generation_skill目录里面放SKILL.md技能描述与调用条件、schema.sql数据库的真实表结构、examples/几十组问题-正确 SQL 的示例库、rules.mdSQL 书写规范、命名规则、特殊字段处理方式。运行时有一步专门做表结构注入和示例检索模型在下笔前就已经“看到”了真实 schema 和类似问题的标准答案。同样的模型正确率从 60% 左右提到 85% 以上。这就是封装和灌文字的区别。2.2 Skill 架构的三大核心模块拆解从工程角度来看一个合格的 Skill 需要三大核心模块能力描述层、执行逻辑层、外部依赖层。能力描述层解决的是“什么时候该用我”。这一层必须写清楚技能的适用场景、触发条件、不适用场景、使用的前置要求。很多 Skill 翻车不是因为执行逻辑不对而是模型在根本不该用它的时候调用了它。你让一个只负责文档翻译的 Skill 去处理代码审查不乱套才怪。所以这一层是“门卫”先挡掉 60% 的误用。执行逻辑层是整个 Skill 的心脏。它定义了任务拆解路径、每一步怎么做、中间结果怎么校验、失败怎么回退。在这一层你需要给出明确的步骤编号和判断分支。比如搜索类 Skill先做什么后做什么结果为空时怎么处理结果过多时怎么压缩展示。不要指望模型自己临场发挥它是一个优秀的“执行者”却不是天生的“决策者”。如果执行步骤是“调用搜索-筛选-摘要”那模型真会傻乎乎按这个顺序来哪怕第一步就失败了也不会跳过重试——你必须写好“第1步失败则执行第1.1步”。外部依赖层解决的是“做事需要什么工具和数据”。这里包括 API 端点定义、请求参数约束、鉴权信息、数据库连接逻辑、可查询的 Schema以及可检索的示例库。这一层是 Skill 与 Skill 之间差异最大的地方也是最需要投入维护精力的地方。我见过有人把外部依赖直接硬编码在 Prompt 里结果 API 升级后所有 Agent 全部瘫痪排障排了一整天。正确的做法是把依赖独立出来通过配置文件或环境变量注入让 Skill 变成可替换的“插件”。这三个模块缺一个Skill 就很难说“成立”。只有描述没有逻辑等于给模型一张菜谱但没告诉它怎么判断火候只有逻辑没有依赖等于让它炒菜却没给它锅只有依赖没有描述模型根本不知道什么时候该掏出这套工具。3. 从 0 到 1一个 Skill 的制作全流程3.1 场景选定什么样的任务才值得做成 Skill不是所有功能都配叫 Skill。我在刚开始做的时候也犯过“万物皆 Skill”的毛病只要是重复性的任务就想着封装结果封装出来的东西比直接用 Prompt 还难用维护成本却高了一倍。根据实际经验一个任务值得做成 Skill至少要满足三个条件第一任务边界清晰。输入输出都相对固定任务有明确的完成标准。比如“输入一段中文文本输出英文摘要”这就很清晰。而“帮我写个方案”这种边界模糊的任务不适合直接做 Skill更适合让 Agent 先拆解再匹配多个 Skill。第二执行路径可标准化。同样的输入交给 10 个人来做大家的步骤高度相似结果是可控可复现的。翻译、代码补全、SQL 生成、会议纪要整理都属于这一类。而“头脑风暴”“创意策划”这类高度依赖发散思维的任务不建议做成 Skill因为它的结果不可控模型自由发挥的空间反而更重要。第三重复频率足够高。这个 Skill 会被反复使用值得投入时间去打磨。如果是一个月才用一次的冷门任务还是直接用长 Prompt 处理更方便。我个人的经验阈值是每周使用次数不低于 5 次或者每次手动处理成本超过 30 分钟才值得做成 Skill。场景选定时还有一个容易被忽略的维度你要服务的对象是谁。如果是给自己用的个人 Skill自由度可以很高怎么顺手怎么来如果是团队共用就要考虑通用性、清晰度、维护交接成本如果是面向外部用户的产品级 Skill那还得多考虑容错、权限和安全边界。目标不一样Skill 的设计模式完全不同。3.2 核心链路设计从输入到输出的完整闭环场景定了之后下一步是把任务的执行链路完整画出来。不要直接在文字编辑器里写 SKILL.md先把链路想清楚。我常用的方式是画一张简易的流程表输入节点 - 预处理 - 核心处理 - 后处理 - 输出节点。拿“SQL 生成 Skill”举例链路是这样的输入用户自然语言问题“统计 2024 年第一季度每个地区的销售总额按降序排列”预处理识别问题涉及的实体和字段地区、销售额、时间范围检索相关的表结构从示例库中找相似 case核心处理根据 schema 和示例生成候选 SQL用 EXPLAIN 或格式校验器检查语法后处理检查是否遗漏字段、是否需要添加索引提示、是否包含多余的分号输出SQL 语句 简要说明每一条边都要写清楚数据怎么流转、哪一步出错要走什么分支。很多 Skill 不好用是因为链路太粗模型在中间环节迷路了。链路设计得越细模型的表现就越稳定。这里有一个技巧把链路里最脆弱的环节找出来设计兜底方案。脆弱环节通常是外部 API 调用可能超时、可能返回空、可能报错和格式校验模型输出格式不稳定。我一般会为每个外部依赖写至少一层 retry 逻辑并且设计“API 失败时降级为纯规则处理”的备选路径。虽然不是所有场景都能降级但这个思路值得保留。3.3 资源准备与工具定义链路设计完成后开始收集和整理 Skill 所需的外部资源。这一部分往往是区分“能用”和“好用”的分水岭。工具定义是重中之重。如果你的 Skill 需要调用外部 API一定要给模型提供结构化的 function/tool schema而不是在 Prompt 里用自然语言描述“你可以调用某 API参数是……”。为什么因为模型解析 JSON Schema 的准确率远高于解析自然语言描述。Schema 要包含接口的完整路径、请求方法、请求头要求、参数列表名称、类型、是否必填、取值范围、响应结构说明、错误码含义。一个常见的反面教材是给模型 API 地址但不给参数约束模型猜参数名接口返回 400然后它又把 400 当成结果返回给用户。示例库的质量同样关键。示例不能随便找几个 case 就放进去每个示例都应该覆盖一类典型模式或一个容易出错的边界情况。示例不是越多越好——信息量过大会稀释模型对关键特征的注意力。我通常的做法是先跑一版粗版示例看哪些场景下模型容易犯错再有针对性地补充对应场景的示例。示例库是“打补丁补出来的”不是一次性写完的。还有一类资源经常被忽略负面示例。即“什么不能做”的示例。比如 SQL 生成 Skill 里就要放上“禁止使用不存在的字段名”的反例用户问“查询 2024 年入职员工”模型捏造了hire_date字段但实际表里这个字段叫entry_date。这种负面示例对模型的约束力比十句“不要臆造字段”都强。3.4 SKILL.md 的写作技巧像写接口文档不要像写作文SKILL.md 是整个 Skill 的入口文件模型会先读它来决定是否调用、如何调用。很多人把 SKILL.md 写成了长篇大论的自然语言作文这在工程上是低效的——大段散文式的描述会挤占上下文窗口而且模型对长文本的细节记忆是有衰减的。我总结的 SKILL.md 最佳实践是结构化的接口文档风格包含以下板块技能名称简洁一眼看懂适用场景清单分点列出不适用场景清单明确告诉模型什么时候不要用调用前置条件需要哪些外部资源就绪执行步骤编号列表每一步尽可能细输出格式模板给一个具体样例告诉模型按这个结构输出常见错误与规避方法这个模板最大的好处是可解析、可校验、可更新。模型能在很短的上下文里抓到核心指令开发者也能通过文本 diff 看到版本变化。不要怕写得太干Skill 不是给人读的散文是给模型读的配置文档。还有个小技巧在 SKILL.md 里使用明确的“必须/禁止/允许”词汇体系。“必须”类指令表示强制执行“禁止”类指令表示绝对不要做“允许”类指令表示自由度。这三类混用时模型往往会优先满足“必须”然后是“禁止”最后才考虑“允许”。所以关键约束要写进“禁止”核心流程要写进“必须”不要所有指令都用同一个强度等级去写。4. 实操演示手把手构建一个“会议纪要 Skill”4.1 需求定义与输入输出模板设计前面讲了理论要落地还得看实例。这里我用一个最常见的场景——“会议纪要 Skill”——完整演示一遍构建过程。这个 Skill 几乎每个做 AI Agent 的人都需要而且边界足够清楚非常适合用来做教学案例。需求定义输入一段会议录音转文字或者多人对话文本输出结构化会议纪要。纪要包含会议主题、参会人、时间、讨论要点、决策结论、待办事项含负责人和截止时间。在设计输入输出模板时我先定义输入的格式要求原始文本作为输入主体可选参数包括会议标题、参会人列表、会议日期。如果输入里本身包含这些元信息模型可以从文本中自动提取如果输入中没有就要引导模型在输出中标记“未提及”。输出模板是三段式概览一句话总结、详细纪要分议题展开、行动项表格形式列出负责人、事项、截止时间。这里有个实操经验待办事项一定要用表格输出纯文本罗列的待办事项很容易被后续处理的代码解析失败。表格在结构化程度上远高于自然语言段落而且用户阅读体验更好。4.2 关键步骤实现分级处理与质量门控会议纪要 Skill 的核心链路可以拆成四步文本清洗、议题分割、要点提取、行动项识别。每一步都有自己的质量门控标准。第一步文本清洗。输入文本可能含有“嗯”“啊”这类语气词、重复表述、说话中断等噪声。清洗规则要内置在 Skill 里但注意不要过度清洗——语气词和口语化表达有时能帮助判断说话人的情绪和态度全删了会丢失语境线索。我采用的方案是“最小清洗”只去除明显的无用填充词保留主体内容。第二步议题分割。长会议往往包含多个议题模型要识别出议题切换点。这一步是纪要质量的瓶颈分割不对后面的要点提取和行动项识别全是空中楼阁。我会在 Skill 里内置一个“轮次转换”判断逻辑当说话主题、参与人组合、语气强度发生明显变化时判定为新议题开始。第三步要点提取。按议题为单位提取每个议题下各参与人的核心观点、分歧点、结论。这里遇到的最大问题是“模型容易把冗长的背景陈述也当成要点”。我的解法是在 Skill 内加入“信息密度过滤”规则只保留包含观点判断、数据、决策信号的句子过滤纯描述性内容。第四步行动项识别。这是整个 Skill 里对准确性要求最高的环节。误报把非任务句子识别为任务和漏报真正任务没被识别出来都会严重影响下游执行。我在实际调试中用过一个比较有效的方法行动项识别必须带上下文校验不能只看单句话。一句话“把方案发给客户”本身像行动项但前提是说话人身份是项目负责人且客户已确认。把上下文判断融入识别链路后误报率下降明显。每个环节完成后模型还要执行一次自检检查输出是否完整覆盖了所有输入的关键内容是否与原文产生冲突。这个自检步骤看起来多余实际上能堵住不少低级错误。4.3 测试评估如何知道自己做的 Skill 好不好用Skill 做完不能直接拿去用得先做一轮系统评估。评估维度我建议用四个召回率、准确率、格式合规率、端到端任务完成率。针对会议纪要 Skill召回率是“原文中的重要信息有多少被纪要覆盖了”准确率是“纪要中的信息有多少在原文中确实存在没有幻觉”格式合规率看输出是否严格符合模板端到端完成率看真实场景下用户对结果的满意度。评估数据集不必一开始就做很大10 组真实会议文本就能发现很多问题。我强烈建议用真实数据不要用合成数据——合成数据太干净了没法暴露真实场景里口音、打断、话题跳跃、多语混用这些麻烦。评测方式有两种自动化评估和人工评估。自动化评估用代码检查格式合规率、字段完整性、是否存在模板缺失语义层面的召回率、准确率跑批量对比时可以用大模型打分像用 GPT-4 当裁判给每条输出打 1 到 5 分。不过要注意用大模型当裁判本身也存在误判风险最后的结论还是需要人工抽检兜底。根据我的经验前三轮评测往往会发现三类问题一是特定发言模式下比如多人同时说话、插话抢话的行动项漏识别二是输出里出现了原文完全没有的信息幻觉三是模板格式偶尔不完整比如表格少了一列。这三类问题都需要回到 Skill 本身去修复要么补示例、要么加强规则、要么调整后处理逻辑。5. 实战中常见的“Skill 翻车”场景与排查技巧5.1 现象一模型死活不调用 Skill只按自己的理解回答这是最让人崩溃的问题。Skill 放在那里模型就是不调非要自己凭常识回答。排查方向有两步先检查 SKILL.md 里的触发条件描述是否清晰再确认模型加载 Skill 的机制是否正常。关于触发条件有些 Skill 侧是“在满足条件 A 时调用”但 A 描述得太模糊模型不确定自己是否满足条件索性不调用。解决方法把触发条件写得更“苛刻”。什么是苛刻就是给出明确的、可判定的关键词和数据特征。比如会议纪要 Skill 的触发条件写作“输入文本中有两个或两个以上说话人交替发言且文本长度超过 300 字”。模型能明确判断这个条件是否成立调用决策就果断得多。还有一类特殊情况多个 Skill 共享同一触发条件时模型容易“选择困难”哪个都不调。这时候要在每个 Skill 的触发条件里加入“排除词”——“当任务属于文档翻译时不要调用 SQL 生成 Skill”。排除词比正向条件管用得多。5.2 现象二Skill 调用了但执行步骤乱序模型调用 Skill 后不按 SKILL.md 里定义的步骤执行自己东一下西一下。这通常是因为 SKILL.md 里的步骤描述了“做什么”但没有说清“为什么按这个顺序做”。模型没有因果链感知时就容易自作主张调整顺序。解法是在每个步骤前加“前置条件说明”——明确写上“本步骤执行前必须已完成步骤 1 和步骤 2 的输出”。这种依赖关系说得越显式模型越不容易乱序。还有一种做法是把步骤间的数据传递写成变量——比如第 2 步的输出title_candidates作为第 3 步的输入——模型对变量依赖的遵循度通常高于对自然语言顺序描述的遵循度。5.3 现象二补充模型输出格式不对特别是表格缺失、JSON 截断AI 模型输出的一大特点是“不稳定”。同一套 Skill上一次输出规范的 JSON下一次就在中间截断了或者表格少一行。排查时要分清是模型能力问题还是 Skill 的预期管理问题。如果是 JSON 截断多半是输出长度受限或模型在超长输出时注意力衰减。对策是调整生成参数里的max_tokens或者把输出任务拆小——一次只生成一个 JSON 对象而不是一次生成整个大 JSON 数组。如果是表格缺行多半是后处理步骤没有加“行数校验”需要写一个验证器解析输出后统计表格行数与输入中识别到的行动项数量对比不一致就触发重新生成最多重试两次。这里有一个特别好用的小技巧在后处理里加一个“格式修复器”。很多模型输出不全是完全错误的只是局部不合法格式修复器可以尝试修正。比如把 markdown 表格里缺失的分隔线补上、把 JSON 里多余的逗号删掉、把被截断的数组补上闭合括号。这种规则型修复器不依赖模型能力效率高、成本低是锦上添花但也是雪中送炭。5.4 现象四同一个 Skill换一个模型就效果崩坏Skill 在设计时如果高度依赖特定模型的风格和习惯比如某人写 Prompt 习惯了某模型喜欢接受否定式表达换一个模型就完全不适用那这个 Skill 的移植性就差。我踩过的一个典型的“风格依赖”坑写了一套中文 SQL 生成 Skill在 Claude 上表现优秀迁移到某个轻量开源模型上后准确率直线下降。排查发现轻量模型对 SKILL.md 里的复杂分支条件理解不到位更依赖示例。解决方式是为不同模型维护不同版本的 Skill 示例库——轻量模型需要更多更接近真实问题的示例同时减少规则条数让规则更直白。所以做 Skill 时最好想清楚一件事你是要做一个模型专用的 Skill还是一个模型无关的 Skill。前者体验更好后者复用性更强。建议核心业务用模型专用版边缘场景用通用版。6. 进阶进阶如何把 Skill 做成一个可组合、可分发的产品6.1 Skill 的版本管理与打包分发思路当 Skill 从一个“自己用的小脚本”变成“团队共享的基础设施”版本管理和打包分发就提上日程了。我见过很多团队在这一步翻车——Skill 的修改没有记录、依赖的外部资源散落在各个聊天记录和网盘里、不同成员手里的 Skill 版本不一致。最后的结果就是运行结果对不上谁也不敢改代码变成了“祖传秘方”。建议的实践方式用 Git 仓库管理 Skill 目录每次修改提交都写清楚变更原因。Skill 目录结构与代码仓库直接对应一个 Skill 一个子目录里面包含 SKILL.md、示例库、工具定义、依赖配置、版本说明。版本号遵循语义化版本规范主版本号变化代表行为不兼容的大改次版本号变化代表新增能力或资源补丁版本号变化代表 bug 修复或文档修订。打包分发方面目前主流的方式是将 Skill 目录压缩成单一压缩包或者直接发布到内部/公共的 Skill 注册中心。分发时要带上完整的依赖说明讲清楚需要哪些 API Key、哪些数据库连接、哪些模型能力支持。没有依赖说明的 Skill 包别人拿到手大概率跑不起来。6.2 Skill 与智能体Agent的双向奔赴如何组织多个 Skill 协同单个 Skill 的能力再强也是有限的真正体现价值的是多个 Skill 组合在智能体里协同完成复杂任务。这里就涉及到编排层设计。编排层要回答三个问题当前任务涉及哪些 Skill 的组合它们的执行顺序是并行还是串行一个 Skill 的输出如何成为另一个 Skill 的输入我的一个推荐模式是“流水线Pipe”第一步意图识别分诊 Skill 判断任务类型第二步按任务类型从 Skill 库中检索匹配的 2 到 4 个 Skill第三步把上一个 Skill 的结构化输出作为下一个 Skill 输入的一部分。为了做到这一步每个 Skill 的输入输出都必须是有规范格式定义的——这正是前面强调结构化输出模板的原因。还有一个常见的坑多个 Skill 并行执行时结果冲突。比如“信息查询 Skill”和“文档摘要 Skill”同时处理同一段内容一个说“信息充足”一个说“信息不足以完成摘要”Agent 就不知道该信谁。我的解法是在编排时给每个 Skill 设置优先级和仲裁规则当结果冲突时以高优先级 Skill 的输出为准。这套规则看起来机械但在工程上非常有效。6.3 关于 Skill 的“无禁词/无审核”误区提醒最近逛社区经常看到有人在搜“无限制 AI 聊天”“无禁词 AI”之类的词也有一些帖子把 Skill 包装成“绕过内容安全限制”的万能钥匙。这里我必须把话说明白Skill 不是用来突破安全边界的工具。内容安全边界是大模型运行的基本前提你可以在 Skill 中设计更细致的业务规则让模型更懂你的领域但你不能也不应该试图通过 Skill 让模型输出违反公序良俗、触碰法律底线的内容。从工程角度来看就算技术上能够做到一定程度“绕开限制”这类 Skill 也毫无产品化价值你的服务上线需要过审核你的应用要面对真实用户风险完全不可控。Skill 的正道是提升模型在专业领域的执行能力而不是钻安全策略的空子。我在做 Skill 评估时会把“是否产生了不安全内容”作为一票否决项——一个 Skill 哪怕准确率再高只要在测试中有一次生成不安全内容就必须回炉重做。6.4 个人经验怎样判断一个 Skill 是否值得长期运维Skill 做出来后不是一劳永逸的示例库需要更新、工具定义随 API 版本迭代、规则要根据新场景持续优化。长期运维一个 Skill 的成本其实不低所以在立项之初就要想清楚它的 ROI。我的判断标准有三条一是有没有被更上游的技术替代——比如某个 Skill 解决的问题随着模型能力升级自然消亡了二是有没有足够稳定的用户群——只有自己用的话多于两个维护轮次就值得重新评估三是有没有形成正反馈循环——外部依赖方的反馈是否能持续输入到 Skill 的迭代里。根据个人经验一个 Skill 的生命周期一般在三个月到一年之间。有些会随着模型能力提升而被“吸收”比如模型原生就支持了你的 Skill 要做的事有些会因为业务方向调整而废弃只有少数核心领域的 Skill 能持续迭代超过一年。所以做 Skill 时从第一天起就要有“生命周期管理”意识不要觉得做出来就完事了。7. 最后分享一点实际体会写到这里再回头说一个我特别想强调的点。现在 AI Agent 领域火得不行各种概念层出不穷Skill 这个词已经被用滥了。但真正做事的人要沉住气不要被概念绑架。从长 Prompt 进化到 Skill核心不是“写得更长”“写得更细”而是工程化思维的引入——把不可控的模型行为变成可控的系统行为。Skill 的价值在于它把一次性的“灵光一现”变成了可持续迭代的“基础设施”。你用的时候可能感觉不到什么但当你需要修 bug、换模型、加功能时那套工程化架构带来的底气才是 Skill 真正的回报。我个人在实际操作中最大的心得是别迷恋“完美 Skill”那是永远不存在的。先做一版能用的然后让真实场景去鞭打它、磨砺它。第一批用户哪怕只有你自己的每一次抱怨都是 Skill 迭代升级最好的线索。如果你正准备把某个长 Prompt 改造成 Skill我的建议是从最小闭环切入先做一个只含一个外部工具、三步执行链路的超简版跑通后再逐步加规则、加示例、加分支。路是一步一步走出来的Skill 也是这样。 
