【译】AGENTS.md 在 Agent 评测中优于 Skills

原文：AGENTS.md outperforms skills in our agent evals 作者：Jude Gao 发布日期：2026 年 1 月 27 日

我们原本期望 skills 能成为教授 coding agent 框架特定知识的解决方案。在构建专注于 Next.js 16 API 的评测后，我们发现了意想不到的结果。

一个压缩到 8KB 的文档索引直接嵌入 AGENTS.md 后，实现了 100% 的通过率，而 skills 即使在明确指示 agent 使用它们的情况下，最高也只达到 79%。如果没有这些指示，skills 的表现与完全没有文档时相当。

以下是我们尝试的内容、学到的经验，以及如何为你自己的 Next.js 项目进行设置。

我们试图解决的问题

AI coding agent 依赖于会过时的训练数据。Next.js 16 引入了 'use cache'、connection() 和 forbidden() 等 API，这些都不在当前模型的训练数据中。当 agent 不了解这些 API 时，它们会生成错误的代码或回退到旧的模式。

反过来的情况也可能发生：你正在运行较旧的 Next.js 版本，而模型却建议使用你项目中尚不存在的新 API。我们希望通过让 agent 访问与版本匹配的文档来解决这个问题。

教授 Agent 框架知识的两种方法

在深入讨论结果之前，先简要解释一下我们测试的两种方法：

• Skills 是一种开放标准，用于打包 coding agent 可以使用的领域知识。一个 skill 捆绑了 agent 可以按需调用的提示词、工具和文档。其理念是 agent 识别到需要框架特定帮助时，调用该 skill，然后获取相关文档。
• AGENTS.md 是项目根目录中的一个 markdown 文件，为 coding agent 提供持久的上下文。无论你在 AGENTS.md 中放入什么内容，agent 在每一轮对话中都可以访问，无需 agent 决定是否加载它。Claude Code 使用 CLAUDE.md 实现相同的目的。

我们构建了一个 Next.js 文档 skill 和一个 AGENTS.md 文档索引，然后通过我们的评测套件进行测试，看看哪个表现更好。

我们最初押注于 Skills

Skills 看起来是正确的抽象。你将框架文档打包成一个 skill，agent 在处理 Next.js 任务时调用它，然后你就能得到正确的代码。关注点清晰分离，上下文开销最小，agent 只加载需要的内容。在 skills.sh 上甚至有一个不断增长的可复用 skills 目录。

我们期望 agent 遇到 Next.js 任务时，调用 skill，阅读版本匹配的文档，然后生成正确的代码。

然后我们运行了评测。

Skills 没有被可靠地触发

在 56% 的评测案例中，skill 从未被调用。Agent 可以访问文档，但没有使用它。添加 skill 相比基线没有任何改进：

零改进。Skill 存在，agent 可以使用它，但 agent 选择不使用。在详细的 Build/Lint/Test 分解中，skill 在某些指标上实际上比基线更差（测试 58% vs 63%），这表明环境中未使用的 skill 可能会引入噪音或干扰。

这不是我们设置特有的问题。Agent 不能可靠地使用可用工具是当前模型的已知限制。

明确指示有帮助，但措辞很脆弱

我们尝试在 AGENTS.md 中添加明确指示，告诉 agent 使用该 skill。

在编写代码之前，先探索项目结构，
然后调用 nextjs-doc skill 获取文档。

这将触发率提高到 95% 以上，并将通过率提升到 79%。

这是一个显著的改进。但我们发现了指示措辞如何影响 agent 行为的意外情况。

不同的措辞产生了截然不同的结果：

相同的 skill。相同的文档。但基于微妙的措辞变化产生了不同的结果。

在一个评测（'use cache' 指令测试）中，“先调用”方法写出了正确的 page.tsx，但完全错过了所需的 next.config.ts 更改。而”先探索”方法两者都完成了。

这种脆弱性让我们担忧。如果微小的措辞调整会产生大的行为波动，这种方法在生产使用中会显得脆弱。

构建可信赖的评测

在得出结论之前，我们需要可信赖的评测。我们最初的测试套件有模糊的提示、验证实现细节而非可观察行为的测试，以及对已在模型训练数据中的 API 的关注。我们没有衡量我们真正关心的东西。

我们通过消除测试泄漏、解决矛盾、转向基于行为的断言来强化评测套件。最重要的是，我们添加了针对不在模型训练数据中的 Next.js 16 API 的测试。

我们专注评测套件中的 API：

• connection() 用于动态渲染
• 'use cache' 指令
• cacheLife() 和 cacheTag()
• forbidden() 和 unauthorized()
• proxy.ts 用于 API 代理
• 异步 cookies() 和 headers()
• after()、updateTag()、refresh()

以下所有结果都来自这个强化的评测套件。每个配置都针对相同的测试进行评判，并进行重试以排除模型方差。

回报的直觉

如果我们完全移除决策会怎样？与其希望 agent 调用 skill，我们可以将文档索引直接嵌入 AGENTS.md。不是完整的文档，只是一个索引，告诉 agent 在哪里可以找到与你项目 Next.js 版本匹配的特定文档文件。然后 agent 可以根据需要读取这些文件，无论你使用的是最新版本还是维护较旧的项目，都能获得版本准确的信息。

我们在注入的内容中添加了一条关键指示。

重要：对于任何 Next.js 任务，优先使用检索导向的推理而非预训练导向的推理。

这告诉 agent 查阅文档，而不是依赖可能过时的训练数据。

结果让我们惊讶

我们在所有四种配置上运行了强化的评测套件：

最终通过率：

在详细分解中，AGENTS.md 在 Build、Lint 和 Test 上都取得了满分。

这不是我们预期的结果。“笨”方法（静态 markdown 文件）超越了更复杂的基于 skill 的检索，即使我们对 skill 触发器进行了微调。

为什么被动上下文优于主动检索？

我们的工作理论归结为三个因素：

1. 没有决策点。 使用 AGENTS.md 时，不存在 agent 必须决定”我应该查一下吗？“的时刻。信息已经存在了。
2. 始终可用。 Skills 只有在被调用时才异步加载。AGENTS.md 内容在每一轮的系统提示中都存在。
3. 没有顺序问题。 Skills 创建了顺序决策（先读文档还是先探索项目）。被动上下文完全避免了这个问题。

解决上下文膨胀的问题

在 AGENTS.md 中嵌入文档有上下文窗口膨胀的风险。我们通过压缩来解决这个问题。

最初的文档注入约为 40KB。我们将其压缩到 8KB（减少 80%），同时保持 100% 的通过率。压缩格式使用管道分隔的结构，将文档索引打包到最小空间：

[Next.js Docs Index]|root: ./.next-docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|01-app/01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}
|01-app/02-building-your-application/01-routing:{01-defining-routes.mdx,...}

完整索引涵盖了 Next.js 文档的每个部分。

Agent 知道在哪里找到文档，而无需在上下文中包含完整内容。当它需要特定信息时，它从 .next-docs/ 目录读取相关文件。

自己试试

一条命令即可为你的 Next.js 项目设置：

npx @next/codemod@canary agents-md

此功能是官方 @next/codemod 包 的一部分。

这条命令做三件事：

1. 检测你的 Next.js 版本
2. 将匹配的文档下载到 .next-docs/
3. 将压缩的索引注入你的 AGENTS.md

如果你使用的 agent 遵守 AGENTS.md（如 Cursor 或其他工具），同样的方法也适用。

这对框架作者意味着什么

Skills 并非无用。AGENTS.md 方法在所有任务中对 agent 使用 Next.js 的方式提供了广泛的横向改进。Skills 对于用户明确触发的垂直、特定操作的工作流更有效，如”升级我的 Next.js 版本”、“迁移到 App Router”或应用框架最佳实践。这两种方法相互补充。

话虽如此，对于一般的框架知识，被动上下文目前优于按需检索。如果你维护一个框架并希望 coding agent 生成正确的代码，可以考虑提供一个 AGENTS.md 片段供用户添加到他们的项目中。

实用建议：

• 不要等待 skills 改进。 随着模型在工具使用方面变得更好，差距可能会缩小，但现在结果最重要。
• 积极压缩。 你不需要在上下文中包含完整文档。指向可检索文件的索引同样有效。
• 用评测测试。 构建针对不在训练数据中的 API 的评测。这是文档访问最重要的地方。
• 为检索而设计。 构建你的文档结构，使 agent 可以查找和读取特定文件，而不是需要预先加载所有内容。

目标是将 agent 从预训练导向的推理转向检索导向的推理。AGENTS.md 被证明是实现这一目标最可靠的方式。

研究和评测由 Jude Gao 完成。CLI 可在 npx @next/codemod@canary agents-md 获取

欢迎关注我的其它发布渠道

WeChat