SKILL.md vs CLAUDE.md vs AGENTS.md：什麼時候用哪個

一句話結論

CLAUDE.md 是給 Claude Code 的專案上下文。AGENTS.md 是一樣的東西，但跨工具通用。SKILL.md 是任務層級的能力，按需載入。三者解決不同問題，應該同時使用。

如果你只有時間維護一個檔案，選 AGENTS.md — 它是 2026 年最接近通用標準的 AI 編程 agent 設定檔，Codex CLI、Copilot CLI、Gemini CLI、Cursor、Claude Code 都認得。但「只維護一個檔案」是假經濟。真正的效能來自正確的分層。

這篇文章會講清楚什麼內容放哪裡、哪些工具讀哪些檔案、以及如何避開多數開發者踩到的效能陷阱。

比較總表

這張表的重點： CLAUDE.md 和 AGENTS.md 做同一件事 — 持久性專案上下文，注入到每次對話中。差別在於工具相容性。SKILL.md 本質上不同：它是條件式載入，只有當前任務符合 skill 的 description 時才會載入。這種按需載入正是 skill 存在的理由 — 你不該把所有東西塞進 CLAUDE.md。

.cursorrules 列在這裡是為了完整性。Cursor 仍然支援，但已經遷移到 .cursor/rules/ 的 .mdc 檔案格式，提供更細粒度的、基於檔案 pattern 的規則。如果你同時用 Cursor 和 CLI agent，把 .cursor/rules/ 分開維護 — 它的格式是 Cursor 專屬的，不能移植到其他工具。

CLAUDE.md：你專案的 AI 新人文件

CLAUDE.md 是 Claude Code 在每次 session 開始時讀取的檔案。把它想成新人入職文件 — 不是給新員工，而是給一個每次對話都沒有記憶的 AI agent。

該放什麼

• 架構概覽 — 框架、資料庫、驗證方案、主要依賴
• 程式碼慣例 — 命名模式、錯誤處理風格、import 慣例
• 硬性限制 — agent 絕對不能做的事（修改 migration、使用特定套件、破壞特定 API）
• 建構和測試指令 — 如何跑測試、lint、build

不該放什麼

• 任務特定的工作流程（那些屬於 SKILL.md）
• 冗長的參考文件（改用連結指向它）
• agent 可以從程式碼推斷的資訊（tsconfig.json 已經告訴它你用 TypeScript）
• linter 規則（你的 linter 會確定性地強制執行；CLAUDE.md 不會）

ETH Zurich 的研究發現

2026 年 2 月，蘇黎世聯邦理工學院的 Thibaud Gloaguen 等人發表了 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" — 第一篇嚴格評估這類上下文檔案是否真的有幫助的研究。結果讓很多開發者意外：

• LLM 生成的上下文檔案比完全不提供上下文，任務成功率降低約 3%。
• 人工撰寫的上下文檔案只提升了約 4%。
• 加入上下文檔案讓推理成本增加超過 20%。

核心問題：詳盡的程式碼庫概述跟既有文件高度重複，過度限制的指令反而讓 agent 更難解決實際任務。Agent 已經會讀你的程式碼 — 重述程式碼裡已經有的資訊只是浪費 context window、增加噪音。

實務意涵： 保持 CLAUDE.md 精簡。100 行以下。每一行都要通過這個測試：「拿掉這行，agent 會犯一個它自己無法恢復的錯誤嗎？」

實際範例

## Project Overview
E-commerce API serving 50k DAU. Monorepo with API server and admin dashboard.

## Architecture
- Runtime: Node.js 22, TypeScript strict
- Framework: Fastify 5
- Database: PostgreSQL 16 via Drizzle ORM
- Auth: Custom JWT with refresh token rotation
- Queue: BullMQ on Redis

## Conventions
- Error handling: Result<T, E> pattern (see src/lib/result.ts)
- All endpoints validated with Zod schemas in src/schemas/
- Database queries go in src/repositories/, never in route handlers
- Tests: Vitest for unit, Supertest for integration

## Hard Constraints
- Never modify files in src/db/migrations/
- Never use default exports except in route files
- All new endpoints need integration tests before merge

## Commands
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build
- Migrate: pnpm db:migrate

30 行。告訴 agent 所有有效工作需要的資訊，不重述程式碼已經呈現的內容。

AGENTS.md：跨工具的專案上下文

AGENTS.md 和 CLAUDE.md 用途相同 — 持久性專案上下文 — 但工具相容性更廣。最初由 OpenAI 的 Codex CLI 推廣，AGENTS.md 現在是由 Linux Foundation 下的 Agentic AI Foundation 託管的開放標準，已被超過 60,000 個開源專案採用。

哪些工具會讀它

截至 2026 年 3 月，認得 AGENTS.md 的工具：

• Codex CLI（OpenAI）— 每次任務前讀取
• Copilot CLI（GitHub）— 自動發現並載入
• Gemini CLI（Google）— 原生支援
• Cursor — 與 .cursor/rules/ 一起讀取
• Claude Code（Anthropic）— 作為補充上下文讀取

Claude Code 同時讀 CLAUDE.md 和 AGENTS.md。Codex CLI 讀 AGENTS.md 但不讀 CLAUDE.md。這個不對稱性創造了一個實用策略：

策略：AGENTS.md 作為唯一真相來源

把 AGENTS.md 當作專案上下文的唯一真相來源。CLAUDE.md 保持最小化 — 只放 Claude Code 專屬的指令（像 compaction 行為或權限提示），其他全部引用 AGENTS.md。

# CLAUDE.md

Read AGENTS.md for project architecture and conventions.

## Claude Code-Specific
- When compacting, preserve the full list of modified files
- Prefer subagents for research tasks over inline exploration

# AGENTS.md

## Project Overview
E-commerce API serving 50k DAU. Monorepo with API server and admin dashboard.

## Architecture
- Runtime: Node.js 22, TypeScript strict
- Framework: Fastify 5
- Database: PostgreSQL 16 via Drizzle ORM
...
（跟上面完整的 CLAUDE.md 範例一樣的內容）

這個做法消除重複。使用多種 AI 工具的團隊可以得到一致的行為。只用 Claude Code 的團隊也不損失任何東西 — Claude Code 兩個檔案都讀。

巢狀 AGENTS.md

AGENTS.md 和 CLAUDE.md 都支援目錄層級的巢狀。frontend/AGENTS.md 可以包含只在 agent 處理該目錄檔案時才適用的前端慣例。Monorepo 中不同 package 有不同慣例時，用這個方式處理。

SKILL.md：按需載入的專業能力

這裡才是有趣的地方。SKILL.md 跟 CLAUDE.md 和 AGENTS.md 有本質上的不同。關鍵差異：skill 只在相關時才載入。

當你啟動 Claude Code session 時，CLAUDE.md 和 AGENTS.md 會立即注入 context window。這些檔案的每一個 token 都算在你整個 session 的 context 預算裡，不管你正在做什麼任務。

Skill 不一樣。每個 skill 在 YAML frontmatter 中有一個 description 欄位。Claude Code 讀取所有 skill 的 description（短字串，成本低），只在當前任務符合某個 description 時才載入完整的 skill 指令。這就是為什麼你不該把所有東西塞進 CLAUDE.md — 專業知識應該放在 skill 裡，按需載入，保持基礎 context 精簡。

要深入理解 skill 系統以及如何打造有效的 skill，請看 Agent Skills 指南。

SKILL.md 的結構

每個 skill 住在 .claude/skills/ 下自己的資料夾裡。資料夾裡必須有一個 SKILL.md 檔案，包含 YAML frontmatter 和 markdown 指令。

.claude/skills/
  database-migration/
    SKILL.md
  api-endpoint/
    SKILL.md
  pr-review/
    SKILL.md

這裡是一個具體範例 — 資料庫 migration skill：

---
name: database-migration
description: >
  Use this skill when creating, modifying, or reviewing database migrations.
  Triggers on: new migration files, schema changes, Drizzle ORM modifications,
  database column additions or removals, index changes.
---

## Database Migration Workflow

### Before Creating a Migration
1. Read the current schema in src/db/schema.ts
2. Check existing migrations in src/db/migrations/ for naming conventions
3. Verify no pending migrations exist: run `pnpm db:status`

### Creating the Migration
1. Modify the schema in src/db/schema.ts first
2. Generate the migration: `pnpm db:generate`
3. Never write migration SQL by hand — always use the generator
4. Review the generated SQL for correctness

### After Creating a Migration
1. Run `pnpm db:migrate` on the dev database
2. Run integration tests: `pnpm test:integration`
3. If tests fail, do NOT modify the migration file — drop and regenerate

### Naming Convention
- Format: NNNN_descriptive_name.sql
- Examples: 0042_add_user_preferences.sql, 0043_create_audit_log_table.sql

### Hard Rules
- Never modify an existing migration file that has been committed
- Never delete a migration file
- Always test migrations against a fresh database: `pnpm db:reset && pnpm db:migrate`

這個 skill 有 30 多行 migration 專屬知識。如果放在 CLAUDE.md 裡，每次 session 都會消耗 context — 即使你在做前端元件的工作。作為 skill，它只在你要求 Claude Code 建立 migration 或它偵測到任務涉及 migration 相關檔案時才載入。

Skill 的獨特能力

三項能力讓 SKILL.md 與 context 檔案截然不同：

1. 腳本執行。 Skill 可以包含 Claude Code 執行的可執行腳本。部署 skill 可能包含一個部署前檢查清單腳本。CLAUDE.md 和 AGENTS.md 都做不到。

2. 根據 description 自動觸發。 Frontmatter 中的 description 欄位告訴 Claude Code 何時啟動這個 skill。Description 寫得稍微「強勢」一點 — Claude Code 傾向於少觸發 skill 而不是多觸發。

3. 存取控制。 Skill 支援 disable-model-invocation: true（只有使用者能觸發）、user-invocable: false（只有 Claude Code 觸發，作為背景知識）、以及 allowed-tools（限制 Claude Code 在 skill 內能用哪些工具）。Context 檔案不具備這種細粒度控制。

分層策略

以下是如何同時使用三種檔案，用最少的 context 消耗達到最大效果：

第一層：AGENTS.md（永遠載入、跨工具） 專案架構、程式碼慣例、硬性限制、建構指令。保持 100 行以下。這是每個 AI 工具都讀的通用專案上下文。

第二層：CLAUDE.md（永遠載入、Claude Code 專屬） 最小化。共享上下文引用 AGENTS.md。只加 Claude Code 專屬指令，像 compaction 行為、subagent 偏好、權限提示。20 行以下。

第三層：Skills（按需載入、任務專屬） 專業化工作流程，只在相關時才載入。資料庫 migration、PR review 流程、部署檢查清單、API endpoint 模式、測試撰寫慣例。每個 skill 可以很詳細（最多 500 行），因為它只在需要時才進入 context。

結果： 你的基礎 context 精簡（CLAUDE.md + AGENTS.md 加起來 120 行以下），但按需可以獲得深度能力。這才是表現好的架構 — 它尊重 ETH Zurich 的研究發現（保持永遠載入的 context 最小化），同時在 agent 需要時提供豐富的任務專屬指引。

這種 workspace 層級的設定管理 — 保持 context 檔案、skill、工具設定在你的開發環境中同步 — 正是 Termdock 的 workspace sync 大顯身手的地方。當你切換專案時，整個 context 設定（終端、環境變數、git 狀態）跟著你一起切換。

決策流程圖

當你要為 AI agent 寫一條新指令時，依序問這些問題：

「這跟這個專案的每一個任務都有關嗎？」 是 -> AGENTS.md（或 CLAUDE.md 如果只用 Claude Code） 不是 -> 繼續往下。

「這是一個有多個步驟的專業化工作流程嗎？」 是 -> 在 .claude/skills/ 建立 SKILL.md 不是 -> 繼續往下。

「它需要在工作流程中執行腳本或指令嗎？」 是 -> SKILL.md。這是唯一支援腳本執行的選項。 不是 -> 繼續往下。

「你使用多種 AI 編程工具嗎？」 是 -> 共享上下文放 AGENTS.md，Claude 專屬指令放 CLAUDE.md，任務工作流程放 SKILL.md。 不是（只用 Claude Code）-> CLAUDE.md 放專案上下文，SKILL.md 放任務工作流程。

「這是 Cursor 專屬的編輯器行為嗎？」 是 -> .cursor/rules/ 的 .mdc 檔案。跟 agent context 檔案分開管理。

中間地帶的情況，預設放 AGENTS.md。它是覆蓋面最廣的檔案，Claude Code 讀 AGENTS.md 而不是 CLAUDE.md 沒有任何壞處 — Claude Code 兩個都讀。

常見錯誤

錯誤 1：把所有東西塞進 CLAUDE.md

最常見的失敗模式。開發者寫 300 行以上的 CLAUDE.md，包含程式碼標準、架構文件、工作流程指令、風格指南。ETH Zurich 的研究直接證明了：越長的 context 檔案，效能越差。Agent 遵循部分指令、忽略其他，這種不一致比完全沒有 context 檔案還糟。

解法： 無情地精簡。專業化工作流程移到 skill。跨工具上下文移到 AGENTS.md。CLAUDE.md 裡剩下的東西應該一個螢幕就能看完。

錯誤 2：完全不用 Skill

很多開發者學會 CLAUDE.md 就停了。他們從來沒發現 skill 的存在，或者覺得額外的複雜度不值得。這等於把大量能力留在桌上不用。

Skill 是區分「agent 知道你專案的架構」（CLAUDE.md）和「agent 知道如何執行你的特定工作流程」（skill）的關鍵。上面的資料庫 migration 範例包含了新人要花好幾個小時才能學會的機構知識。有了 skill，agent 瞬間就有這些知識 — 而且只在相關時才載入。

如果你在用 Claude Code 或任何相容 skill 的 agent，從 2-3 個最常見工作流程的 skill 開始。完整的建構與安裝教學請看 Agent Skills 指南。

錯誤 3：跨檔案重複內容

CLAUDE.md 寫「用 Vitest 跑測試」。AGENTS.md 寫「用 Vitest 跑測試」。測試 skill 也寫「用 Vitest 跑測試」。同一條指令三份拷貝代表換測試框架時要改三個地方 — 而且必然有一個被遺漏。

解法： 單一真相來源。AGENTS.md 持有正式版的專案上下文。CLAUDE.md 引用它。Skill 引用它。當 skill 需要專案層級的資訊時，寫「遵循 AGENTS.md 中的測試慣例」而不是重述。

錯誤 4：用 LLM 生成 Context 檔案

ETH Zurich 的研究特別測試了這點：讓 LLM 生成你的 context 檔案，結果比你自己手寫更差。LLM 生成的檔案冗長、泛用、充滿 agent 已經能從程式碼庫看到的重複資訊。

手寫你的 context 檔案。你比任何 LLM 都更了解你專案的怪癖、限制和慣例。AI CLI 工具指南有一個可以直接改用的 CLAUDE.md 範本 — 但要改寫它，不要用生成的。

錯誤 5：忽略跨工具相容性

如果你的團隊今天用 Claude Code，明天可能改用 Copilot CLI 或 Codex CLI。把所有 agent 上下文都建在 CLAUDE.md 裡等於綁死。AGENTS.md 是對沖 — 它今天就能跨工具使用，而且隨著標準在 Linux Foundation 下成熟，支援只會更廣。