不要把 Skill 写成 PromptAgent Skill 调优的系统方法与实战心得Skill 是 Agent 可按需加载的一组领域规则、工作流、工具说明、约束和验证方法。真正有效的 Skill不是写得越长越好而是让模型在正确的任务上被正确触发、以最小上下文完成最可靠的动作。本文总结 Skill 调优中的核心规律、失败模式和可复用方法。1. 我对 Skill 的重新理解1.1 Skill 不只是 PromptPrompt 主要描述一次请求应该怎样回答Skill 描述一类任务应该怎样完成。一个生产级 Skill 至少包含Skill 触发条件 工作目标 专业知识 操作流程 工具契约 输出格式 验证方法 边界/失败处理Skill 的关键价值是“按需加载”。如果所有规则都放进系统 Prompt上下文会膨胀任务之间会互相污染如果没有 Skill模型只能依赖泛化能力容易漏步骤、误用工具或无法判断什么时候应该停止。1.2 Skill 解决的问题把重复性的专家经验编码成可复用资产让 Agent 具备领域流程而不是只会自由发挥将复杂任务拆成可验证步骤控制工具调用的前置条件、权限和结果处理让不同 Skill 之间可以组合、隔离和版本化通过失败样本和评测集持续迭代。1.3 Skill、Rule、Prompt、Tool、Workflow 的区别概念解决的问题是否执行动作Rule始终有效的系统约束否Prompt当前一轮如何表达目标否Skill一类任务如何专业完成间接Tool对外部系统执行具体动作是Workflow明确规定的步骤与分支是通常确定性更强Agent根据目标自主决策是决策不完全固定Skill 可以包含 Prompt 片段、Tool schema 和 Workflow但它本身更接近“可加载的能力包”。2. Skill 的逻辑架构匹配不匹配通过失败用户请求Skill Router触发判断加载 Skill 元数据基础 Agent选择版本/依赖/优先级按需装载上下文任务计划工具与权限检查执行步骤观察结果验证/质量门禁最终输出修复/重试/澄清事件/Trace/日志Skill Registry经验/失败样本/评测集2.1 Skill 文件的推荐结构skill-name/ SKILL.md # 入口、触发范围、核心流程 references/ # 只有需要时才加载的详细资料 scripts/ # 可复用的确定性脚本 templates/ # 输出模板、检查清单 examples/ # 正例、反例、边界案例 tests/ # 触发和行为评测入口文件应该短、清晰、可执行。详细知识放入 references避免每次加载全部内容。脚本用于确定性动作不能把可计算的工作全部交给模型。3. Skill 的生命周期DraftTriggerTestBehaviorTestReviewPublishedObservedTunedDeprecatedArchived一个 Skill 不应“写完即结束”而应经历问题发现、草稿、触发测试、行为测试、人工评审、发布、线上观察、版本调优和废弃。4. 调优的核心指标4.1 触发质量True Positive该触发的任务被触发False Positive不该触发却触发False Negative应该触发却没有触发Ambiguous多个 Skill 都合理匹配。触发器的目标不是“尽可能触发”而是提高正确触发率并降低能力污染。4.2 行为质量流程完整率是否完成关键步骤工具正确率是否选择正确工具、参数和调用顺序约束遵守率是否遵守权限、格式和禁止事项验证通过率是否在结束前完成检查一次成功率是否需要用户反复纠正Token/Latency/Cost单位任务成本可恢复性失败、暂停和 Resume 后是否能继续。4.3 一个简单的综合目标Skill Quality 任务成功率 × 触发准确率 × 约束遵守率 - 成本惩罚 - 延迟惩罚 - 越权风险惩罚不要只用“模型回答看起来不错”作为指标。Skill 的价值是稳定地完成任务而非偶然生成漂亮文本。5. 调优原则一先定义边界再写内容最常见的问题是 Skill 目标过大例如“负责所有文档处理”。这会导致触发范围模糊、上下文过长、工具冲突和难以测试。好的边界应回答这个 Skill 服务哪类任务明确不服务什么输入和输出是什么哪些步骤必须执行哪些动作需要用户确认什么情况下应该停止并报告失败例如“PDF 读取和版面验证”比“文档专家”更容易触发和评估“生成 RAG 评测集”比“AI 工程 Skill”更可控。6. 调优原则二触发描述要像分类器不要像广告6.1 触发条件应包含正例和反例triggers:positive:-用户要求创建、编辑或验证 PDF-用户明确要求检查 PDF 的页面布局negative:-只需要回答一个与 PDF 无关的知识问题-用户要求生成 Markdown不涉及 PDF 文件仅写“当用户需要 PDF 时使用”不够因为模型需要知道“PDF 内容问答”和“PDF 排版验证”是否都属于范围。6.2 触发词不能代替意图识别关键词如“图”“文件”“设计”很宽泛。应描述任务意图、输入类型、预期输出和风险等级。触发描述越宽False Positive 越高越窄False Negative 越高。6.3 处理 Skill 冲突当多个 Skill 都匹配时应提供优先级原则具体任务 Skill 领域 Skill 通用 Skill 用户明确点名 语义推断 安全/合规 Skill 普通执行 Skill 验证 Skill 在修改 Skill 之后运行7. 调优原则三正文应写“决策点”而不是堆知识低质量 Skill 往往像百科全书解释很多但没有告诉 Agent 下一步做什么。高质量 Skill 的正文应优先包含什么时候做这一步什么时候不做输入准备好了吗调用哪个工具工具失败后怎么办结果如何验证何时向用户询问何时可以结束。推荐使用决策表情况动作输入文件存在且格式明确直接解析输入文件缺失请求用户补充需要外部最新资料使用搜索/连接器工具返回空结果检查参数并重试一次结果涉及破坏性操作暂停并请求确认验证失败不宣布完成进入修复8. 调优原则四上下文按需加载8.1 三层上下文L0Skill 元数据——名称、用途、触发范围、禁用条件 L1核心流程——当前任务完成所需的最小规则和工具契约 L2参考资料——只有遇到具体分支时才读取L0 参与路由L1 参与执行L2 通过条件触发加载。不要在 L0 放数千字的背景知识。8.2 上下文压缩策略删除重复的礼貌语和泛化建议将长段落改成条件-动作表将重复的工具参数放入 schema 或 reference以模板替代多组近似示例只保留能改变决策的知识。8.3 上下文不是越多越好上下文越长模型不一定越准确。冗余规则会产生优先级冲突过期示例会诱导错误行为多个类似工具会增加选择困难。调优时要观察“增加一段说明是否真的改变了成功率”。9. 调优原则五工具契约必须精确Skill 不应该只说“调用工具处理文件”而应说明{name:render_document,description:将文档渲染为页面图片用于版面检查只读输入不修改源文件,input_schema:{type:object,required:[path],properties:{path:{type:string},output_dir:{type:string}}}}应明确工具的前置条件、权限、输出结构、错误类型、幂等性、超时和副作用。Tool 名称相似时Skill 要写选择规则而不是把选择责任全部交给模型。10. 调优原则六把验证写成 Skill 的一等步骤“生成完成”不等于“任务完成”。验证应该具体到可执行检查defverify(result):assertresult.existsassertresult.mime_typeapplication/pdfassertresult.page_count0assertnotresult.has_overflowassertcitations_cover_claims(result)验证可以包括文件存在、格式正确、内容完整、引用有效、权限正确、没有越界修改和输出可渲染。遇到失败要回到修复步骤不应直接输出“已完成”。11. 一个完整的 Skill 执行示例假设 Skill 是“技术文档生成与校验”。用户说“根据这份设计说明生成 CSDN Markdown并制作封面。”Router 判断用户要创建 Markdown、生成图片、写入工作区匹配文档生成 Skill 和图片生成 Skill。Skill Resolver 选择文档 Skill 作为主流程图片 Skill 作为子能力。Context Loader 加载标题规范、Markdown 模板、图片比例要求和文件写入规则。Planner 生成读取材料 - 归纳结构 - 撰写 - 生成封面 - 写入图片 - 插入引用 - 校验链接和文件。Tool Manager 检查读取、写入和图像生成工具。Executor 依次执行确定性动作模型只负责归纳、表达和图像提示词。Validator 检查 Markdown 是否存在、图片是否存在、相对路径是否正确、标题是否清晰。如果图片生成失败保留正文报告图片失败不谎称已完成如果路径错误自动修复并再次验证。这个例子体现了 Skill 的边界模型负责判断和内容工具负责实际写入验证负责确认事实。12. 常见失败模式与修复失败模式现象根因修复Skill 太长模型忽略后半段上下文过载分成 L0/L1/L2触发太宽所有请求都加载描述缺少反例增加边界和优先级触发太窄用户点名仍不触发只写关键词加入意图和同义表达工具说明模糊参数和顺序错误缺少契约写 schema、前置和失败处理没有停止条件无限循环或重复调用只写“继续优化”加成功条件、预算和最大重试没有验证结果看似完成但不可用过程和结果混淆增加质量门禁示例太少边界任务表现差只有 happy path添加反例、错误、暂停样例多 Skill 冲突工具互相覆盖没有组合规则规定主 Skill、子 Skill 和优先级把安全写成建议高风险动作仍自动执行没有硬门禁工具层强制策略和审批版本不可追踪调优后不知道是否变好没有评测基线版本、数据集、指标绑定13. Skill 调优方法论从感觉驱动到数据驱动13.1 建立最小评测集每个 Skill 至少准备10 个明确正例10 个明确负例5 个与相邻 Skill 冲突的样例5 个工具失败样例5 个需要澄清或人工审批的样例5 个长上下文和多轮 Resume 样例。13.2 只改一个变量一次同时修改触发词、流程、工具描述和示例无法知道哪个改动起作用。推荐每轮只改一个变量并记录版本、样本、成功率、成本、延迟、失败类型。13.3 看失败分类不只看总分总成功率没有解释力。应把失败分为未触发、误触发、工具选错、参数错、流程漏步、权限错误、验证漏检、输出不合格和成本超标。13.4 保留回归测试Skill 调优可能修复一个场景却破坏另一个场景。每次发布都跑固定回归集并对关键安全场景设置“不可下降”的质量门槛。14. Skill 与 Harness、RAG、MCP 的关系Harness RuntimeSkill RouterSkillPrompt RulesTool ContractMCP CapabilityRAG ReferencesValidationExternal WorldHarness 负责 Skill 的加载、执行、状态、权限、事件和恢复Skill 负责任务领域的规则和流程MCP 提供可发现、可调用的外部能力RAG 提供动态知识证据Tool 执行真实动作Validator 判定结果是否达到完成标准。Skill 不是把所有能力都装进去而是编排这些能力完成某类任务。15. 推荐的 Skill 编写模板--- name: example-skill description: 说明服务对象、触发意图、明确不适用场景 --- # 目标 一句话说明最终结果。 # 触发范围 - 正例... - 反例... - 与相邻 Skill 冲突时... # 必须遵循的流程 1. 检查输入和权限 2. 建立计划 3. 调用工具 4. 处理失败/暂停 5. 验证结果 6. 输出交付物 # 工具规则 - 工具 A 何时使用 - 工具 B 何时禁止使用 - 参数、超时、幂等和副作用 # 输出规范 明确文件、格式、引用和错误报告方式。 # 完成条件 列出可验证的成功标准。 # 失败处理 列出重试、降级、澄清、审批和停止条件。 # 延迟加载资料 - references/xxx.md仅在遇到 xxx 时读取16. 最终心得Skill 调优的第一原则不是增加内容而是减少歧义。Skill 的竞争力来自流程、边界、工具契约和验证而不是华丽的措辞。能确定性执行的事情交给脚本和工具模型负责理解、选择和归纳。触发器决定“什么时候介入”正文决定“介入后怎么做”验证器决定“什么时候算完成”。任何无法被评测的规则都很难持续优化。任何没有失败处理的 Skill都只能算 Demo。Skill 应该小而专、可组合、可版本化避免成为新的“超级 Prompt”。最好的 Skill 不会让用户感觉 Agent 变得更复杂而是让复杂任务稳定地一次完成。参考资料Anthropic Claude Code Skills 概念OpenAI Agents SDKModel Context ProtocolLangGraph ConceptsAgent Skills Specification
