# AGENTS.md 的 Markdown 技能规格格式设计解析 > 解析 Vercel AGENTS.md 采用 Markdown 作为技能规格的底层设计选择，对比 Skills 文件夹格式与 MCP 协议，揭示版本追踪、权限声明与运行时验证的差异化实现路径。 ## 元数据 - 路径: /posts/2026/01/30/agents-md-markdown-skill-specification/ - 发布时间: 2026-01-30T13:02:55+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 当工程师需要告诉 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 的多文件结构更容易处理冲突。 第三，为文档建立版本关联机制。使用类似 `` 的注释标记版本依赖，让后续维护者明确知道哪些内容在版本升级时需要同步更新。 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日版本）。 ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。