Agent技能管理与评估指南

1. 简介

本文档旨在提供一套关于 AI Agent Skills 的全面管理与评估指南。随着人工智能技术的发展，Agent Skills 在自动化、知识检索增强生成（RAG）以及复杂任务执行中扮演着核心角色。本指南将从技能的批量维护、动态路由、发现与发布，到详细的测试评估流程及最佳实践，提供结构化的方法和建议，以帮助开发者和知识工作者高效地利用和优化 Agent Skills。

2. 使用场景

2.1. 批量维护 Agent Skills

为了有效地管理多样化的 Agent Skills，尤其是跨工具、*跨项目或多层级的技能库，以下策略被推荐：

• 集中式管理工具: 利用 skill-manager 等工具在本地进行统一管理，可以涵盖不同工具、层级及领域的技能。
• 版本控制与同步: 结合 GitHub 进行技能仓库的同步与版本控制，确保技能的可追溯性和团队协作的效率。
  • 技能仓库组织方案考量:
    • 自有技能与第三方技能集成: 需考虑如何平衡管理自研技能与集成第三方技能（可能需要本地化调整及跟踪上游更新）。
    • 兼容性: 确保方案适配 skill.sh 规范与 gh 安装方案
  • 推荐方案:
    • Fork + 独立分支 + 多仓库: 这种方案提供了最大的灵活性，但管理成本相对较高。
    • Git Subtree: 适用于将外部仓库作为子目录引入，但独立性较差。
    • 直接使用 skill-manager: 强烈推荐。它能够自动同步指定仓库的技能到本地，支持修改、跟踪差异，并推送到备份仓库，极大地简化了管理流程。

2.2. 实现动态路由方案

动态路由是提升 Agent 智能与适应性的关键。以下是几种实现动态路由的策略：

• 小型 LLM 作为前置过滤器: 利用参数量较小的语言模型作为请求的前置过滤器，快速判断请求意图，将任务路由至合适的技能。
• skill-router 专用技能: 推荐 使用一个专门设计的 skill-router 技能，它能够根据输入上下文智能地选择并调用其他技能。
• 向量数据库（Vector Database）: 将技能描述或其功能嵌入到向量空间中，通过语义相似度匹配来动态选择技能。
• 标签匹配服务器: 构建一个基于标签或关键词的匹配服务，根据任务描述中的关键词来路由技能。

3. 寻找优质 Agent Skills

寻找高质量的 Agent Skills 对于构建强大的 Agent 系统至关重要：

• skill.sh 站点: 访问 skill.sh 官方站点是发现和探索社区贡献技能的首选途径。

3.1. 发布自己的 Agent Skills

发布技能无需复杂的流程，核心在于遵循规范：

• 标准化发布: 开发者只需按照既定的规范（例如 agentskills 社区规范）将技能发布到自己的代码仓库即可。

4. 测试与评估 Agent Skills

全面的测试与评估是确保 Agent Skills 质量和可靠性的基础。

4.1. Description 测试

技能的 description 是 Agent 发现和使用技能的关键。因此，对其进行测试至关重要：

• 正向查询: 验证 description 是否能准确响应预期的查询。
  • 措辞: 评估 description 的语言是否清晰、准确。
  • 准确性: 检查 description 模糊的反应意图，评估泛化能力。
  • 细节: 判断 description 提供更丰富的细节，试图抢夺注意力。
  • 复杂度: 评估 description 对复杂场景、多步骤、长链条的适配能力的。
• 负向查询: 测试在包含关键词但真实意图不匹配的情况下，Agent 是否能正确地不调用该技能。
  • 案例: 例如，当查询包含技能关键词但实际任务与技能功能无关时。
• 真实逼近: 使用包含真实场景细节、背景信息或口语化表达的查询来测试 description。
• 测试方法:
  • 训练与验证划分: 将测试数据集划分为训练集和验证集。
  • 多次运行: 由于大模型的不确定性，需进行对一个测试案例多次运行来验证结果的稳定性。
  • 多次迭代: 根据测试结果不断优化 description。

4.2. 评估流程

一个系统的评估流程有助于持续改进 Agent Skills：

1. 设计测试用例:
   • 包含元素: 每个测试用例应包含 prompt（用户输入）、预期输出 和 输入（传递给技能的参数）。
   • 经验:
     • 首次评估可从小批量（2-3个）测试用例开始。
     • 持续调整 prompt 以优化 Agent 行为。
     • 覆盖边缘案例和异常情况。
     • 使用真实的上下文信息。
2. 运行评估:
   • 工作区结构: 好的结构方便当后期的测试与维护。可以参考 agentskills 社区案例
   • 对比运行: 对比“使用技能运行”与“不使用技能运行”（或“使用旧技能运行”）的结果。
   • 干净的上下文: 每次评估都应从干净的 Agent 上下文开始。
   • 记录实践数据: 详细记录每次运行的输入、输出、时间消耗、Token 消耗等数据。
3. 编写断言: 在第一轮评估后，根据预期行为编写自动化断言，用于验证技能的输出。
4. 评分输出:
   • 具体证据: 评分应基于具体的证据和事实，要严格把控。
   • 同步优化断言: 在审查结果的同时，同步优化断言，使其更精确。
5. 聚合结果:
   • 存储: 将评估结果存储在结构化的文件（例如 benchmark.json）中。
   • 粒度: 记录技能是否通过、时间花费、Token 消耗等粒度信息。
   • 指标: 计算平均值、方差等统计指标。
6. 审查模式:
   • 移除冗余断言: 移除两种配置（使用/不使用技能）都可以通过的断言，它们不提供信息且拉高通过率。
   • 调整困难断言: 调整两种配置都失败的断言，可能说明断言过于严格。
   • 识别价值区域: 找出有技能时成功、没有时失败的断言，这些是真正体现技能价值的地方。
   • 检查异常值: 分析时间与 Token 消耗的异常值，找出性能瓶颈。
7. 人工审查: 引入人类反馈，对机器评估结果进行补充和修正。
8. 迭代: 持续优化信息来源（失败断言、人类反馈、执行记录），并利用 LLM 给出分析与优化建议，形成闭环改进。

5. 最佳实践

5.1. 生成来源

• 从实际任务中提取: 技能应来源于解决实际问题和完成任务的需求。
• 从现有项目中综合: 从现有代码库或项目中提炼可复用的功能作为技能。

5.2. 上下文原则

• 补充 Agent 缺失，省略 Agent 已知: 在为技能设计上下文时，只提供 Agent 缺乏的信息，避免重复 Agent 已知内容。
• 设计合适范围的技能: 技能的职责范围应适中，并考虑与其他技能的协作。
• 追求适度细节: 避免过于详细的文档，而是提供足以理解和使用的关键信息。
• 渐进式披露: 必要时，可以采用渐进式披露策略，按需提供更多细节。

5.3. 控制原则

• 特定性匹配脆弱性: 灵活的任务解释（说明原因和目的）通常比严格的限制更有效。
• 提供默认值而非菜单: 优先为技能参数提供合理的默认值，而不是罗列所有的选择。
• 优先考虑流程而不是声明: 技能的实现细节可以是特定的，但其解决问题的方法和流程应尽可能通用。

5.4. 复用原则

• 高价值注意事项: 高价值部分是那些细化的注意事项。
• 特定输出格式应使用模板: 对于需要特定输出格式的技能，应使用模板来确保一致性。
• 检查清单**: 明确技能任务清单，防止依赖。
• 循环验证: 确保技能通过循环验证，直到符合预定义的验证器规则。
• 复杂任务策略: 对于复杂任务，采用“规划 -> 验证 -> 执行”的策略。
• 统计抽象可复用脚本: 从多次测试中统计抽象出通用的、可复用的脚本。

5.5. Description 编写指南

• 使用祈使句: 采用“当…时候，执行…”的祈使句式来描述技能功能。
• 聚焦用户意图: description 应直接回应用户的核心意图。
• 宁可过于主动，详细明确场景: 即使用户没有明确提及，也要主动预设并详细说明技能适用的场景。
• 保持简洁: 描述应简洁明了，避免冗余。

5.6. Scripts 编写指南

• 优先使用一次性命令: 优先调用已有的 CLI 工具或一次性命令，而不是编写复杂的脚本。
• 自包含脚本: 脚本应具备自包含性，减少外部依赖。
• 避免交互式提示: 脚本应设计为非交互式运行。
• 简洁有效的 --help 文档: 提供清晰简洁的 --help 文档。
• 有价值的错误信息: 脚本应返回有价值的错误信息，便于调试。
• 结构化输出: 尽可能提供结构化的输出，便于 Agent 解析。

6. 拓展信息

6.1. Agent Skill 目录规范

• 平铺结构: 技能目录应采用平铺结构，避免深层嵌套。所有命名建议考虑领域划分需求。

7. 参考资料

• skill 的定义规范
• skill manager
• gh skill 文档