capabilities-txt-registry

capabilities.txt

一种简单、开放的约定，供网站在众所周知的位置声明自己能做什么——即 Agent 可以发现并调用的能力。

Web 让机器能够分层读取信息。robots.txt 说明爬虫可以访问什么。sitemap.xml 说明有哪些内容。llms.txt 说明哪些内容值得阅读。每个文件都回答自动化读取程序的一个特定问题。

但它们都没有回答 Agent 现在提出的问题：这个主机实际上能做什么？

Agent 不再只是阅读 Web，也开始在 Web 上执行操作。访问你的网站的 Agent 可以总结你的文档，但没有标准方式来发现你提供了“创建支持工单”“检查库存”或“发起退货”等能力，也不知道如何调用这些能力。如今，这需要逐家供应商单独定制集成。

capabilities.txt 补上了缺失的一层：一个公开的、位于众所周知位置的文件，由主机声明其提供的能力，让任何 Agent 都能发现它可以做什么。

它刻意保持精简。llms.txt 能发挥作用，是因为只需一个下午就能采用。capabilities.txt 遵循同样的原则。

两种形式

主机可以发布其中一种或两种：

• /capabilities.txt — 供人和 Agent 阅读的 markdown：按类别分组的能力，每项包含 ID、版本和一行描述。
• /.well-known/capabilities.json — 结构化形式：能力引用数组，每项都可解析到完整描述符。

markdown 形式用于发现和阅读。JSON 形式适用于需要结构化信息的机器。仅发布 markdown 形式也是很好的起步方式。

格式（/capabilities.txt）

# capabilities.txt

> One sentence: what this host is and what kind of capabilities it offers.
> Structured form: https://example.com/.well-known/capabilities.json

## <Category>

### <Group name> (<group-id>)

- <capability-id> (v<version>) — <one-line description>
- <capability-id> (v<version>) — <one-line description>

规则尽量精简：

1. 第 1 行是 # capabilities.txt。
2. 后接一个引用块（>）摘要：用一句话说明主机提供什么，并可附上链接（JSON 形式、文档、调用端点）。
3. ## 标题按类别分组能力（类别名称自由选择）。
4. ### 标题用于命名组，可选稳定的 (group-id)。
5. 每项能力都是一个列表项：包含稳定的 capability-id、可选的 (v<version>)，以及一段简短的 — 描述。
6. 它就是普通的 markdown。只要人能读懂、Agent 能解析，就是有效格式。

结构化形式（/.well-known/capabilities.json）

{
  "version": "1",
  "capabilities": [
    {
      "id": "support.create_ticket",
      "version": "1.2.0",
      "description": "Open a support ticket",
      "descriptor": "https://example.com/.well-known/capabilities/support.create_ticket.json"
    }
  ]
}

每个条目都是一个引用；descriptor（可选）指向完整的机器可读描述，说明输入、权限以及调用方式。

它在标准体系中的位置

文件	回答的问题	面向对象
robots.txt	爬虫可以访问什么？	爬虫
sitemap.xml	有哪些页面？	搜索引擎
llms.txt	哪些内容值得阅读？	读取内容的大模型
capabilities.txt	这个主机能做什么？	执行操作的 Agent

它不是 MCP 或 API 规范的替代品。Model Context Protocol 是一种有状态的连接与调用协议；OpenAPI 描述 HTTP API。capabilities.txt 位于调用之前这一层——它是一个静态、公开且可抓取的说明文件，Agent（或搜索引擎）无需建立实时连接即可读取，并由此指向你的 MCP 服务、HTTP API 或其他实际调用端点。发现与调用是不同的任务。capabilities.txt 负责发现；调用则交由其他端点处理。

采用它

最快的方式（无需规范）： 复制 capabilitiestxt.org/implement 上的提示词， 并交给你的 AI 编码 Agent — 它会根据你的代码编写 capabilities.txt。

有 OpenAPI 规范？ 在浏览器中生成 （粘贴 URL）— 或使用 GitHub Action 在 CI 中自动保持文件为最新：

- uses: capabilityhostprotocol/capabilities-txt/action@main
  with:
    openapi: https://api.yoursite.com/openapi.json
    output: public/capabilities.txt

然后在 capabilitiestxt.org/submit 检查文件，获取评级、修复建议和徽章 — 之后便可在目录和地图中发现它。

手动操作：

1. 列出你的网站提供（或能够提供）的功能。
2. 按照上述格式将它们写入 /capabilities.txt。
3. 可选：发布 /.well-known/capabilities.json。
4. 通过拉取请求，将你自己添加到 adopters.md。

已经有 OpenAPI 规范？ 直接生成 — 无需手动编写：

python tools/from_openapi.py https://api.yoursite.com/openapi.json > capabilities.txt
python tools/validate.py capabilities.txt   # check it

examples/ 中提供了可供参考的示例 — 包括真实、在线的 capabilities.txt，以及涵盖多个行业（电子商务、支持服务、银行、医疗保健、开发平台）的示范模板。 tools/ 中的工具可生成和验证文件。

后续方向

发现是第一步。Agent 知道你能做什么之后，接下来要问的是：我可以吗、发生了什么，以及我能证明吗 — 也就是调用、治理和证据。这些内容由 Capability Host Protocol (CHP) 定义。CHP 是一种开源协议，而 capabilities.txt 是它自然的公开门面。你可以单独采用 capabilities.txt；如果你还需要其余部分，它将引导你使用 CHP。

状态与许可证

这是一个附有可用参考实现的提案，并非已完成的标准 — 你的反馈能让它变得更好。欢迎提交议题或 PR。

• 规范与网站文本（README.md、index.html、SPEC.md）：CC BY 4.0 — 详见 LICENSE-DOCS。
• 工具（tools/）：Apache-2.0 — 详见 LICENSE。
• “capabilities.txt”是一种免费、开放的惯例 — 欢迎自由使用。（无商标限制。）

版权所有 © 2026 Project Auxo, Inc. 及贡献者。