Gutenberg 仓库随附了面向 AI 编码代理的说明：AGENTS.md 文件和 .agents/skills/ 目录。本文档解释了它们的组织方式，以及在添加更多内容之前需要考虑的事项。

指导原则：首先改进文档

在向代理文件添加任何内容之前，请先询问该信息是否也能帮助人类贡献者。如果可以，它应该属于公开文档，而代理文件应指向这些文档。

仅限代理使用的文件很容易腐化：由于无人审计，遗漏的细节和过时的信息会长期存在，而公开文档则由贡献者持续阅读和修正。将文档复制到代理文件中还意味着两份副本会悄然分叉。代理文件应路由到规范文档，切勿复制其内容。

代理指令的组织方式

代理指令遵循渐进式发现原则——代理仅读取当前任务所需的内容：

  • 根目录下的 AGENTS.md 会在每个代理会话中加载。它保持精简，并路由至公开的贡献者文档。
  • 目录级 AGENTS.md 文件（例如 packages/components/AGENTS.md）在代理处理该目录中的文件时加载。它们包含仅作用于该目录的规则。
  • 技能 (Skills) (.agents/skills/<domain>/SKILL.md) 是轻量级的、针对特定任务的指南——包括流程、检查清单或决策树。原生技能发现利用每个技能的 frontmatter 描述，在其任务匹配时选择一个技能。
  • 链接的文档和参考资料仅在流程步骤指向它们时才被读取——在此之前没有成本，因此深度内容应放在那里。
  • 兼容性指令文件（例如 CLAUDE.md）是一行 @AGENTS.md 重定向；内容始终位于 AGENTS.md 中。

这种结构控制了上下文膨胀。根目录下的 AGENTS.md 是每个会话的固定成本，因此请保持精简。技能主体在相关时被读取，因此请保持其轻薄且具程序性。所有通过一跳连接的链接实际上是免费的。

支持的代理

Codex 原生发现仓库技能目录。Claude Code 使用生成的兼容视图。安装依赖项时，如果视图中仅包含目录条目，则会更新该视图；如果发现未匹配的本地条目，则保持视图不变。目前尚未配置其他特定于代理的视图。

创建技能

在 .agents/skills/<domain>/SKILL.md 中创建仓库技能，遵循下文描述的共享 Agent Skills 格式。添加、删除或更改技能后，运行 npm run agents:setup 以将目录应用到所有受支持的代理。它会询问是否替换未匹配的生成技能条目；然后启动一个新的代理会话，以便其发现更新的目录。

新指南应归属于何处？

按此列表向下查找，并在第一个匹配处停止：

  1. 公共文档 — 如果信息对人类也有帮助（通常如此），请改进文档，并让代理文件指向那里。
  2. 根目录 AGENTS.md — 仅用于几乎每个任务都需要的事实：环境设置和通用陷阱。
  3. 目录级 AGENTS.md — 用于代理在特定目录中工作时必须知道的规则。
  4. 技能 (Skill) — 用于范围限定于某种任务类型而非位置的指南：代理在执行该项工作时应遵循的流程、检查清单或决策树（运行测试、发布包、搭建区块脚手架）。

技能约定

这些约定使用共享的 Agent Skills 格式：

  • 每个域一个目录：.agents/skills/<domain>/，小写 kebab-case。
  • SKILL.md 以 YAML frontmatter 开头，仅包含 name（与目录匹配）和 description。将描述表述为触发条件：“Use when …”。
  • 保持主体简短且具有程序性。链接到深度内容而不是将其内联，并保持每个链接的文件距离 SKILL.md 仅一跳。
  • 作为需要它的流程步骤的一部分，链接代理必须阅读的文档（“编写第一个主体前请先阅读 [guide]”）。经测试，如果代理找到与其任务匹配的技能，它将专注于该任务，而不是重新考虑来自 AGENTS.md 的泛化的“阅读相关文档”文件。
  • 可选的 .agents/skills/<domain>/references/ 目录存放代理特定的深度内容，这些内容在公共文档中没有归属地。

testing skill 及其 references/ 目录 是这些约定的实时示例。骨架形式下，一个技能看起来像这样：

---
name: <domain>
description: Use when <the tasks that should trigger reading this skill>.
---

# <Domain>

<What the root AGENTS.md already covers is not repeated here.>

## <Procedure step shared by every sub-area>

…

## By sub-area

-   **<Sub-area>**: read [references/<sub-area>.md](references/<sub-area>.md).

逐步解析实时 testing skill 如何应用这些约定：

  • description 是代理在决定是否读取技能时进行匹配的依据，因此它列出了应触发该技能的任务（“编写、运行或调试测试……”）。
  • 主体起路由作用而非解释作用：每种工作一行，每行指向一跳之外的 references/ 文件。
  • 适用于每个子区域的流程步骤（与作者一起规划测试列表）在技能主体中存在一次，而不是在每个参考文件中重复——每个事实只有一个归属地，位于其适用于下方所有内容的最高层级。
  • 每个参考文件仅包含其领域的代理特定规则，并链接到规范文档以获取深度内容。例如，references/e2e.md 指出“保持无头模式；切勿使用 --headed 或 --ui”——这些模式是 e2e 指南正确推荐给人类的，但会使代理会话挂起——然后链接到该指南以获取编写实践。
  • 没有任何内容重申根目录 AGENTS.md —— 每个代理已经加载了它。
  • 这是端到端的渐进式披露：描述始终可见，当开始测试任务时读取主体，并且仅当工作实际属于该类时才读取每个参考文件。

添加技能的检查清单

  1. 确认公共文档无法涵盖它——如果可以，请先改进公共文档。
  2. 按照上述约定创建 .agents/skills/<domain>/SKILL.md。
  3. 运行 npm run lint:md:docs。