当工程师需要告诉 AI 代理「如何正确使用这个项目」时，他们面临一个架构选择：用结构化的 JSON Schema 定义函数签名和参数约束，还是用自然语言写一份可读性更高的文档？Vercel 推动的 AGENTS.md 标准选择了一条看似「复古」但实际充满深意的路径 —— 用 Markdown 这种轻量级标记语言作为技能规格的载体。本文将从格式设计的底层逻辑出发，对比 Skills 文件夹格式与 Model Context Protocol（MCP），解析 AGENTS.md 在版本追踪、权限声明和运行时验证三个关键维度上的差异化实现。
格式设计的起点：为什么是 Markdown
AGENTS.md 的核心设计理念可以浓缩为一句话：让代理读取的内容与人类维护的内容保持一致。传统的技能规格往往采用 JSON 或 YAML 等结构化格式，这种选择在机器解析层面具有优势 —— 严格的类型定义、明确的必填字段、可验证的 schema 合规性。然而，这种「机器优先」的设计思路带来了一系列工程摩擦。
首先是可维护性问题。一个包含数十个函数定义的 JSON Schema 文件，修改时需要精确对应字段层级，任何格式错误都会导致代理无法正确解析。其次是版本控制体验。结构化数据在 Git diff 中往往产生大量噪声，使得代码审查难以聚焦于实质变更。最后是协作门槛。团队中并非所有成员都熟悉 JSON Schema 语法，而 AGENTS.md 的 Markdown 格式对任何写过文档的开发者都是天然的。
Vercel 的评估数据揭示了一个更具说服力的证据：在控制变量的前提下，AGENTS.md 配置达到了 100% 的测试通过率，而基于 Skills 格式的配置在未添加显式调用指令时仅达到 53%，即便添加了明确指令也仅能提升至 79%。这个差距并非源于技能内容的差异，而是格式本身的特性影响了代理的行为模式 —— 代理可以立即读取 AGENTS.md 中的内容，无需做出「是否加载这个技能」的决策。
版本追踪：嵌入元数据与目录结构
技能规格的版本管理是实际工程中的核心痛点。当框架发布新版本时，API 签名可能发生变化，旧文档中的示例代码可能产生误导。AGENTS.md 采用了一种「嵌入式版本锚定」的策略：在文档头部声明适用的框架版本，文档内容本身跟随版本更新而演进。这种设计与 Skills 格式形成了鲜明对比。
Skills 采用文件夹结构组织技能包，每个技能对应一个独立目录，包含 skill.json 清单文件和多个资源文件。这种设计的版本粒度是技能包级别的 —— 用户安装特定版本的技能包后获得完整的资源集合。优点是隔离性好，缺点是版本切换需要重新安装整个包。AGENTS.md 的版本粒度则可以细化到单行指令 —— 用户可以在同一个文件中保留多个版本的 API 使用说明，通过版本条件分支让代理自行选择。
Markdown 的纯文本特性为版本追踪提供了额外的便利。Git 可以直接对比不同提交之间的内容变更，reviewer 能够清晰地看到新增、删除或修改的指令。而 Skills 的文件夹结构中，资源文件可能是 Markdown、代码片段或二进制格式，跨文件的变更追踪需要借助更复杂的工具链。从实际维护角度而言，AGENTS.md 的单一文件形式降低了工具链复杂度，也让 CI/CD 流程中的文档验证变得更简单 —— 只需确认 Markdown 语法正确即可。
权限声明：从机器约束到人类约定
当一个技能需要访问文件系统、网络资源或敏感 API 时，如何向代理传达权限边界？不同格式采用了截然不同的思路。
Skills 格式的权限声明嵌入在 skill.json 清单文件中，采用结构化的字段定义。Anthropic 定义的技能规范中，permissions 字段是一个对象数组，每个条目包含 type（权限类型）、description（人类可读的描述）和可选的 constraints（约束条件）。这种设计是可验证的 —— 代理运行时可以检查技能声明的权限是否与实际使用的 API 匹配。
AGENTS.md 的权限声明则是「约定优于约束」的典型体现。开发者可以在文档中使用自然语言描述访问权限，例如「此脚本需要读取项目根目录的 .env 文件获取 API 密钥」或「该工具将向 https://api.example.com 发送 POST 请求」。代理根据这些描述自行判断是否需要请求额外的授权。
两种设计各有其适用场景。结构化权限声明适合需要严格审计的企业环境 —— 安全团队可以解析 skill.json 并生成权限报告。但自然语言权限声明的优势在于灵活性：同一段描述可以同时传达功能意图和安全边界，代理无需在「功能描述」和「权限清单」之间建立映射关系。Vercel 的评估中，AGENTS.md 达到 100% 通过率而 Skills 止步于 79%，部分原因正是 AGENTS.md 的权限描述与功能说明位于同一上下文中，代理不会因为「忘记检查权限清单」而违规操作。
运行时验证：无 schema 的信任模型
JSON Schema 和类型定义的一个核心价值是运行时验证 —— 代理在执行技能前可以检查参数是否符合预期，如果不符合则拒绝执行或抛出错误。AGENTS.md 完全放弃了这种验证机制，转而依赖「文档即协议」的信任模型。
这种设计选择背后是对当前代理能力的判断。当前的 LLM 在遵循指令方面仍有局限性 —— 精确的类型匹配和边界检查并非它们的优势任务。与其让代理在「参数验证失败」和「尝试执行」之间做出选择，不如将验证责任前置到文档编写阶段：通过清晰的示例代码和边界说明，让代理在第一次执行时就产生正确的行为。
Vercel 的实践证明了这种信任模型的可行性。他们将原本 40KB 的文档索引压缩至 8KB，保留的并非完整的 API 签名定义，而是一份「文档路径索引」—— 代理根据这份索引找到对应的文档文件，在需要时读取具体内容。这份索引本身不需要 schema 验证，只需确保路径格式正确即可。
相比之下，MCP 协议的验证机制更为严格。MCP 定义了完整的 JSON-RPC 消息格式，每个工具调用必须符合预定义的 schema。优点是错误处理更精确，缺点是集成成本更高 —— 工具提供方需要编写完整的 schema 定义，工具消费方需要实现验证逻辑。AGENTS.md 的「无验证」模型降低了集成门槛，但也要求文档编写者承担更多责任。
实际采用建议
对于正在评估技能规格格式的团队，以下实践建议可供参考。
第一，将 AGENTS.md 视为「代理专属的 README」。不要将人类需要阅读的完整项目文档复制进去，而是提取代理最需要的上下文：项目使用的框架版本、包管理器命令、代码风格约定、测试运行方式。Vercel 的实践表明，8KB 左右的压缩索引足以覆盖 Next.js 完整文档的检索需求。
第二，利用 Markdown 的可组合性组织大型文档。当项目复杂度较高时，可以将 AGENTS.md 拆分为多个主题文件，使用 include 语法或链接引用保持一致性。这种模式在 Git 合并时比 Skills 的多文件结构更容易处理冲突。
第三，为文档建立版本关联机制。使用类似 <!--适用于 Next.js 16+ --> 的注释标记版本依赖，让后续维护者明确知道哪些内容在版本升级时需要同步更新。 Skills 的 skill.json 通过 version 字段强制声明版本，但 AGENTS.md 的「软版本」标记更灵活 —— 同一个文件可以同时包含多个版本的 API 说明。
第四，谨慎处理权限声明。虽然 AGENTS.md 不强制验证权限，但良好的实践是在文档开头使用固定格式声明所需的访问范围，例如「## 权限要求」小节列出所有需要的能力。这种格式虽然不强制验证，但为后续的审计和交接提供了清晰的参考点。
技能规格的格式选择最终取决于团队的技术文化和安全需求。AGENTS.md 的 Markdown 格式代表了一种「信任文档、简化约束」的哲学，它在可维护性和协作效率上具有优势，但要求开发者承担更多的质量保证责任。对于追求快速迭代和低集成成本的团队，这种设计提供了一个值得考虑的选项。
资料来源：本文核心数据与设计理念参考自 Vercel 官方博客的 AGENTS.md 评估报告（2026 年 1 月 27 日）、Anthropic 主导的 Agent Skills 开源规范（GitHub 7.9k stars），以及 Model Context Protocol 官方规范文档（2025 年 11 月 25 日版本）。