作者注：详解 AI Agent 开发中 .agents 和 .claude 两个配置文件夹的定位差异、Skills 存放规范、目录结构对比，以及 AGENTS.md 与 CLAUDE.md 的适用场景
AI Agent 开发越来越火，项目根目录里开始出现各种配置文件夹——.agents、.claude、.cursor……其中 .agents 和 .claude 都可以放置 Skills，但它们的定位、设计理念和适用范围完全不同。选错了存放位置，轻则 Skills 不生效，重则团队协作时配置冲突。本文将从底层设计出发，讲清楚两者的核心区别和最佳实践。
核心价值: 看完本文，你将明确 Skills 该放在 .agents 还是 .claude，以及如何在多工具团队中高效管理 Agent 配置。
.agents 和 .claude 文件夹核心要点
先回答最核心的问题：这两个文件夹不是竞争关系，而是不同层次的配置体系。
| 对比维度 | .claude/ 文件夹 |
.agents/ 文件夹 |
|---|---|---|
| 归属方 | Anthropic（Claude Code 专属） | Agentic AI 基金会 / Linux 基金会 |
| 定位 | Claude Code 的项目配置目录 | 工具无关的 Agent 配置标准 |
| Skills 格式 | SKILL.md（Markdown + YAML 前置元数据） |
SKILL.yaml（纯 YAML） |
| 成熟度 | 生产就绪，Claude Code 正式支持 | 规范制定中（Work In Progress） |
| 跨工具支持 | 仅 Claude Code | 设计目标是所有 AI Agent 工具 |
.agents 和 .claude 文件夹的设计理念差异
这两个文件夹的根本差异在于设计哲学：
.claude/ 是"专属深度集成"思路。它为 Claude Code 量身定制，提供完整的 Skills、Subagents、Hooks、Permissions 等能力，与 Claude Code 的工具链深度绑定。优势是功能完善、开箱即用；代价是锁定在 Claude Code 生态内。
.agents/ 是"跨工具通用标准"思路。它试图定义一个所有 AI Agent 工具都能读懂的配置规范，类似于 .editorconfig 之于编辑器。优势是一套配置多工具通用；代价是规范还在演进中，各工具支持程度不一。
两者完全可以在同一个项目中共存——Claude Code 专属的深度配置放 .claude/，可跨工具复用的通用配置放 .agents/。
.claude 文件夹完整目录结构
先看 Claude Code 原生的 .claude/ 文件夹，这是目前最成熟的实现。
.claude 文件夹目录结构详解
.claude/
├── CLAUDE.md # 项目指令（替代根目录 CLAUDE.md）
├── settings.json # 项目设置（提交到 git，团队共享）
├── settings.local.json # 本地设置（gitignore，个人配置）
├── skills/ # Skills 技能目录
│ └── <skill-name>/
│ ├── SKILL.md # 技能定义文件（必需）
│ ├── scripts/ # 辅助脚本
│ ├── references/ # 参考资料
│ └── templates/ # 模板文件
├── agents/ # 子代理定义
│ └── <agent-name>.md # 子代理定义文件
├── commands/ # 旧版斜杠命令（已合并到 skills）
│ └── <command-name>.md
└── agent-memory/ # 子代理持久化记忆
└── <agent-name>/
└── MEMORY.md
同时还有用户级别的 ~/.claude/ 目录，个人 Skills 放在这里可以在所有项目中生效：
~/.claude/
├── CLAUDE.md # 用户级指令（跨项目）
├── settings.json # 用户级设置
├── skills/ # 个人 Skills（所有项目可用）
├── agents/ # 个人子代理
└── projects/ # 会话记录和数据
.claude 文件夹 Skills 的 SKILL.md 格式
Claude Code 的 Skills 使用 Markdown 文件 + YAML 前置元数据定义：
---
name: my-skill
description: 技能描述，帮助 Claude 判断何时触发
user-invocable: true # 用户可通过 /my-skill 调用
allowed-tools: Read, Grep # 限制可用工具
context: fork # 在独立子代理中运行
model: sonnet # 模型覆盖
---
你是一个专业的代码审查助手...
（Markdown 格式的技能指令）
关键字段说明：
user-invocable: true的 Skill 会注册为/slash-commandcontext: fork表示在独立上下文中运行，不污染主对话allowed-tools可以限制 Skill 能使用的工具集合$ARGUMENTS、$0、$1支持参数替换
🎯 开发建议: Claude Code 的 Skills 系统遵循 Agent Skills 开放标准（agentskills.io），语法在 Claude Code、Claude API 和 VS Code Copilot 中通用。
如果你用 Claude Code 开发 AI 应用，推荐通过 API易 apiyi.com 获取 API Key，统一管理多模型调用。
.agents 文件夹完整目录结构
.agents/ 文件夹规范（AGENTS-1 Spec）由 Agentic AI 基金会维护，托管在 Linux 基金会下，目标是定义一个所有 AI 编码工具都能理解的通用配置标准。
.agents 文件夹目录结构详解
.agents/
├── manifest.yaml # 必需：配置注册表，声明所有可用配置
├── prompts/ # 必需：指令提示
│ ├── base.md # 通用 Agent 指令
│ ├── project.md # 项目专属指令
│ └── snippets/ # 模块化指令片段
├── modes/ # 必需：行为模式（类似 .claude/agents/）
│ ├── plan.md # 规划模式
│ ├── code.md # 编码模式
│ └── review.md # 审查模式
├── policies/ # 必需：安全策略和能力约束
├── skills/ # 必需：技能定义（遵循 Agent Skills 规范）
│ └── <name>/
│ └── SKILL.yaml # YAML 格式技能定义
├── scopes/ # 必需：路径级覆盖（Monorepo 支持）
├── profiles/ # 必需：命名配置叠加（dev/ci/staging）
├── schemas/ # 必需：JSON Schema 校验
└── state/ # 本地状态（不提交 git）
├── .gitignore
└── state.yaml
与 .claude/ 的 Skills 使用 SKILL.md（Markdown）不同，.agents/ 的 Skills 使用 SKILL.yaml（纯 YAML）格式。
.agents 文件夹的独特设计
.agents/ 规范有几个 .claude/ 没有的概念：
- Scopes（作用域）: 为 Monorepo 中的不同子目录定义不同配置，最具体的路径优先匹配
- Profiles（配置档案）: 支持
dev、ci、prod等命名配置叠加，类似环境变量 - Policies（策略）: 独立的安全约束目录，deny 规则始终覆盖 allow 规则
- Determinism（确定性）: 相同输入必须产生相同输出，不依赖外部状态
.agents 和 .claude 文件夹 Skills 存放规则对比
这是开发者最关心的实操问题：我的 Skills 到底放哪里？
.agents 和 .claude 文件夹 Skills 对比
| 对比维度 | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| 定义文件 | SKILL.md（Markdown + YAML frontmatter） |
SKILL.yaml（纯 YAML） |
| Claude Code 支持 | 原生支持，自动发现 | 需手动配置或等官方支持 |
| 斜杠命令 | user-invocable: true 自动注册 /command |
取决于具体工具实现 |
| 子代理运行 | context: fork 在独立上下文运行 |
通过 modes/ 配置 |
| 模型覆盖 | model: sonnet 直接指定 |
通过 profiles/ 配置 |
| 工具限制 | allowed-tools: Read, Grep |
通过 policies/ 配置 |
| 辅助文件 | scripts/、references/、templates/ 子目录 |
取决于实现 |
| 参数传递 | $ARGUMENTS、$0、$1 变量替换 |
规范未明确定义 |
.agents 和 .claude 文件夹如何共存
实际项目中，两个文件夹可以共存互补。以本项目为例：
.claude/skills/ 存放 Claude Code 专属技能：
apiyi-article-generator— 文章生成，深度集成项目模板和规范apiyi-svg-generator— SVG 插图生成，依赖项目 SVG 模板apiyi-content-reviewer— 内容审核，使用项目质量标准
.agents/skills/ 存放通用可移植技能：
markdown-proxy— URL 转 Markdown 抓取，使用 Python 脚本nano-banana-pro-image-gen— 图片生成，调用外部 API
划分原则很清晰：与 Claude Code 深度集成的放 .claude/，可在其他 AI 工具中复用的放 .agents/。
🎯 选型建议: 如果你的团队只用 Claude Code，全部放
.claude/skills/即可，功能最完整。
如果团队成员使用不同 AI 工具（Cursor、Windsurf、Codex 等），通用技能放.agents/skills/更便于协作。
AI Agent 开发中的 API 调用推荐通过 API易 apiyi.com 统一管理，一个 Key 覆盖多种模型。
.agents 和 .claude 配套指令文件对比
除了 Skills 文件夹，两个体系还有各自的项目指令文件。
CLAUDE.md 与 AGENTS.md 的区别
| 对比维度 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 支持工具 | Claude Code | Claude Code、OpenAI Codex、Google Jules、Cursor、GitHub Copilot 等 |
| 文件层级 | 用户级（~/.claude/）→ 项目级（./）→ 子目录级 |
项目级（./）→ 子目录级 |
| 本地覆盖 | CLAUDE.local.md（gitignore） |
无 |
| 正式规范 | 无（Anthropic 产品文档） | 有（Linux 基金会下 Agentic AI 基金会） |
| 生态规模 | 增长中（Next.js、LangChain、Deno 等采用） | 大规模（n8n 178K stars、llama.cpp 97K stars、Bun 82K stars） |
| 初始化 | Claude Code 内 /init 命令 |
手动创建 |
实际建议：两个文件可以共存。CLAUDE.md 放 Claude Code 专属指令（如 Hooks 配置、权限规则），AGENTS.md 放所有 AI 工具通用的项目上下文（如构建命令、编码规范、架构说明）。
.agents 和 .claude 配套文件生态总览
| 文件/目录 | 所属体系 | 用途 | 是否提交 git |
|---|---|---|---|
CLAUDE.md |
.claude | Claude Code 项目指令 | 是 |
CLAUDE.local.md |
.claude | 个人本地指令 | 否 |
.claude/settings.json |
.claude | 权限、Hooks、MCP | 是 |
.claude/settings.local.json |
.claude | 个人本地设置 | 否 |
AGENTS.md |
.agents | 通用 Agent 项目指令 | 是 |
.agents/manifest.yaml |
.agents | 配置注册表 | 是 |
.agents/state/state.yaml |
.agents | 本地运行状态 | 否 |
.cursorrules |
Cursor | Cursor 专属规则 | 是 |
提示: 2026 年 ETH Zurich 的研究指出，AI 生成的上下文文件有时可能反而降低 Agent 性能，建议由人工编写并限制在代码中无法推断的非显性信息（自定义工具链、非常规模式等）。
常见问题
Q1: Claude Code 能读取 .agents/skills/ 目录下的 Skills 吗？
目前 Claude Code 原生只从 .claude/skills/ 自动发现和加载 Skills。.agents/skills/ 中的内容不会被自动识别。社区已在 GitHub 提交了 Issue（#31005）请求 Claude Code 支持 .agents/ 目录。如果你的 Skills 需要在 Claude Code 中生效，当前必须放在 .claude/skills/ 中。
Q2: .agents 文件夹规范成熟了吗？可以用于生产项目吗？
.agents/ 文件夹规范（AGENTS-1 Spec）目前仍在制定中（Work In Progress），但 AGENTS.md 文件已被广泛采用——n8n（178K stars）、llama.cpp（97K stars）、Bun（82K stars）等大型开源项目都在使用。建议先采用 AGENTS.md 作为通用指令文件，.agents/ 完整目录结构等规范稳定后再使用。
Q3: 团队成员用不同 AI 工具（Claude Code + Cursor），配置怎么管理？
推荐分层管理：1）AGENTS.md 放通用项目信息（构建命令、编码规范），所有工具都读取；2）CLAUDE.md 放 Claude Code 专属指令；3）.cursorrules 放 Cursor 专属规则。通用 Skills 放 .agents/skills/，工具专属 Skills 放各自目录。通过 API易 apiyi.com 统一管理团队的 AI API 调用，一个平台覆盖所有模型。
Q4: SKILL.md 和 SKILL.yaml 有什么格式区别？
SKILL.md 是 Claude Code 的格式，使用 Markdown 文件 + YAML 前置元数据（frontmatter），指令部分用 Markdown 编写，人类可读性更好。SKILL.yaml 是 .agents/ 规范的格式，全部使用 YAML 结构化定义，机器解析更方便。两者的核心信息（名称、描述、触发条件）相同，只是格式不同。
总结
.agents 和 .claude 文件夹的核心区别：
- 定位不同:
.claude/是 Claude Code 的专属项目配置目录，深度集成所有 Claude Code 功能；.agents/是 Linux 基金会下的跨工具通用标准 - Skills 格式不同:
.claude/skills/使用SKILL.md（Markdown），Claude Code 原生加载；.agents/skills/使用SKILL.yaml（YAML），设计上工具无关 - 可以共存互补: Claude Code 深度功能（Hooks、子代理、权限）放
.claude/，通用可移植技能放.agents/，项目基础指令用AGENTS.md
选择哪个文件夹的关键决策因素是你的团队工具链组成和技能的可移植性需求。
推荐通过 API易 apiyi.com 统一管理 AI Agent 开发中的模型调用，平台提供免费额度和多模型统一接口，支持 Claude、GPT、Gemini 等主流模型的一站式接入。
📚 参考资料
-
Claude Code Skills 官方文档: Skills 的完整定义、格式和使用方法
- 链接:
code.claude.com/docs/en/skills - 说明: 了解 SKILL.md 格式、触发规则和参数传递
- 链接:
-
Claude Code 子代理文档: Subagents 的定义和配置方法
- 链接:
code.claude.com/docs/en/sub-agents - 说明: 了解
.claude/agents/目录的文件格式
- 链接:
-
AGENTS.md 官方网站: 跨工具 Agent 指令文件标准
- 链接:
agents.md - 说明: 了解 AGENTS.md 的编写规范和支持工具列表
- 链接:
-
.agents/文件夹规范: AGENTS-1 Spec 的完整目录结构定义- 链接:
github.com/agentsfolder/spec - 说明: 了解 manifest.yaml、modes、policies、scopes 的设计
- 链接:
-
API易文档中心: AI Agent 开发中的统一 API 调用管理
- 链接:
docs.apiyi.com - 说明: 支持多模型统一接口，适合 Agent 开发场景
- 链接:
作者: APIYI 技术团队
技术交流: 欢迎在评论区讨论，更多资料可访问 API易 docs.apiyi.com 文档中心
