Agent Skills 为什么突然火了？CLAUDE.md、AGENTS.md 和 SKILL.md 怎么分工

先给结论：

CLAUDE.md 和 AGENTS.md 负责“在这个项目里平时怎么工作”；SKILL.md 负责“遇到某类任务时，按哪套可复用流程执行”。

它们都能影响 Coding Agent，但不是同一种东西。把所有内容塞进一个巨大的项目说明，会长期占用上下文；把每条仓库规则都拆成 Skill，又会让 Agent 缺少每次任务都需要的基础信息。

Agent Skills 最近受到关注，关键不是又出现了一个 Markdown 文件名，而是它把能力发现和完整操作手册加载分开：Agent 启动时只看到少量元数据，匹配任务后才读取完整步骤、脚本和参考资料。

本文基于截至 2026 年 7 月 19 日的 Agent Skills、Anthropic、OpenAI 和 AGENTS.md 官方资料，并用本机 Hermes Agent 做了两次固定提示的最小 A/B 实验。

一张表看懂三个文件

文件	本质	典型内容	加载时机	最适合
`CLAUDE.md`	Claude Code 的持久项目/用户指令	构建命令、编码规范、架构约定、长期陷阱	启动时加载祖先目录；子目录规则按访问加载	Claude Code 每次会话都应知道的信息
`AGENTS.md`	面向 Coding Agent 的开放项目说明	安装、测试、目录职责、贡献约定	由客户端实现；Codex 从项目根逐层读到当前目录	希望多种 Coding Agent 共享项目规则
`SKILL.md`	Agent Skill 的入口	触发描述、步骤、判断规则、验收条件	通常在任务匹配或显式调用后读取	发版、审计、迁移等按需重复流程

CLAUDE.md、AGENTS.md 与 SKILL.md 的职责边界

最实用的判断是：

希望 Agent 每次都知道：放 CLAUDE.md 或 AGENTS.md；
只在某类任务出现时才需要：做成 Skill；
必须强制禁止或授权：交给权限、沙箱、Hook 或 Policy，不要只靠 Markdown。

`SKILL.md` 不是换了名字的项目 Prompt

一个开放标准的 Skill 至少是一个目录：

release-note/
├── SKILL.md
├── scripts/       # 可选：确定性程序
├── references/    # 可选：详细参考资料
└── assets/        # 可选：模板和资源

最小入口：

---
name: release-note
description: Create release notes that follow the team's exact format. Use when preparing a product release.
---

# Release note workflow

1. Read the release policy.
2. Group changes by type.
3. Render the approved template.
4. Run the validation script.

开放规范要求 name 和 description，正文使用 Markdown；还可声明 license、compatibility、metadata，以及目前仍为实验性的 allowed-tools。

不同客户端可以增加扩展字段。Claude Code 的调用控制或子 Agent 选项、Codex 的 agents/openai.yaml 都不是所有 Skill 客户端必须支持的通用标准。

为什么是“渐进式披露”让 Skills 变得实用

Agent Skills 官方把加载分成三层：

元数据：启动时只暴露名称和描述，用来判断是否相关；
SKILL.md 正文：任务匹配或用户显式调用后加载；
脚本与参考资料：执行中按需读取，没访问的文件不进入上下文。

Agent Skills 的三层渐进式披露

这解决了一个常见矛盾：团队希望 Agent 知道越来越多流程，但上下文窗口不应永久背着所有手册。

Anthropic 当前文档给出的近似量级是：每个 Skill 的初始元数据约 100 tokens，正文建议控制在约 5K tokens 内；这不是跨客户端硬限制。OpenAI Codex 则为初始 Skill 列表设置上下文预算：通常最多占窗口的 2%，无法获知窗口时上限为 8,000 字符；完整 SKILL.md 在选中后另行读取。

所以“按需加载”不等于零成本。Skill 仍有元数据发现成本，触发后也会增加输入；真正要比较的是，它是否减少了遗漏、探索和返工。

`CLAUDE.md`：Claude Code 的长期上下文

适合放入：

项目使用 pnpm 而不是 npm；
标准测试和构建命令；
目录职责和架构约定；
每次改动都适用的编码规范；
稳定、反复踩到的项目陷阱。

Claude Code 会从当前工作目录向上发现 CLAUDE.md 和 CLAUDE.local.md，并把发现的文件加入上下文；当前目录以下的规则通常在访问对应子目录时再加载。@path 可以导入其他文件。

重要边界：Anthropic 明确把这些文件描述为上下文，而不是强制配置。出现冲突时，模型不保证按一条机械优先级执行。必须确保的规则仍要用权限或 Hook 落地。

Claude Code 会直接读取 `AGENTS.md` 吗？

截至本文核对日期，不会把它当作 CLAUDE.md 的天然替代品。Anthropic 官方建议从 CLAUDE.md 导入：

# CLAUDE.md
@AGENTS.md

## Claude Code

- Put Claude Code-specific notes here.

也可以建立符号链接：

ln -s AGENTS.md CLAUDE.md

因此“Claude Code 原生支持 AGENTS.md”是过度概括。

`AGENTS.md`：给 Coding Agent 的项目 README

AGENTS.md 官方将它称为“README for agents”。它把人类 README 不必承载的 Agent 细节放在可预测位置，例如：

# AGENTS.md

## Setup
- Install dependencies with `pnpm install`.

## Tests
- Run `pnpm test` before reporting completion.

## Conventions
- Do not edit generated files.

Codex 的官方发现规则比较具体：

先检查 Codex home 中的 AGENTS.override.md 或 AGENTS.md；
再从项目根走到当前目录；
每层最多选择一个匹配文件；
越靠近当前目录的说明排得越后，可以细化前面的规则；
项目说明总大小默认受 32 KiB 限制。

但这是 Codex 的实现规则，不是整个 AGENTS.md 生态必须采用的统一算法。不同 Agent 是否支持、怎样合并，应查各自文档。

真实对照：同一提示，无 Skill 与有 Skill

为了不把产品机制写成营销口号，我做了一个最小实验。它不是 Coding Agent 的全面 Benchmark，只回答一个窄问题：当任务有团队专属输出格式时，附带按需流程能否提升规则命中？

实验使用：

同一个 Hermes Agent API；
同一个模型入口 hermes-agent；
temperature: 0；
两次独立请求；
相同基础提示；
第二次额外附带一份 release-note Skill 正文；
不连接真实仓库、网络或生产数据。

基础任务只有：

为 2.4.0 生成 release-note.md：
Added: OAuth device flow
Fixed: duplicate webhook delivery
Breaking: /v1/events now requires event_id
只返回 Markdown。

Skill 预注册了 8 个机器可检查要求：固定 H1、四个固定章节、两条未勾选检查项，以及用反引号包围 API 路径。评分项在看到输出前已经确定。

原始结果

指标	无 Skill	有 Skill	差值
运行次数	1	1	—
指令命中	3/8	8/8	+5 项
全部要求满足	否	是	—
输入 Token	15,204	15,354	+150
输出 Token	44	61	+17
总 Token	15,248	15,415	+167
输出字符	139	220	+81

无 Skill 与有 Skill 的实验对照

无 Skill 输出为：

# 2.4.0

## Added

- OAuth device flow

## Fixed

- Duplicate webhook delivery

## Breaking Changes

- `/v1/events` now requires `event_id`

它完成了通用 release note，但不知道团队要求版本号前带 v，也没有 Verification 和两条固定检查项。

有 Skill 输出为：

# v2.4.0

## Added

- OAuth device flow

## Fixed

- Duplicate webhook delivery

## Breaking changes

- `/v1/events` now requires `event_id`

## Verification

- [ ] Migration guide reviewed
- [ ] Changelog links verified

该实验能证明什么，不能证明什么

它能证明：在这两次受控请求里，增加 150 个输入 Token 后，团队专属格式从 3/8 提升到 8/8。

它不能证明：

Skills 会普遍提高所有代码任务质量；
任意模型或客户端都会得到相同结果；
Skills 一定节省 Token——本次反而增加 167 个总 Token；
自动触发一定可靠——本实验直接提供了 Skill 正文，没有测试客户端的隐式匹配；
3/8 到 8/8 具有统计显著性——每组只有一次运行。

更完整的评测应多次交错运行，记录工具事件、文件读取、测试结果和修改 Diff。本文选择公开原始输出而不是用一次样本包装“成功率提升”。

三者怎样组合才不乱

一个实用仓库可以这样组织：

repo/
├── AGENTS.md                         # 跨 Agent 的通用项目规则
├── CLAUDE.md                         # @AGENTS.md + Claude 专属说明
├── .claude/skills/release/SKILL.md   # Claude Code 项目 Skill
└── .agents/skills/release/SKILL.md   # Codex 等兼容客户端 Skill

设计原则：

项目文件保持短而稳定：只写每次工作都相关的事实；
Skill 保持任务化：一个 Skill 解决一类明确任务；
描述写清触发条件：既说明做什么，也说明何时使用；
详细资料放 references：主流程不要塞成百科全书；
确定性工作交给脚本：格式校验、Schema 检查、构建命令不必让模型猜；
不要复制冲突规则：Skill 应遵守项目规则，而不是维护另一套版本；
安全边界交给执行层：Markdown 不是权限系统。

常见误区

“Skill 就是保存的 Prompt”

不完整。Skill 是带元数据的目录，可以携带脚本、参考资料和模板，并通过渐进式披露按需加载。

“Skill 就是 MCP 或插件”

不是。Skill 提供程序性知识和本地资源；MCP 连接外部工具与上下文。两者可以组合。在 OpenAI 当前产品语境中，Plugin 还是安装和分发 Skills、Connector 或 MCP 的包装方式之一。

“`SKILL.md` 永远覆盖 `AGENTS.md`”

没有跨客户端统一规则。项目指令和 Skill 的发现、合并及冲突行为由客户端实现；更高层系统或权限规则也不会被项目文件覆盖。

“把所有规则都放 Skill 最省上下文”

也不对。每次任务都必须知道的构建命令若藏在偶尔触发的 Skill 中，Agent 可能根本看不到。按需信息与长期信息必须分开。

“一份 Skill 到处都完全兼容”

开放格式提供可移植基础，但客户端扩展字段、路径、优先级、预算和工具授权仍有差异。可移植 Skill 应把核心流程保持在标准字段内。

对多模型 Agent 团队意味着什么

当团队同时使用 Claude Code、Codex 或其他 Agent 时，问题会从“写一段好 Prompt”变成三层治理：

项目层：统一仓库规则和测试门禁；
能力层：用 Skills 复用发布、审计、迁移等流程；
模型入口层：统一不同 Agent 的模型访问、用量和成本记录。

Nbility 位于第三层：它不会替代 AGENTS.md 或 Skill，但可以为多个 Agent 提供统一 API 入口，集中查看请求、Token 用量和费用。正如本次实验所示，Skill 可能增加单次输入成本，也可能通过减少遗漏降低返工；要判断净收益，必须把完整调用链的用量记录下来，而不是只看 Skill 文件有多长。

如果需要验证不同模型是否适合你的 Skill 流程，可以在 Nbility 使用同一入口做受控对照；需要小额测试额度时，可通过工单联系支持。

官方资料

本文涉及的路径、加载优先级、上下文预算和扩展字段变化很快，以上事实核对于 2026-07-19。