不要把 Skill 写成 Prompt：Agent Skill 调优的系统方法与实战心得

Skill 是 Agent 可按需加载的一组领域规则、工作流、工具说明、约束和验证方法。真正有效的 Skill，不是写得越长越好，而是让模型在正确的任务上被正确触发、以最小上下文完成最可靠的动作。本文总结 Skill 调优中的核心规律、失败模式和可复用方法。

1. 我对 Skill 的重新理解

1.1 Skill 不只是 Prompt

Prompt 主要描述一次请求应该怎样回答；Skill 描述一类任务应该怎样完成。一个生产级 Skill 至少包含：

Skill = 触发条件 + 工作目标 + 专业知识 + 操作流程 + 工具契约 + 输出格式 + 验证方法 + 边界/失败处理

Skill 的关键价值是“按需加载”。如果所有规则都放进系统 Prompt，上下文会膨胀，任务之间会互相污染；如果没有 Skill，模型只能依赖泛化能力，容易漏步骤、误用工具或无法判断什么时候应该停止。

1.2 Skill 解决的问题

• 把重复性的专家经验编码成可复用资产；
• 让 Agent 具备领域流程，而不是只会自由发挥；
• 将复杂任务拆成可验证步骤；
• 控制工具调用的前置条件、权限和结果处理；
• 让不同 Skill 之间可以组合、隔离和版本化；
• 通过失败样本和评测集持续迭代。

1.3 Skill、Rule、Prompt、Tool、Workflow 的区别

Skill 可以包含 Prompt 片段、Tool schema 和 Workflow，但它本身更接近“可加载的能力包”。

2. Skill 的逻辑架构

2.1 Skill 文件的推荐结构

skill-name/ SKILL.md # 入口、触发范围、核心流程 references/ # 只有需要时才加载的详细资料 scripts/ # 可复用的确定性脚本 templates/ # 输出模板、检查清单 examples/ # 正例、反例、边界案例 tests/ # 触发和行为评测

入口文件应该短、清晰、可执行。详细知识放入 references，避免每次加载全部内容。脚本用于确定性动作，不能把可计算的工作全部交给模型。

3. Skill 的生命周期

一个 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 目标过大，例如“负责所有文档处理”。这会导致触发范围模糊、上下文过长、工具冲突和难以测试。

好的边界应回答：

1. 这个 Skill 服务哪类任务？
2. 明确不服务什么？
3. 输入和输出是什么？
4. 哪些步骤必须执行？
5. 哪些动作需要用户确认？
6. 什么情况下应该停止并报告失败？

例如，“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 三层上下文

L0：Skill 元数据——名称、用途、触发范围、禁用条件 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_type=="application/pdf"assertresult.page_count>0assertnotresult.has_overflowassertcitations_cover_claims(result)

验证可以包括文件存在、格式正确、内容完整、引用有效、权限正确、没有越界修改和输出可渲染。遇到失败要回到修复步骤，不应直接输出“已完成”。

11. 一个完整的 Skill 执行示例

假设 Skill 是“技术文档生成与校验”。用户说：“根据这份设计说明生成 CSDN Markdown，并制作封面。”

1. Router 判断用户要创建 Markdown、生成图片、写入工作区，匹配文档生成 Skill 和图片生成 Skill。
2. Skill Resolver 选择文档 Skill 作为主流程，图片 Skill 作为子能力。
3. Context Loader 加载标题规范、Markdown 模板、图片比例要求和文件写入规则。
4. Planner 生成：读取材料 -> 归纳结构 -> 撰写 -> 生成封面 -> 写入图片 -> 插入引用 -> 校验链接和文件。
5. Tool Manager 检查读取、写入和图像生成工具。
6. Executor 依次执行确定性动作，模型只负责归纳、表达和图像提示词。
7. Validator 检查 Markdown 是否存在、图片是否存在、相对路径是否正确、标题是否清晰。
8. 如果图片生成失败，保留正文，报告图片失败，不谎称已完成；如果路径错误，自动修复并再次验证。

这个例子体现了 Skill 的边界：模型负责判断和内容，工具负责实际写入，验证负责确认事实。

12. 常见失败模式与修复

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 负责 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. 最终心得

1. Skill 调优的第一原则不是增加内容，而是减少歧义。
2. Skill 的竞争力来自流程、边界、工具契约和验证，而不是华丽的措辞。
3. 能确定性执行的事情交给脚本和工具，模型负责理解、选择和归纳。
4. 触发器决定“什么时候介入”，正文决定“介入后怎么做”，验证器决定“什么时候算完成”。
5. 任何无法被评测的规则，都很难持续优化。
6. 任何没有失败处理的 Skill，都只能算 Demo。
7. Skill 应该小而专、可组合、可版本化，避免成为新的“超级 Prompt”。
8. 最好的 Skill 不会让用户感觉 Agent 变得更复杂，而是让复杂任务稳定地一次完成。

参考资料

• Anthropic Claude Code Skills 概念
• OpenAI Agents SDK
• Model Context Protocol
• LangGraph Concepts
• Agent Skills Specification