AI Agent 文档指南：llms.txt、AGENTS.md、SKILL.md 与 MCP 全解析

开发者工具的文档体系正在经历一轮结构性变化。过去 README、API 参考和快速入门是给人看的，现在它们还要被编码 Agent 读取、理解和执行。围绕这个需求，一批新的文档格式和协议正在快速成型：llms.txt、AGENTS.md、SKILL.md、MCP，以及尚在早期的 auth.md。理解它们各自解决什么问题，比盲目全盘接入更重要。

AI Agent 文档格式与协议综述

四类资源，各管一段路

把这些格式放在一起看，会发现它们对应的是 Agent 使用开发者产品时遇到的四个不同环节：

资源	主要用途	存放位置
`llms.txt`	帮 Agent 找到相关文档	网站或文档站
`llms-full.txt`	把文档合并为单文件	网站或文档站
`AGENTS.md`	提供仓库内的工作指令	仓库，按 Agent 规则加载
`SKILL.md`	定义可复用工作流及配套资源	Skill 目录
MCP	连接 Agent 与工具、数据	连接客户端的 MCP Server
`auth.md`	描述服务注册与认证方式	服务网站

此外，各主流编码 Agent 还有自己的专属指令文件：Claude Code 用 CLAUDE.md，Gemini CLI 用 GEMINI.md，Cursor 用 .cursor/rules/，GitHub Copilot 用 .github/copilot-instructions.md。这些文件在加载方式、作用范围和优先级上各不相同。

Agent 资源与开发者工作流的对应关系

llms.txt：给 Agent 一张文档地图

llms.txt 是一个 Markdown 文件，放在网站上，用简短介绍加链接列表的方式告诉 Agent「文档在哪里、哪些值得看」。Agent 可以按任务需要跟进相关链接，不必把整个站点塞进上下文。

原文给出了一个典型结构：标题、一句话产品说明，然后是分组链接，每条链接附带简短描述。配套的 llms-full.txt 把文档合并成一个文件，看似方便，但可能消耗大量不必要的上下文。Mintlify 等平台可以自动生成这两种文件。

需要清醒认识的是：**发布了 llms.txt 不等于 Agent 就会用它。**真正要验证的是 Agent 能否发现这个文件、是否跟进相关链接、能否找到完成任务所需的信息。

llms.txt 由 Answer.AI 的 Jeremy Howard 在 2024 年提出，定位类似网站的 robots.txt 或 sitemap.xml，但面向的是大语言模型而非搜索引擎爬虫。它约定放在站点根路径（如 example.com/llms.txt），采用纯 Markdown 格式，让 Agent 用一次轻量请求就能拿到整站文档的导航结构。与之配套的 llms-full.txt 则把所有文档正文拼接成单个文件，适合上下文窗口充裕、需要一次性吞下全部内容的场景。目前 llms.txt 并非任何官方标准，采纳与否完全取决于站点维护者，Anthropic、Stripe 等已有实践案例，但主流 Agent 是否主动探测该文件仍无统一约定。

AGENTS.md：仓库内的操作说明

当 Agent 开始在仓库里干活，它需要知道怎么装依赖、怎么跑测试、遵循什么编码规范。AGENTS.md 就是为这些指令准备的专用位置。

以 Quantiles 仓库的 AGENTS.md 为例，文件开头明确说明「本文件面向 Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI 等编码助手」，然后列出开始任务前应阅读的文件清单和改动规则。

不同 Agent 对 AGENTS.md 的加载和优先级处理并不一致——Codex 会分层加载仓库指引，其他 Agent 可能各有各的策略。指令写得太杂或长期不更新，反而会拖慢工作流、增加任务复杂度，甚至导致 Agent 在与产品交互时出错。

SKILL.md：让 Agent 完成多步工作流

有些任务不是一条仓库指令能覆盖的。Agent 可能需要安装 CLI、配置凭证、执行多个步骤、最后验证结果。Agent Skill 就是为这类场景设计的——提供可复用指令和配套资源。

一个典型的 Skill 目录结构包含 SKILL.md 主文件、references/ 下的补充文档、以及 scripts/ 下的辅助脚本。SKILL.md 里的名称、描述和指令中，描述尤其关键，它决定 Agent 能否判断出「什么时候该用这个 Skill」。

OpenAI Codex 和 Anthropic 的 Skill 实现都采用了「渐进式披露」：Agent 先看到简短描述，需要时才加载完整指令和配套资源。但前提是 Skill 装在 Agent 能发现的位置——光把 SKILL.md 扔进仓库，Agent 不一定找得到，即使找到了也未必判断得准该用、用对。

MCP：标准化地连接工具和数据

文档帮 Agent 理解产品，MCP 则提供标准化方式让 AI 应用连接到产品的工具和数据。MCP Server 可以暴露三类能力：

Tools（工具）：Agent 可调用的操作，如创建项目或启动评估
Resources（资源）：应用可获取的信息，如评估结果或执行日志
Prompts（提示模板）：引导特定任务或交互的复用模板

一个量化的例子：如果存在 Quantiles MCP Server，Agent 就能通过结构化工具调用创建和比较评估结果，而不必手动拼 API 请求或敲 CLI。当然，Agent 实际能用哪些能力，取决于它的 MCP 客户端支持什么。

MCP 和 SKILL.md 可以配合使用：Skill 告诉 Agent 该按什么顺序做哪些操作、怎么验证结果，MCP 提供执行这些步骤所需的工具入口。

MCP（Model Context Protocol）由 Anthropic 于 2024 年底开源，采用客户端—服务器架构：Agent 应用作为 MCP Client，产品方实现 MCP Server，双方通过 JSON-RPC 2.0 消息通信。协议定义了 Tools、Resources、Prompts 三类原语之外，还包含初始化握手、能力协商、采样（Sampling）等机制，使不同厂商的 Agent 能以统一方式接入外部能力，而不必为每家产品写定制集成代码。相较于传统的函数调用（Function Calling），MCP 把工具定义和调用逻辑从 Agent 内部抽离到独立服务，产品方可以独立迭代工具而无需改动 Agent 代码。授权方面，MCP 规范推荐使用 OAuth 2.1 保护远程 Server，这也正是文中强调 MCP 授权与 auth.md 属于不同层面的原因。

auth.md：Agent 如何注册和拿凭证

Agent 能找到文档、看懂 API，却卡在「注册账号、获取凭证」这一步——这是开发者经常遇到的现实问题。WorkOS 提出的 auth.md 就是冲着这个环节来的，目前还在早期采用阶段。

它让服务用 Markdown 文件描述注册、认证和可用权限，支持两种模式：

Agent verified：可信的 Agent 提供商验证用户身份，服务无需额外用户交互即可注册 Agent
User claimed：Agent 发起注册，用户登录并确认验证码来授权访问

两种方式最终都是让 Agent 拿到有作用域的访问令牌。但发布 auth.md 只是第一步，服务端仍需实现认证端点、令牌签发和权限校验。要注意区分 auth.md 和 MCP 授权：MCP 授权管的是访问受保护的 MCP Server，auth.md 管的是 Agent 如何先在服务里注册出一个身份。

作为新兴提案，它的兼容性和 Agent 支持度都还需验证。涉及账号归属、权限或计费时，人工审批环节可能仍然无法完全省略。

WorkOS 提出的 auth.md 针对的是 Agent 自主完成「服务注册」这一传统上为人类设计的流程。在 OAuth 等既有授权框架中，客户端通常需要预先注册并持有 client_id/secret，而 Agent 往往是临时起意、无预置身份的调用方，这就产生了「Agent 如何证明自己是可信代理、代表哪个用户」的问题。auth.md 通过 Markdown 描述端点，让 Agent 先读取再按图索骥完成注册，思路与 llms.txt 一脉相承。目前它与 OAuth 动态客户端注册（RFC 7591）、Agent 身份验证等领域提案存在功能重叠，最终能否形成事实标准尚不确定，采用前应评估服务端的实现成本和生态兼容性。

该用哪些格式，怎么评估效果

起点应该是「Agent 用你的产品时到底卡在哪」，而不是「别人有什么我也要有」。简单库可能只需要可访问的文档；流程复杂的开发者平台，才更需要 Skill、结构化工具和认证指引。

评估时建议从代表性工作流入手——安装产品、跑通快速入门、配置认证、使用高级能力——对比有和没有对应资源时的表现。重点关注四个维度：

发现与激活：Agent 是否找到并使用了相关文档、Skill 或工具？
任务成功与可靠性：多次试验中能否稳定正确地完成任务？
效率：消耗了多少时间、token 和工具调用？
错误与恢复：Agent 在哪里卡住，能否在没有人工干预的情况下恢复？

这些资源不是互斥的，也不是每个产品都需要全套。加更多指令不总是更好的答案，关键在于已有的那些是否真正帮 Agent 完成了开发者任务。

随着 Agent 快速演进，今天对某个 Agent 有效的方案，明天换一个 Agent 或同一 Agent 升级后可能就失效了。维护一组有代表性的开发者任务，在产品、文档和 Agent 变化时重跑评估，用执行轨迹定位问题——有时问题需要靠指令解决，有时一条更清晰的报错、更简单的安装流程、或更有用的工具返回，反而是更有效的答案。