“到底什么信息该写进 CLAUDE.md，什么信息又该写进 Skills？”

说实话，这不是一个小问题。恰恰相反，如果你开始认真、长期、规模化地使用 Claude Code，这几乎就是最关键的架构决策之一。很多团队前期觉得无所谓，先堆着写，等项目一多、协作一复杂，就会发现整个上下文体系开始打架：规则到处都是，流程互相覆盖，Claude 每次干活都像在不同版本的脑回路里来回横跳。

所以，这篇文章会把这两个概念彻底讲清楚：CLAUDE.md 到底是什么，Skill 又到底是什么；什么时候该用前者，什么时候该用后者；以及，它们到底该怎么配合，才不会把项目越做越乱。

先说结论

如果非要用一句话去区分，我会这样想：

CLAUDE.md = 项目的大脑Skills = 可复用的能力模块

这两个东西，看起来都像“给 Claude 的说明”，可它们解决的根本不是同一类问题。

CLAUDE.md 负责的是：让 Claude 理解这个项目到底是什么、该遵守什么、边界在哪里。

Skills 负责的是：让 Claude 在某一类任务上，能反复调用一套成熟、稳定、可执行的方法。

一个偏“项目认知层”，一个偏“执行能力层”。

如果你从一开始就没把这两层分开，后面十有八九会写乱。

CLAUDE.md

你可以把 CLAUDE.md 理解成一句话：

“凡是 Claude 为了理解这个具体项目而必须知道的东西，都应该放在这里。”

判断方法其实特别简单。

当你在想某条信息该放哪里时，只要你脑子里冒出来的开头是：

“在这个项目里……”或者“对于这个项目来说……”

那这条信息，大概率就应该写进 CLAUDE.md。

因为它本质上是项目专属知识，而不是某种能跨项目复用的通用能力。

CLAUDE.md 一般放在哪里？

通常，它就放在项目根目录下。

也就是说，当 Claude 进入这个项目时，最先接触到、也最该优先建立上下文的，就是这个文件。

图片

CLAUDE.md 里到底该写什么？

这个文件本身是 Markdown 格式，所以结构上很自由，但真正重要的不是你分多少标题，而是你有没有把项目的关键认知信息讲清楚。

比如，下面这些内容，就是非常典型、也非常适合写进 CLAUDE.md 的部分：

## Project Overview
Short explanation of what the project is.

## Tech Stack
- TypeScript
- Next.js
- Tailwind
- ShadCN

## Architecture
Explain folders and patterns.

## Coding Rules
- Use functional React components
- Prefer server components
- Use Tailwind utilities instead of custom CSS

## Design System
- Follow ShadCN patterns
- Use tokens from /styles/tokens.ts

## Commands
npm run dev
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.

你会发现，这里面写的都不是“某个任务该怎么做”，而是“这个项目本身是什么样、该按什么方式被理解和执行”。

比如：

• 项目概览，告诉 Claude 这项目到底是在解决什么问题；
• 技术栈，告诉它你在这个项目里到底用什么；
• 架构说明，告诉它目录、模式、组织方式怎么理解；
• 编码规则，告诉它你在这个项目里有哪些明确偏好；
• 设计系统，告诉它 UI 和样式层该遵守什么；
• 常用命令，则是为了让它真正执行任务时别犯低级错误。

说白了，CLAUDE.md 的任务，不是“教 Claude 干活”，而是先把这个项目的世界观塞进它脑子里。

Skills

如果说 CLAUDE.md 解决的是“这个项目是什么”，那 Skills 解决的，就是“Claude 遇到某类任务时，该怎么做得更稳定、更像熟练工”。

所以我更喜欢把 Skills 理解成：

可按需调用的、可执行的专业能力。

它特别适合那种反复出现、流程清晰、最好每次都别从头摸索的任务。

比如这些，就非常适合做成 Skill：

• 生成 PRD
• 创建 landing page
• 重构组件
• 做设计审计
• 编写 API handler

这些事情的共同点在于：它们不是只属于某一个项目，而是你在很多项目里都会反复遇到。既然如此，就没必要每个项目都从头写一遍流程说明。

Skills 一般放在哪里？

Skills 可以分成两类：本地 Skills 和 全局 Skills。

本地 Skills 属于某个具体项目，通常会放在项目里的 /skills 目录下。例如：

project-root/
├── CLAUDE.md
├── skills/
│   ├── ux/
│   │   ├── run-ux-audit.md
│   │   └── analyze-user-flow.md
│   ├── coding/
│   │   ├── build-component.md
│   │   └── refactor-code.md
│   ├── research/
│   │   └── competitor-analysis.md
│   └── content/
│       └── write-linkedin-post.md
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.

这种本地 Skill 的意义在于：它只服务这个项目，或者说，它的使用场景强依赖这个项目当前的工作流。

而如果你发现某项能力在很多项目里都能复用，那它就更适合做成全局 Skill。全局 Skills 通常会放在 Claude Code 的工具目录里，比如：

~/claude-skills/
├── front-end-design/
├── ux-audit/
└── content-writing/
1.
2.
3.
4.

你可以把它理解成：本地 Skill 更像“项目内部工具”，全局 Skill 更像“你自己的长期武器库”。

顺手提一句，如果你根本不知道当前项目里 Claude 能用哪些 Skills，可以直接问它：

What skills I have
1.

图片

Skill 里应该写什么？

和 CLAUDE.md 一样，Skill 文件本身通常也是 Markdown。但 Skill 不是普通说明文档，它更像一个带触发条件和执行说明的“能力封装”。

通常，一个完整的 Skill 至少要包含两部分：

第一部分，是 YAML frontmatter，也就是写在 --- 标记之间的元信息。它的作用，是告诉 Claude：这是什么 Skill、它适合什么时候被使用。

第二部分，是 Markdown 格式的执行说明。也就是当这个 Skill 被调用时，Claude 到底该按什么步骤做。

比如，一个用于生成 landing page 的 Skill，可以写成这样：

name: create-landing-page
description: Generate a landing page using project conventions

steps:
  - Analyze CLAUDE.md for design system
  - Generate layout
  - Create components
  - Apply styling rules
  - Validate accessibility
1.
2.
3.
4.
5.
6.
7.
8.
9.

这里最值得注意的一点是：Skill 不是在替代 CLAUDE.md，而是在读取 CLAUDE.md 的前提下执行任务。

也就是说，Skill 更像一个熟练工的操作流程，而 CLAUDE.md 则像工地总规范。没有总规范，熟练工可能乱干；可只有规范、没有流程，Claude 又容易每次都发挥不稳定。

CLAUDE.md 与技能如何协同工作

很多人一开始总想二选一： 要么全写进 CLAUDE.md，觉得这样集中； 要么疯狂造 Skills，觉得这样模块化。

其实最合理的方式，从来不是二选一，而是让它们各守自己的位置，再互相配合。

我自己的理解是：

CLAUDE.md 负责给出底层规则、项目边界和基础约束；Skill 则在这些规则之内执行具体工作流。

举个很典型的例子。

如果你在 CLAUDE.md 里这样写：

## Tech Stack
- React version 19.2
- Use TypeScript 5.9.3
1.
2.
3.

这就属于项目级约束。它告诉 Claude：这个项目里，React 和 TypeScript 的版本就是这些，别乱来。

而与此同时，你又做了一个可复用的 Skill，叫 build-component，内容像这样：

Workflow:
1. Generate component in React
2. Use TypeScript types
3. Ensure <200 lines
4. Document component usage in markdown format
1.
2.
3.
4.
5.

那么，当 build-component 这个 Skill 被触发时，它会照着自己的流程去生成组件；但它在生成过程中，又必须尊重 CLAUDE.md 里已经写好的项目约束，比如 React 版本、TypeScript 版本、目录模式、设计系统等等。

这才是最健康的配合关系：

项目规则在 CLAUDE.md，任务方法在 Skill。

谁也别越界。

你甚至可以在 CLAUDE.md 里直接列出可用 Skills

这也是一种很实用的做法。比如，你可以在 CLAUDE.md 里单独写一个 “Available Skills” 区域，给项目里的常用 Skill 做快捷索引：

## Available Skills
- run-ux-audit → ./skills/ux/run-ux-audit.md
- build-component → ./skills/coding/build-component.md
1.
2.
3.

这样做的好处是，Claude 在读取项目脑子的时候，就已经顺手知道：这个项目里有哪些现成能力可以调用。对于复杂项目来说，这能明显减少“明明有 Skill 却没用上”的情况。

最容易踩的 3 个坑，真的很多团队都中过

说到这里，其实大方向已经很清楚了。但真正把系统用顺之前，还有几个特别常见的坑，最好一开始就避开。

坑一：把流程全写进 CLAUDE.md

很多人写着写着，就会忍不住在 CLAUDE.md 里塞这种东西：

To create a landing page:
1. Do this
2. Do that
1.
2.
3.

表面上看，这好像也没错。但问题在于：这已经不是“项目背景信息”了，而是一个具体任务流程。

这类内容，应该被放进 Skill 里；如果你不打算复用，那至少也该做成一个单独的 workflow .md 文件，在需要的时候引用，而不是直接塞进 CLAUDE.md 里。

因为一旦你把流程和项目脑子混写在一起，后面 CLAUDE.md 会越来越像一个什么都装的杂物间。结果就是：看起来信息很多，实际上层次全乱了。

坑二：把项目专属规则写进 Skill

再比如，有人会在 Skill 里直接写：

Use Next.js 16.1.1
1.

这就属于典型的放错地方。

因为 Skill 应该尽量是通用、可复用的。像某个框架的具体版本、某个项目特有的目录结构、某个产品专属的设计 token，这些都应该放在 CLAUDE.md 里，而不是塞进 Skill 里。

否则，今天这个 Skill 在 A 项目可用，明天拿到 B 项目还得改一遍，最后它根本不配叫“可复用能力”，只是一个伪装成 Skill 的项目片段而已。

坑三：重复写逻辑，越写越冲突

还有一种更隐蔽、也更烦的错误，就是重复定义。

比如某条规则你已经在 CLAUDE.md 里写过了，结果又在 Skill 里再写一遍，甚至写得还不完全一样。短期看你可能觉得“更保险”；可一旦后续改动发生，两个地方不同步，Claude 就会开始在冲突指令之间摇摆。

所以原则一定要记住：

Skills 应该读取 CLAUDE.md，而不是重写 CLAUDE.md。

能引用就引用，能继承就继承，不要重复造一套几乎一样的规则。

最后

如果你想把这篇内容真正记住，其实只需要记住一句话：

CLAUDE.md 讲的是身份、上下文和边界；Skill 讲的是动作、流程和能力。

换句话说：

CLAUDE.md 回答的是：“这个项目到底是什么？在这里该怎么理解世界？”

Skill 回答的是：“遇到这类任务时，我应该按什么成熟方法执行？”

一个定义环境，一个定义招式。

一旦你把这两个层次彻底分开，Claude Code 的可控性会明显提升。项目不会再越做越乱，Skill 也不会越积越废。你会发现，Claude 开始更像一个真正能协作的系统，而不是一个每次都要重新讲规则的临时工。

真正会在 Claude Code 上规模化做事的人，最后拼的从来不是 prompt 写得多花，而是这套结构到底搭得清不清楚。

而 CLAUDE.md 和 Skills 的边界，就是这套结构里最不能糊涂的一刀。