CLAUDE.md 与 Skills 的区别：一张表彻底分清

核心区别：一句话版本

· CLAUDE.md：贴在 Agent 桌子上的便签——"在这个项目里，永远记住这些事"
· Skills：放在 Agent 书架上的操作手册——"遇到这类任务时，按这个流程做"

---

详细对比

维度 CLAUDE.md Skills
本质 项目级持久约束 场景化能力模块
作用范围 该项目内所有会话，全程生效 只在匹配到的特定任务时加载
内容 项目事实、规范、禁止事项 特定领域的流程、最佳实践、工具组合
加载时机 每次启动 Agent 时默认注入 任务匹配时动态加载
加载方式 自动，无条件 自动匹配 或 手动调用
是否占用上下文 是，始终占用 是，但只在加载时占用
可插拔 否，一个项目一个文件 是，可以有多个，随时启用/禁用
谁维护 你手动编写 你可以写，也可以用社区现成的
典型内容 "用 pnpm，Node ≥ 18，别碰数据库 schema" "TypeScript 迁移流程"、"React 组件生成规范"

---

用代码类比

```typescript
// CLAUDE.md = 全局常量，整个项目到处都能用
const PROJECT_RULES = {
  packageManager: "pnpm",
  nodeVersion: ">=18",
  forbiddenPaths: ["/packages/database/schema"],
};

// Skills = 按需引入的模块，用到的时候才 import
import { typeScriptMigrationGuide } from "./skills/ts-migration";
import { reactBestPractices } from "./skills/react-patterns";
```

---

实际运行时怎么配合

假设你的项目有如下配置：

CLAUDE.md：

```markdown
- 使用 pnpm，不要用 npm
- Node 版本 ≥ 18
- 所有 API 路径以 /api/v1 开头
- 不要在周五部署
```

Skills 列表：

· nextjs-patterns（Next.js 最佳实践）
· api-error-handling（统一错误处理规范）
· weekly-report（周报生成器）

当你执行“给项目加统一错误处理”：

```
Agent 启动
  ├── 自动读取 CLAUDE.md → "pnpm、Node ≥ 18、API 路径规则" 永驻上下文
  └── 建立 Skill 索引

你下指令："给所有 API 加统一错误处理"
  ├── Agent 匹配 Skill → 命中 api-error-handling → 加载到上下文
  ├── Agent 规划任务（受 CLAUDE.md + Skill 双重约束）
  │   ├── CLAUDE.md 约束：API 路径保持 /api/v1 开头
  │   └── Skill 约束：错误格式遵循 RFC 7807
  └── 开始执行
```

---

什么时候写在 CLAUDE.md，什么时候写成 Skill？

写在 CLAUDE.md 的：

· 项目永远不变的事实（用什么技术栈、版本要求）
· 你每次都想让 Agent 知道的约束（命名规范、禁止操作）
· 简短、普适的规则

写成 Skill 的：

· 特定场景才需要的专业知识（某个框架的最佳实践）
· 有固定流程的多步骤任务（周报、代码审查）
· 你希望在多个项目间复用的能力
· 内容较长、只在特定时候需要的

---

一个直观判断法

问自己这个问题：

"这个规则，是每次任务都要遵守的，还是某类任务才需要遵守的？"

· 每次 → CLAUDE.md
· 某类 → Skill

---

常见误区

误区一：把所有规则都塞进 CLAUDE.md

· ❌ 结果：上下文被大量规则占满，留给推理的空间变少
· ✅ 正确：CLAUDE.md 放高频约束，低频的放 Skills

误区二：Skills 和 CLAUDE.md 写重复内容

· ❌ 结果：浪费上下文，两者冲突时 Agent 可能混乱
· ✅ 正确：CLAUDE.md 写通用约束，Skills 写领域细节，互不重叠

误区三：以为 Skill 能覆盖 CLAUDE.md

· ❌ Skill 不匹配就不会加载，重要约束会丢失
· ✅ 通用硬约束必须写在 CLAUDE.md

---

一句话总结

CLAUDE.md 是 Agent 的“项目常识”，Skills 是“专业培训”。常识始终在线，培训按需加载。