各项指令应放在何处：AGENTS.md、CLAUDE.md和SKILL.md

已有超过4,300名工程师为某个GitHub议题点赞，要求Claude Code无需辅助即可加载AGENTS.md文件。但到了2026年7月，版本2.1.201依然无法实现这一功能。Anthropic自己的文档现在告诉开发者如何强制让系统执行该操作：在终端中运行ln -s AGENTS.md CLAUDE.md。实际上，这家公司为其自身工具拒绝读取的文件提供了变通方案。

争论本身并不重要，真正的工程实现细节体现在Anthropic公开技能仓库中claude-api SKILL.md文件的一行内容里，即其YAML前置信息的描述字段中。与CLAUDE.md和AGENTS.md不同，正是这段描述决定了Claude是否要继续读取文件其余内容。涉及三个文件和三种加载模型，而一旦看到相关规则，文件的放置位置问题也就迎刃而解了。

这种分离是如何产生的

时间线展示了该行业是如何发展到目前的。2025年8月，AGENTS.md规范作为一套通用的AI编程助手指令集正式推出。构建命令、测试规则以及项目架构都可以存储在同一个文件中，这样Cursor、Copilot以及独立的智能体都能读取这个文件。

两个月后的2025年10月，Anthropic推出了Agent Skills，采用了不同的上下文处理方式。与单纯的规则Markdown文件不同，一种技能实际上是一个包含自身元数据、脚本及参考文档的目录。

到2025年12月，这两种格式均已成为开放标准。技能规范发布在agentskills.io上，而AGENTS.md规范则被提交给Linux基金会，作为Agentic AI基金会的核心项目。目前已有超过6万个代码仓库以及大约二十多种工具能够直接支持AGENTS.md，因此这两种标准都不会被淘汰。

结果是，团队现在需要在三个地方编写相同的指令：用于编辑器的AGENTS.md、用于终端的CLAUDE.md，以及用于复杂工作流的SKILL.md。之后他们就会疑惑为何智能体运行速度变慢，令牌费用却不断上升。解决这个问题首先要从这些工具实际解析文本的方式入手。

技能的门槛

会话并不会从智能体读取项目中的所有文件开始，因为那样会耗尽上下文窗口容量并削弱模型的注意力。它会寻找特定的入口点，以及遵循逐步披露模式的技能。

启动时，智能体会将每个已安装技能的元数据加载到系统提示中。这些元数据包括名称和描述，每项技能大约需要100个标记。随后智能体会读取用户的请求，将其与已加载的描述进行对比，从而决定是否展开该技能的内容。描述起到筛选作用，相关参考资料则被锁在其后。

以下是发布在Anthropic开放仓库中的claude-api技能的前置信息。

---
name: claude-api
description: |
  Reference for the Claude API / Anthropic SDK — model ids, pricing, params,
  streaming, tool use, MCP, agents, caching, token counting, model migration.
  TRIGGER — read BEFORE opening the target file; don't skip because it "looks
  like a one-liner" — whenever: the prompt names Claude/Anthropic in any form
  (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`,
  `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/
  model choice/limits/caching) — never answer from memory; OR the task is
  LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/
  RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/
  converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).
  SKIP only when another provider is being worked on (overrides all triggers):
  OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR
  `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|
  cohere|ollama'` over the project hits (run this grep FIRST if no provider
  named — don't Read the file).
license: Complete terms in LICENSE.txt
---

# Claude API reference

Model IDs, pricing, request/response shapes, tool use, MCP, caching,
streaming, and migration notes for the Anthropic SDK.

... (body continues; only loaded if the description above passes the gate)

描述字段具有双重功能：它向智能体说明该技能的功能，同时作为编程接口，供技能开发者编写触发逻辑。

TRIGGER和SKIP只是约定俗成的用法，并非架构中定义的字段。开发者只需用通俗的英语说明何时触发该逻辑即可。这类技能的实现代码往往包含数百行API参考内容。如果涉及Postgres数据库的相关问题，描述检查就会失败，相应的参考文本也就不会被加载。

CLAUDE.md和AGENTS.md的运作方式有所不同。它们没有类似的触发机制。一旦智能体在路径中找到这些文件，就会在会话开始时将其加载，并在整个对话过程中保持有效。

哪些内容应放在哪个文件中

加载模型决定了内容。注入的文件应仅包含智能体在每一步行动中所需的信息。而受限访问的文件则应存储适用于特定任务的专门知识。

一个名为orchard的仓库展示了这些文件如何能够在磁盘上共存而不重复信息。

orchard/
├── AGENTS.md                          # root: shared, tool-agnostic project context
├── CLAUDE.md                          # 6 lines: imports + Claude-specific memory tiers
├── README.md                          # for humans
├── .github/
│   └── workflows/
│       └── skills-to-agents.yml       # dave1010/skills-to-agents@v2 → emits <skills> block into AGENTS.md
├── .agents/
│   └── skills/
│       └── db-migration/
│           ├── SKILL.md               # YAML frontmatter + body; loads only when description gate matches
│           ├── scripts/
│           │   └── check_reversibility.py
│           └── references/
│               └── postgres-lock-modes.md
├── services/
│   └── payments/
│       └── AGENTS.md                  # nested: subproject-specific rules; nearest-file-wins
└── packages/
    └── ui/

AGENTS.md 中记载了通用的构建规则，包括风格指南、单仓库结构、测试运行方法以及依赖项相关说明。无论何种工具读取，这都是所有智能体所需的基准上下文。其核心特性是“最近文件优先”原则：在 services/payments/ 目录下工作的智能体会首先读取该目录下的 AGENTS.md，并优先采用本地规则而非根目录的规则。OpenAI 通过类似这样的包含88个文件的单仓库结构来管理内部上下文，而嵌套文件仅加载当前目录所需的内容，从而保持上下文的简洁性。

CLAUDE.md 的功能更为有限，其中仅包含在当前智能体为 Claude Code 时才有效的指令。

Bloat是CLAUDE.md文件中常见的问题。开发者们会将整个AGENTS.md内容粘贴到CLAUDE.md中，以为Claude需要自己独立的构建规则副本。而正确的最小化形式则是将共享的标准导入到Claude的上下文中。

# Project instructions for Claude Code

@AGENTS.md

## Claude-specific

- Prefer `Explore` subagent for cross-file searches over 3 files; single grep otherwise.
- User-level memory lives at ~/.claude/CLAUDE.md — do not duplicate its rules here.

<!--
Alternative if you do not want an @ import and prefer one file on disk:

    ln -s AGENTS.md CLAUDE.md

This is Anthropic's own recommendation for repos that keep AGENTS.md canonical
and have nothing Claude-specific to add. See docs.claude.com/en/docs/claude-code/memory.
-->

适用于多个工具的规则应放在AGENTS.md中。Anthropic的记忆管理文档推荐使用@AGENTS.md导入作为主要方式，而对于那些没有特定于Claude的内容、仅希望工具读取标准文件的仓库，则可采用符号链接作为替代方案。

SKILL.md是条件能力层，用于存储重复出现的工作流程、一次性功能以及深度领域术语。在orchard中，.agents/skills/db-migration/目录包含了安全执行Postgres迁移所需的所有内容，即用于检查可逆性的Python脚本以及关于Postgres锁模式的Markdown说明。这些内容都不属于AGENTS.md的范畴。在UI包中编辑CSS文件的智能体无需在其系统提示中接收锁模式相关信息。描述门控机制可确保仅在处理迁移文件时才加载相应技能。

路由规则

一旦模型加载完成，添加新的上下文就会变得很机械化：

• 每轮对话都需要的、可共享且与工具无关的项目上下文应放在 AGENTS.md 中。
• 仅适用于 Claude Code 的指令应放入 CLAUDE.md 中，最好是一个导入 AGENTS.md 的简短文件。
• 仅部分任务需要的特定工作流程、脚本及领域参考资料，应放在某个技能模块中，并附上说明何时使用该模块的描述。

控制持续运行的资源消耗

条件加载与持续加载之间的区别直接关系到智能体的性能。

2026年1月，伦敦国王学院、新加坡管理大学、海德堡大学以及班贝格大学的研究人员发表了一项研究（arXiv:2601.20404），旨在探究AGENTS.md文件的实际功能。实验结果显示，智能体的运行时间减少了28.64%，输出token数量减少了16.58%，但任务完成速度仍保持相近水平。共享的指令层提升了智能体的效率——它们无需再自行编写构建命令或运行错误的测试套件，因为模型只需读取一次标准规则即可直接开始执行任务。

只有当上下文保持相关性时，这种效率才能维持。系统提示词中的每一个标记都会占用模型的注意力。假设某个团队将一份500字的数据库迁移指南粘贴到根目录下的AGENTS.md中，那么智能体在修复前端状态错误时就必须阅读这份指南，本应思考React钩子的问题却不得不把注意力放在Postgres锁模式上。

条件加载机制有助于保护这些优势。将特定场景的工作流程放到SKILL.md中，可以保持根目录AGENTS.md的精简，从而延续共享上下文带来的运行效率优势，同时避免为不相关的指令付出注意力成本。

存在的桥梁与不存在的桥梁

该生态系统存在翻译层面的差距。Claude Code能够理解技能及其启用条件，但Cursor、Copilot以及独立的CLI工具则无法原生理解 .agents/skills/ 这一结构。

开发数据库迁移技能的团队希望Cursor用户也能从中受益。若将该技能手动复制到AGENTS.md中，就会破坏唯一的真实数据源，因此解决方案是进行编译。

这样，非Claude智能体无需手动复制即可查看这些技能。在orchard的AGENTS.md中生成的代码块如下所示。

# Project agents

Build with `pnpm build`. Test with `pnpm test`. Migrations under
`services/payments/migrations/` must run through the db-migration skill.

## Style

- TypeScript 5.x, strict mode on. No `any` in new code.
- Errors surface as structured `AppError` with a `code` field, never raw strings.

<!-- BEGIN skills-to-agents (auto-generated; edit .agents/skills/*/SKILL.md) -->
<skills>
  <skill name="db-migration" path=".agents/skills/db-migration/">
    Run a Postgres migration end-to-end. TRIGGER whenever the user asks to
    add/modify a migration, backfill a column, or lock-analyze a schema
    change. SKIP if the query is purely a read-only SELECT / EXPLAIN.
  </skill>
  <skill name="release-notes" path=".agents/skills/release-notes/">
    Draft the release notes for a merged PR. TRIGGER on "cut a release",
    "write release notes", or "prep the changelog". SKIP if the PR is a
    dependency bump.
  </skill>
</skills>
<!-- END skills-to-agents -->

## Repo layout

- `services/` — deployable services, each with its own AGENTS.md
- `packages/` — shared libraries
- `.agents/skills/` — Conditional workflows

该桥接工具会显示每项技能的名称、路径及描述。非Claude版本的智能体并未内置针对这些目录的渐进式展示功能，因此技能板块中的摘要便充当了它们的界面：读取AGENTS.md的工具会找到该板块，解析触发条件，并确定在磁盘上的具体位置以完成迁移。

目前仍缺失的桥接功能是让Claude Code直接读取AGENTS.md，而无需通过导入或符号链接的方式。Manifold上的预测市场仍在讨论Anthropic是否会在今年底前加入此类支持功能。这一差距表明工具开发者希望掌控自己的上下文层——Anthropic拥有CLAUDE.md，而社区则拥有AGENTS.md。跨平台兼容性将继续依赖于具体的工具和持续集成流程，而非规范要求。

最终的系统架构

查看该果园单仓库结构后可以发现其运作良好。嵌套的AGENTS.md文件包含了通用的结构规则，而一行式的CLAUDE.md则负责处理与Claude相关的导入内容。db-migration SKILL.md则在描述门控之后等待数据库任务触发，GitHub Action则将所有组件整合在一起，确保没有开发者会重复编写相同的规则。