|

搞懂 .agents 和 .claude 文件夾的 5 個核心區別：AI Agent 開發的 Skills 該放哪裏？

ByAPIYI - Stable and affordable AI API

作者注：詳解 AI Agent 開發中 .agents 和 .claude 兩個配置文件夾的定位差異、Skills 存放規範、目錄結構對比，以及 AGENTS.md 與 CLAUDE.md 的適用場景

AI Agent 開發越來越火，項目根目錄裏開始出現各種配置文件夾——.agents、.claude、.cursor……其中 .agents 和 .claude 都可以放置 Skills，但它們的定位、設計理念和適用範圍完全不同。選錯了存放位置，輕則 Skills 不生效，重則團隊協作時配置衝突。本文將從底層設計出發，講清楚兩者的核心區別和最佳實踐。

核心價值: 看完本文，你將明確 Skills 該放在 .agents 還是 .claude，以及如何在多工具團隊中高效管理 Agent 配置。

agents-vs-claude-folder-skills-ai-agent-development-guide-zh-hant 图示

.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-command
  • context: 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-vs-claude-folder-skills-ai-agent-development-guide-zh-hant 图示

.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 性能，建議由人工編寫並限制在代碼中無法推斷的非顯性信息（自定義工具鏈、非常規模式等）。

agents-vs-claude-folder-skills-ai-agent-development-guide-zh-hant 图示

常見問題

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 文件夾的核心區別：

  1. 定位不同: .claude/ 是 Claude Code 的專屬項目配置目錄，深度集成所有 Claude Code 功能；.agents/ 是 Linux 基金會下的跨工具通用標準
  2. Skills 格式不同: .claude/skills/ 使用 SKILL.md（Markdown），Claude Code 原生加載；.agents/skills/ 使用 SKILL.yaml（YAML），設計上工具無關
  3. 可以共存互補: Claude Code 深度功能（Hooks、子代理、權限）放 .claude/，通用可移植技能放 .agents/，項目基礎指令用 AGENTS.md

選擇哪個文件夾的關鍵決策因素是你的團隊工具鏈組成和技能的可移植性需求。

推薦通過 API易 apiyi.com 統一管理 AI Agent 開發中的模型調用，平臺提供免費額度和多模型統一接口，支持 Claude、GPT、Gemini 等主流模型的一站式接入。

📚 參考資料

  1. Claude Code Skills 官方文檔: Skills 的完整定義、格式和使用方法

    • 鏈接: code.claude.com/docs/en/skills
    • 說明: 瞭解 SKILL.md 格式、觸發規則和參數傳遞

  2. Claude Code 子代理文檔: Subagents 的定義和配置方法

    • 鏈接: code.claude.com/docs/en/sub-agents
    • 說明: 瞭解 .claude/agents/ 目錄的文件格式

  3. AGENTS.md 官方網站: 跨工具 Agent 指令文件標準

    • 鏈接: agents.md
    • 說明: 瞭解 AGENTS.md 的編寫規範和支持工具列表

  4. .agents/ 文件夾規範: AGENTS-1 Spec 的完整目錄結構定義

    • 鏈接: github.com/agentsfolder/spec
    • 說明: 瞭解 manifest.yaml、modes、policies、scopes 的設計

  5. API易文檔中心: AI Agent 開發中的統一 API 調用管理

    • 鏈接: docs.apiyi.com
    • 說明: 支持多模型統一接口，適合 Agent 開發場景

作者: APIYI 技術團隊
技術交流: 歡迎在評論區討論，更多資料可訪問 API易 docs.apiyi.com 文檔中心

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts