1. 绪论：从提示词工程到代理架构的范式转移

在人工智能尤其是大语言模型（LLM）的发展历程中，我们正处于一个从单纯的文本生成向**自主代理（Autonomous Agents）**演进的关键转折点。这一转变不仅是模型参数量的增加或推理能力的提升，更是交互范式与上下文管理策略的根本性重构。

早期的 AI 交互主要依赖于“提示词工程（Prompt Engineering）”。然而，随着应用场景向复杂的企业级工作流、自动化软件开发以及高精度数据处理拓展，单纯依赖上下文窗口（Context Window）遭遇了显著瓶颈：

• 上下文的有效治理
• 确定性能力的执行

为了解决这些问题，技术社区与领先的 AI 实验室分别提出了不同的解决方案标准：

1. AGENTS.md（GitHub Copilot, Cursor 等推动）： 旨在通过标准化的文档协议解决“上下文治理”问题，被形象地称为“机器人的 README”。
2. Agent Skills（Anthropic 等推动）： 旨在通过封装指令与代码的动态模块解决“能力执行”问题，赋予 Agent 类似于人类专家的“技能包”。

---

2. 上下文治理层：AGENTS.md 的架构与生态

2.1 AGENTS.md 的核心定义与设计哲学

AGENTS.md 并非编程语言，而是一种基于 Markdown 格式的上下文协议（Context Protocol）。其核心在于“人机协作的透明化与标准化”。

• 传统痛点： 传统的 README.md 包含大量对 AI 冗余的信息（徽章、赞助商），且缺乏 AI 决策所需的隐式约束。
• 解决方案： AGENTS.md 作为专为 AI 设计的元数据文件，通过自然语言明确定义项目的角色（Persona）、技术栈（Tech Stack）、行为边界（Boundaries）以及操作指令（Commands）。

2.2 结构化剖析：从元数据到行为约束

一个高质量的 AGENTS.md 文件通常包含以下核心模块：

2.2.1 角色定义与环境上下文

定义 Agent 的身份与技术栈版本，防止生成过时代码。

示例： “你是一个专注于 React 18 和 Tailwind CSS 的高级前端工程师。项目使用 Next.js 14 App Router, TypeScript 5.0。”

2.2.2 操作指令集（Operational Commands）

显式列出构建、测试和部署命令，支持 Agent 的**自我纠正（Self-Correction）**循环。

# 示例指令集
构建指令: pnpm build
测试指令: pnpm test:unit
格式化指令: npm run lint

2.2.3 否定约束与行为边界（Negative Constraints）

定义“不做像什么”往往比“做什么”更具约束力，起到概率剪枝的作用。

• 🚫 安全边界： “绝不要在代码中硬编码 API 密钥，始终使用环境变量。”
• 🚫 架构边界： “绝不要修改 src/core 目录下的底层逻辑，除非得到显式授权。”
• 🚫 风格边界： “绝不要使用 any 类型，必须定义完整的 TypeScript 接口。”

2.3 层次化解析逻辑与单体仓库支持

针对大型单体仓库（Monorepo），AGENTS.md 引入了层次化解析逻辑（Hierarchical Resolution Logic）：

1. 就近原则（Proximity Priority）： 优先读取距离当前编辑文件最近的 AGENTS.md。
2. 上下文合并（Context Merging）： 将根目录的全局指令与子目录的局部指令合并。

2.4 生态系统与工具链集成

目前该标准已被超过 60,000 个开源项目采用。

工具平台	集成方式	特性
GitHub Copilot	支持 .github/copilot-instructions.md	在对话开始时自动注入系统提示词。
Cursor / Windsurf	索引入 RAG 系统	将 AGENTS.md 作为高优先级上下文，支持自然语言查询规范。
Aider / Goose	CLI 启动时读取	作为会话的“元规则”，并在 Git 操作时参考提交规范。
OpenAI Codex	早期支持者	利用该文件作为理解代码库意图的关键元数据。

---

3. 能力执行层：Agent Skills 的技术体系与实现

3.1 Agent Skills 的定义

Agent Skills（基于 agentskills.io 标准）代表了一种动态的、可执行的能力封装（Capability Encapsulation）。它包含指令、脚本和资源，旨在让 AI 以可重复、确定性的方式完成特定任务，体现了“代码即工具（Code as Tool）”的理念。

3.2 架构解构：渐进式披露与沙箱执行

3.2.1 渐进式披露机制（Progressive Disclosure）

采用三层架构管理上下文，避免耗尽 Token：

1. Level 1 发现层 (Discovery)： 仅加载 YAML Frontmatter (name, description)。

• 作用： 让 Agent 知道“我有这个能力”。

2. Level 2 指令层 (Instruction)： 动态加载 SKILL.md 主体内容。

• 作用： Agent 获得详细步骤和工作流。

3. Level 3 执行层 (Execution)： 按需运行具体脚本或读取文档。

• 作用： 完成具体的计算或生成。

3.2.2 物理文件结构规范

标准的 Skill 目录结构如下：

my-skill/
├── SKILL.md          # 核心接口文件 (Required, 含 Frontmatter)
├── scripts/          # 可执行代码 (Optional)
│   ├── process.py
│   └── validate.sh
├── templates/        # 输出模版 (Optional)
│   └── report_template.docx
└── references/       # 辅助文档 (Optional)
    └── api_spec.md

3.3 代码执行与安全性

• 沙箱隔离： Skills 运行在 Docker 容器或 MicroVM 中，无法访问宿主机敏感文件。
• 确定性操作： 使用预先编写好、经过测试的脚本（Pre-written & Tested），而非 LLM 临时生成的“一次性代码”，保证执行结果的确定性。

3.4 API 生命周期

• Beta Headers： 需包含 tools-2025-*-* 标识。
• 创建与上传： 通过 SDK 上传 ZIP 包（通常限制 8MB）。
• 版本控制： 支持 Versioning，可锁定特定版本以保证生产环境稳定性。

---

4. 深度对比分析：AGENTS.md vs. Agent Skills

4.1 本质维度的差异

维度	AGENTS.md	Agent Skills
核心隐喻	员工手册 (Employee Handbook)	工具箱 (Toolbox)
主要载体	静态纯文本 (Markdown)	动态文件夹结构 (Markdown + Code)
交互模式	被动注入：预加载进 Prompt	主动调用：Agent 决定何时加载执行
上下文成本	高：占用初始 Context	低：按需加载详情
执行能力	无：依赖 Agent 自身生成代码	强：依赖预置脚本的沙箱执行
适用场景	项目规范、代码风格、架构约束	复杂数据处理、文件转换、API 交互
治理模式	社区共识 (Community Consensus)	企业标准 / 开源规范

4.2 哲学层面的分歧

• AGENTS.md (静态约束)： 关注 “What” 和 “Why”。假设 AI 有能力，只需“对齐”规则。
• Agent Skills (动态能力)： 关注 “How”。假设通用 AI 不可靠，需要外挂“义肢”来“增强”能力。

4.3 场景化应用建议

• 使用 AGENTS.md 当： 需要统一命名约定、目录结构、禁用特定库时。
• 使用 Agent Skills 当： 需要处理非结构化数据、生成特定格式报表、执行复杂多步 API 调用时。

---

5. 融合与演进：Model Context Protocol (MCP) 的角色

Model Context Protocol (MCP) 正在成为连接这两者的“操作系统”层。

1. AGENTS.md 与 MCP： MCP 服务器可动态推送 AGENTS.md 内容（例如连接到 GitHub 仓库时自动加载）。
2. Agent Skills 与 MCP： MCP 解决“如何连接”，Skills 解决“连接后做什么”。MCP 服务器可以将 Skills 暴露为资源。
3. 生态融合：

• Skills 内部可能嵌入 AGENTS.md 逻辑。
• 项目的 AGENTS.md 可能显式索引特定的 Skills（如“迁移数据库时请加载 db-migration-skill”）。

---

6. 结论与实施建议

AGENTS.md 和 Agent Skills 分别代表了 AI 代理架构中的**“软约束”与“硬能力”**。

给企业架构师与开发者的建议：

• ✅ 全面部署 AGENTS.md： 低成本高收益。建议在所有项目中维护该文件，既提升 Copilot 效果，也作为人类员工的指南。
• ✅ 战略性采用 Agent Skills： 识别高频、高价值、高准确性要求的任务（如合同审核、自动化测试），将其封装为 Skills。
• ✅ 关注标准化进程： 密切跟踪 agentskills.io 和 MCP 标准，构建“即插即用”的智能系统。