代理人工具包：技能与推荐信的文件夹标准

智能体框架是一种为人工智能系统的行为和思维方式添加结构的方式，使得一个底层模型能够用于多种不同的任务。这一概念建立在一些早期理论之上，因此首先需要了解这些基础内容：什么是大语言模型、什么是智能体、推理与工具使用是如何结合的，以及哪些技能是必要的。掌握了这些之后，智能体框架本身只是一个小步骤，一个简单的文件夹结构就足以对其进行描述。

基础概念

作为函数的语言模型

为此，大语言模型可以被视作一种函数：输入文本，输出文本。它所做的仅仅是用文本回应文本，然而最近涌现的大多数人工智能产品都是基于这种单一功能构建的。

何为智能体

“智能体”仍然是一个含义宽泛的词汇。学术研究描述了多种运作方式截然不同的类型。但在日常对话中，几乎所有人指的是同一回事：一种接收消息、执行某些操作并回复的聊天系统。这种模式通常被称为ReAct，即通过一层简短的代码将模型与功能相连，使其能够进行推理、采取行动并观察结果。ReAct让模型能够思考自己要做什么，选择一种能影响环境的动作，然后再读取关于该结果的观察信息。下文中的“智能体”均指这种类似ReAct的概念。

推理与行动

这一机制背后包含两个核心理念。推理通常通过思维链来实现，即引导模型在给出答案之前逐步推导解决方案。最初提出该方法的论文是在提示词中加入一个已解决的示例，而原本在普通提示下无法解答的问题，在加入了该示例后使用同一模型就能得到正确答案。

这项技术现已变得极为重要，许多模型都被训练成能够自主生成思维链。普通模型倾向于在回复前先完整思考问题，而DeepSeek推广的推理模型则设有专门阶段，让模型通过极长的思维链来逐步解决问题。

工具使用也有类似的发展历程：它出现已有一段时间，持续展现出实用性，并逐渐成为标准。最简单的形式是告诉模型，如果它输出特定文本，就会运行某些代码并得到结果。随后模型会决定何时上网搜索、查阅文件，或者在最糟糕的情况下将资金转往不该去的地方。复杂问题往往需要推理与行动相结合，而对提示策略的比较表明，两者的结合比单独使用任何一种效果都更好。

技能

随着智能体、工具使用及提示技术的成熟，各种实践方式也逐渐成形。假设某个智能体需要向数据库中添加行数据，它就需要能够让模型查看和操作数据库的工具，同时还需要描述数据库结构及可用工具的提示语。

技能是一种用于组织该数据包的标准方式。信息与功能被整合为一个整体，从而使智能体能够以完整的形式接收它。技能就是一个文件夹：

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

大多数技能实际上都只是文本文件。即便如此，它们仍能让智能体理解并操作复杂的系统，同时为智能体开发者提供可重复使用、可移植的规划与流程框架。

什么是工具包

工具包可被视为技能的延伸。一个技能会封装诸如编辑网站、管理数据库或分析客户反馈之类的广泛功能。而像担任产品开发者的助手这类复杂工作，则可能需要多种技能协同使用。工具包会将多个技能以及智能体理解自身角色及所处环境所需的参考资料整合在一起。

智能体工具包格式

根据这项拟议中的标准，一个工具包由三部分组成：用于描述它的 Markdown 文件、一套用于与环境交互的技能，以及一组帮助智能体了解其工作环境的参考资料。该标准是一个公开维护的开源项目。

my-harness/
├── HARNESS.md        # Required: metadata + instructions
├── skills/           # Optional: a set of skills
└── references/       # Optional: a set of reference documents

顶层文件HARNESS.md应当保持简短。它能让智能体快速了解问题的整体情况，并指出在各个技能和参考资料中何处可以找到具体内容。

其设计遵循渐进式披露原则，这一模式近期由Agent Skills标准推广开来。整个过程分为三个阶段：

1. 发现阶段。启动时，智能体仅加载HARNESS.md，该文件会说明整个框架的结构。当收到提示后，智能体会将这些提示与文件中的描述进行匹配，逐步查看各项技能和参考资料的名称及描述，直至找到所需内容。
2. 激活阶段。找到相关资料后，会加载并读取这些技能和参考资料的完整文档。
3. 执行阶段。智能体会按照框架的指示来运行相应的技能。

HARNESS.md文件

与技能类似，该工具也使用了前置内容，即放在 Markdown 文件顶部的关键信息，以便智能体能够高效地扫描相关资源。

---
name: <name of the harness>
description: <description of what the harness is for>
---

<body>

名称和描述是必填项，这样客服就能立即知道该安全带的具体类型。正文部分则是对主要构成的简要说明，为客服提供指引，告诉其应使用哪些技能和参考资料。

技能目录

该目录收录了符合“客服技能标准”的各类技能，该标准对这类技能有如下定义：

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

背带系统在此基础上进一步发展，因此技能目录如下所示：

my-harness/
├── HARNESS.md
├── skills/
|  ├── my-skill-1/
|  |  ├── SKILL.md
|  |  ├── scripts/
|  |  ├── references/
|  |  ├── assets/
|  |  └── ...
|  └── my-skill-2/
|     ├── SKILL.md
|     ├── scripts/
|     ├── references/
|     ├── assets/
|     └── ...
└── references/

参考资料目录

参考资料目录中包含各种文档，这些文档有助于智能体理解其所在环境、自身角色以及其他高层级背景信息。

技能本身也包含参考资料，且这两者的范围有所不同。技能内部的参考资料用于说明如何使用该特定技能，而框架层面的参考资料则应在更高抽象层次上涵盖多个技能共有的需求。

以一个用于生成营销内容的智能体为例，它可能拥有一个用于撰写博客文章的技能、一个用于生成图片的技能以及一个用于扫描社交媒体的技能：

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/

每种技能都可以有自己的参考资料。社交扫描技能可能会列出公司的账号，图片处理技能可能会说明成品图片的存储位置，而博客管理技能则可能会描述发布流程。至于在三种技能中都会用到的内容，比如风格指南和品牌优先级，它们则属于框架层级的参考资料。

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/
   ├── style-guide.md
   └── brand-priorities.md

任何内容都可以放入 harness 级别的参考目录中，但强烈建议使用 Markdown 格式，并在每个文件顶部添加简短描述，以便智能体能够快速判断其相关性。本示例中的风格指南可以这样开头：

---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---

<body>

管理大型工具集

一个工具集可能包含大量的技能和参考资料。一旦规模变得过大，维护工作就会变得混乱，向代理传递信息也会效率低下。

my-harness/
├── HARNESS.md
├── skills/
|  ├── skill1/
|  ├── skill2/
|  ├── skill3/
|  └── ...
└── references/
   ├── reference1
   ├── reference2
   ├── reference3
   └── ...

答案就是子目录。在“技能”和“参考资料”中，文件夹都可以将项目分组为子集：

my-harness/
├── HARNESS.md
├── skills/
│   ├── software-development/
│   │   ├── SKILLS.md
│   │   ├── skill1/
│   │   │   └── SKILL.md
│   │   └── skill2/
│   │       └── SKILL.md
│   ├── market-analysis/
│   │   ├── SKILLS.md
│   │   └── skill3/
│   │       └── SKILL.md
│   └── social-media/
│       ├── SKILLS.md
│       ├── skill4/
│       │   └── SKILL.md
│       └── skill5/
│           └── SKILL.md
└── references/
    ├── brand-assets/
    │   ├── REFERENCES.md
    │   ├── reference1.md
    │   └── reference2.md
    ├── software-infrastructure/
    │   ├── REFERENCES.md
    │   ├── reference3.md
    │   └── reference4.md
    └── product-information/
        ├── REFERENCES.md
        └── reference5.md

为使智能体能够高效且完整地理解这一结构，HARNESS.md 应对其进行说明。每个子目录也包含一个描述文件：SKILLS.md 用于介绍该子目录中的技能，而 REFERENCES.md 则记录其参考资料。

这正是渐进式披露的优势所在。智能体首先阅读顶层文件以了解整体结构，仅在需要时才打开具体的 SKILLS.md 和 REFERENCES.md 文件，从而高效地获取相关内容。

嵌套层级可根据内容的复杂程度进行调整，因此庞大的资料集也能被有序组织。每个子目录都应拥有自己的 SKILLS.md 或 REFERENCES.md，这样智能体在逐层深入时就能理解每一层的内容：

...
└── references/
  └── data-sources/
      ├── REFERENCES.md
      ├── relational/
      │   ├── REFERENCES.md
      │   └── schema-overview.md
      └── warehouse/
          ├── REFERENCES.md
          └── dataset-catalog.md

为何这种布局行之有效

这种格式对作者的要求极低。所有内容都存放在文件夹中的文本文件里，这意味着此类工具包可以像其他项目一样进行版本控制、审核和共享。代理程序无需加载整个集合，因为每个描述文件都相当于一个小型指引，能帮助它决定是否继续处理后续内容。面向营销团队的工具包与面向数据库管理员的工具包仅在内容上有所区别，而发现、激活和执行流程则完全相同。

有两个习惯能让工具包保持良好状态。首先，撰写描述时需明确说明相关材料适用的场景，而不仅仅是其包含的内容，因为代理程序仅根据这些描述来决定要打开哪些文件。其次，确保工具包层面的引用真正实现共享。如果某份文档仅适用于某一项技能，那就应将其放在该技能对应的目录中，否则向上层级提升只会给其他查询带来不必要的干扰。