Claude Code Skills 和 CLAUDE.md：它们怎么配合

Skills 是 Claude Code 里很多人很晚才发现的部分。像 /handoff、/review、/wt 这样的 slash commands 看起来只是快捷方式，但每一个背后都有一个 markdown file，只在被调用时把 scoped behavior 加载进 agent。skills 和 CLAUDE.md 的关系很重要。它决定了 agent 每个会话都能看到哪些规则，只在需要时看到哪些规则，以及当你决定写一条新规则时应该放哪里。下面是 2026 年初这两者的配合方式，以及怎样利用这种关系保持 CLAUDE.md 短，同时还能捕捉 rich workflows。

skill 到底是什么

skill 是一个带 frontmatter 的 markdown file，存放在 ~/.claude/skills/（user-global）或 .claude/skills/（project-local）下面。frontmatter 声明 skill 的 name、description 和 triggering rules。body 是 markdown prose，会在 skill 被调用时加载到 agent 的 context。

skills 有两种调用方式。用户可以直接输入 /<skill-name>。或者用户用自然语言描述任务，harness 会拿这个意图和 skill 的 description field 匹配，并提示调用它。第二种是很多人漏掉的模式。description field 做了很多工作，写得好的 description 才能让 skill 在该触发时真的触发。

skill 的 body 可以包含 workflow steps、format specifications、hard rules、examples，以及指向其他 documents 的 pointers。当 skill 被调用时，整个 body 会成为这个 workflow 中 agent 的 working context。这是关键 architecture property：skills 是 scoped context，而 CLAUDE.md 是 always-on context。

为什么 scope 重要

CLAUDE.md 每次会话开始都会加载。里面每一行都在每个会话消耗 context budget，不管这条规则和当前任务有没有关系。一份 300 行 CLAUDE.md 会让你在整个会话里付 300 行 context 的成本，即使你只是在 debug 一个单文件 CSS 问题，而只有三行适用。

skills 只有被调用时才加载。一个 500 行 skill，对不调用它的会话成本为零。如果你有一个规则丰富的 workflow，比如 handoff procedures、content review protocols、release checklists，把它们放进 skill 而不是 CLAUDE.md，可以让 always-on context 保持小，同时仍然精确编码 workflow。

2026 年从运行几十个 skills 的团队里浮现出来的设计模式是：CLAUDE.md 捕捉适用于大多数会话的 project-wide rules。Skills 捕捉只在 workflow active 时适用的 workflow-specific rules。这个拆分和 global-vs-project CLAUDE.md 有点像，但轴不同：always-applicable vs sometimes-applicable。

什么该放 skill，而不是 CLAUDE.md

五类规则通常应该放 skill，而不是 CLAUDE.md。

Workflow procedures。 针对特定用户意图触发的 multi-step processes。Handoff procedures（/handoff）、release procedures（/release）、planning procedures（/gotoplan）、review procedures（/review）。关于“怎么交接一个会话”的规则，在你没有交接时不适用，所以不该在那些会话的 context 里。

Format specifications。 当 workflow 需要特定输出格式（experience note schema、HANDOFF.md schema、plan-file format）时，format spec 应该放在生产或消费这个格式的 skill 里。如果这个格式经常被引用，CLAUDE.md 可以有一行 pointer 指过去。

Tool-specific configurations。 关于如何使用某个特定 tool 的规则：什么时候调用、传什么 flags、怎么解读 output。例子包括某个 API client 的使用规则，或者为了某个特定 tool 按特定方式 format git commits 的规则。如果规则只在 tool 被使用时重要，就应该靠近 tool invocation，而不是放进 always-on CLAUDE.md。

一次性操作演练。 “Run the daily forgotten-scan.” “Run the weekly digest cleanup.” 这些是 scheduled 或 on-demand actions，有具体 procedure，但不适用于大多数会话。

很长的参考材料。 如果一条规则需要五段背景才可应用，那五段应该放 skill，不该放 CLAUDE.md。CLAUDE.md 偏好短、可证伪的规则；skills 可以容纳更长 prose，因为它们只在需要时加载。

什么仍然属于 CLAUDE.md

有五类内容不适合迁到 skills，因为它们每个会话都适用。

项目定位。 项目是什么，跑什么 stack，给谁用。agent 每个会话都需要。

硬流程规则。 “All changes go through PR.” “Tests must pass before merge.” 这些普遍适用，而且要在会话开始时可见，才能在任何 tool 被调用前约束决定。

语言和风格承诺。 什么语言，什么 framework，什么命名。只要写代码就适用。

会在很多任务里出现的操作事实。 “This path is a symlink.” “The CI matrix runs Linux only.” 如果一个 fact 适用于多个 workflows，它就属于 CLAUDE.md。

原则。 没有其他规则适用时会用到的规则。按定义，它们需要在每个会话里出现。

Skill triggers 和 description field

skill 加载机制值得单独讲一下，因为 trigger semantics 很容易被误解。

每个 skill 的 frontmatter 里有一个 description field。Claude Code harness 会把用户意图和 skill descriptions 比对，并提示调用匹配的 skill。这个匹配不是 literal substring search，而是 intent matching。所以 description 应该描述 skill 服务的用户意图，不是 skill 内部执行的 procedure。

有效的写法：

description: |
  Use this skill when the user wants to wrap up a session and produce
  a brief for the next session. Triggers on '/handoff', '收尾', '总结一下',
  '交接', or 'wrap up'. Skip pure Q&A or mid-execution unstable state.

无效的写法：

description: Handoff skill that generates a YAML brief in Schema A or B format.

第一种描述用户意图（wrap up、ending a session），并列出显式 invocation triggers。第二种描述 implementation，matcher 很难把它连回用户意图。

经验法则是：skill descriptions 写的是 什么时候调用，不是 skill 内部做什么。procedure 放在 body 里。

一个迁移例子

常见情况是这样：CLAUDE.md 长出一个 60 行的 section，叫 “How to write a HANDOFF file.” 这个 section 有 schema、format rules、do/don't list、examples。它精确、有用。但它也是每个非结束会话里的 dead weight，而大多数会话都不是结束会话。

迁移方法：把这个 section 抽到 ~/.claude/skills/handoff/SKILL.md。frontmatter description 保持紧（“Use when the user wants to wrap up a session...”）。body 保留原来 CLAUDE.md 里的 schema、rules、examples。在 CLAUDE.md 里，用一行替换原来的 60 行：

Session ending: invoke /handoff. Schema and format rules in the skill.

这就是迁移。CLAUDE.md 每个会话都短了 60 行。规则仍然被编码着，agent 会在 /handoff 被调用时读到。相关 context 在相关时加载；其他时候 dead weight 消失。

同样模式适用于 plan-management procedures、review checklists、release runbooks、content review protocols，以及任何规则丰富但不常激活的 workflow。

什么时候 skills 是错误选择

skills 不总是更好。有三种情况，规则应该留在 CLAUDE.md。

规则每个会话都适用。 如果 agent 在做任何决定前都需要知道这条规则，它就必须在 CLAUDE.md 里。硬流程规则和项目定位是典型例子。

规则很短。 把一行规则迁到 skill，带来的间接性和维护成本比节省的 context 多。skills 适合 procedure 足够长、scope loading 有意义的情况。

规则依赖 always-on enforcement。 如果规则需要 hook 来执行，hook 需要在会话开始时知道这条规则。CLAUDE.md 是承载这类规则的自然位置。

合在一起看

mental model 是：CLAUDE.md 是 agent 的持久 operating context，短、密、always loaded。Skills 是 agent 的 situational briefings，详细、流程化、按需加载。两者配合，你可以编码丰富的行为规则，而不用为所有规则都付 always-on context 成本。

多数用了 Claude Code 一年的项目都在迁移中：它们的 CLAUDE.md 太长，因为积累了本该是 skills 的 workflow-specific sections。修复路径是识别这些 workflow sections，把每个抽成 skill，并在 CLAUDE.md 里用一行 pointer 替换。更短的 CLAUDE.md 加更丰富的 skills，比原来那份长 CLAUDE.md 承重更多。

如果你还没写过 skill，最便宜的第一个，是你最常做、而且形状清楚的 workflow。Session handoffs 是容易的第一目标，因为每个团队都会做，而且格式很明确。Plan-writing 也是。Code review 也是。有了一个能工作的 skill，第二个和第三个会很快，而把 workflow rules 从 CLAUDE.md 迁出去也会变成机械动作。

CLAUDE.md 和 skills 不是竞争对手。它们是 agent operating context 的两半，只是按不同目的用不同 scope。知道一条新规则该放哪一半，是你能在 harness 里做的最清楚的设计决定之一；当你发现现有分布错了时，这也是杠杆最高的 refactor 之一。