Claude Code Skills and CLAUDE.md — How They Fit Together

Skills are the part of Claude Code that most people discover late. Slash commands like /handoff, /review, or /wt look like simple shortcuts, but each one is backed by a markdown file that loads scoped behavior into the agent only when invoked. The relationship between skills and CLAUDE.md is consequential — it determines what rules the agent sees in every session, what rules it sees only when needed, and where you should put a new rule when you decide to write one. This is how the two fit together as of early 2026, and how to use the relationship to keep your CLAUDE.md short while still capturing rich workflows.

What a skill actually is

A skill is a markdown file with frontmatter, stored under ~/.claude/skills/ (user-global) or .claude/skills/ (project-local). The frontmatter declares the skill's name, description, and triggering rules. The body is markdown prose that gets loaded into the agent's context when the skill is invoked.

Skills get invoked in two ways. The user can type /<skill-name> directly. Or the user can describe a task in natural language, and the harness will detect the match against the skill's description field and offer to invoke it. The second mode is the one most people miss — the description field is doing a lot of work, and a well-written description is what makes the skill actually trigger when it should.

The body of a skill can include workflow steps, format specifications, hard rules, examples, and pointers to other documents. When the skill is invoked, the entire body becomes part of the agent's working context for that workflow. This is the key architectural property: skills are scoped context, while CLAUDE.md is always-on context.

Why scoping matters

CLAUDE.md is loaded at every session start. Every line in it costs context budget every session, regardless of whether the rule is relevant to the current task. A 300-line CLAUDE.md costs you 300 lines of context for the rest of the session, even when you are debugging a one-file CSS issue and only three of those lines apply.

Skills are loaded only when invoked. A 500-line skill costs you nothing for sessions that don't invoke it. If you have a workflow with rich rules — handoff procedures, content review protocols, release checklists — putting them in a skill instead of CLAUDE.md keeps the always-on context small while still encoding the workflow precisely.

The 2026 design pattern, emerging from teams that run dozens of skills, is: CLAUDE.md captures the project-wide rules that apply to most sessions. Skills capture the workflow-specific rules that apply only when the workflow is active. The split is similar in spirit to global-vs-project CLAUDE.md, but operates on a different axis: always-applicable vs sometimes-applicable.

What belongs in a skill instead of CLAUDE.md

Five categories of rules tend to belong in a skill rather than in CLAUDE.md.

Workflow procedures. Multi-step processes that fire on specific user intent. Handoff procedures (/handoff), release procedures (/release), planning procedures (/gotoplan), review procedures (/review). The rules for "how do we hand off a session" do not apply when you are not handing off — they should not be in your context for those sessions.

Format specifications. When a workflow requires a specific output format (an experience note schema, a HANDOFF.md schema, a plan-file format), the format spec belongs in the skill that produces or consumes the format. CLAUDE.md can carry a one-liner pointing at the skill if the format is referenced often.

Tool-specific configurations. Rules about how to use a particular tool — when to invoke it, what flags to pass, how to interpret its output. Examples: rules about how to use a specific API client, rules about how to format git commits in a specific way for a specific tool. If the rule only matters when the tool is in use, the rule belongs near the tool's invocation, not in always-on CLAUDE.md.

One-off operational drills. "Run the daily forgotten-scan." "Run the weekly digest cleanup." These are scheduled or on-demand actions that have specific procedures but do not apply to most sessions.

Verbose reference material. If a rule needs five paragraphs of background to be applicable, the five paragraphs belong in a skill, not in CLAUDE.md. CLAUDE.md prefers terse, falsifiable rules; skills can afford longer prose because they only load when needed.

What still belongs in CLAUDE.md

Five categories that do not migrate well to skills, because their rules apply in every session.

Project orientation. What the project is, what stack it runs, who uses it. The agent needs this in every session.

Hard process rules. "All changes go through PR." "Tests must pass before merge." These apply universally and need to be visible at session start so they constrain decisions before any tool is invoked.

Language and style commitments. What language, what frameworks, what naming. These apply whenever code is being written.

Operational facts that surface in many tasks. "This path is a symlink." "The CI matrix runs Linux only." If the fact applies to multiple workflows, it belongs in CLAUDE.md.

Principles. The rules that apply when no other rule applies. By construction, these need to be in every session.

Skill triggers and the description field

The mechanism by which a skill loads requires brief discussion because the trigger semantics are easy to misunderstand.

Each skill has a description field in its frontmatter. The Claude Code harness compares user intent against skill descriptions and offers to invoke a matching skill. This match is not a literal substring search — it is intent matching, which means the description should describe the intent the skill serves, not the procedure the skill performs.

The pattern that works:

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.

The pattern that does not work:

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

The first describes the user intent (wrapping up, ending a session) and lists explicit invocation triggers. The second describes the implementation, which the matcher cannot tie back to user intent.

This is the rule of thumb: write skill descriptions for when to invoke, not what the skill does internally. The body of the skill is where the procedure lives.

A migration example

Here is a common situation. CLAUDE.md has grown a 60-line section called "How to write a HANDOFF file." The section has the schema, the format rules, the do/don't list, examples. It is a precise, useful section. It is also dead weight in every session that is not ending — which is most sessions.

Migration: extract the section into ~/.claude/skills/handoff/SKILL.md. Keep the frontmatter description tight ("Use when the user wants to wrap up a session..."). Keep the body — schema, rules, examples — exactly as it was in CLAUDE.md. In CLAUDE.md, replace the 60-line section with a single line:

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

That is the migration. CLAUDE.md is now 60 lines shorter for every session. The rules are still encoded — the agent reads them when /handoff is invoked. The relevant context is loaded when relevant; the dead weight is gone the rest of the time.

The same pattern works for plan-management procedures, review checklists, release runbooks, content review protocols, and any other workflow with rich rules and infrequent activation.

When skills are the wrong choice

Skills are not always better. Three cases where a rule should stay in CLAUDE.md.

The rule applies in every session. If the agent needs to know the rule before it can make any decision, the rule has to be in CLAUDE.md. Hard process rules and project orientation are the canonical examples.

The rule is short. Migrating a one-line rule to a skill costs more (in indirection, in maintenance) than it saves. Skills earn their keep when the procedure is long enough that scoping the load matters.

The rule depends on always-on enforcement. If the rule needs a hook to enforce, the hook needs to know the rule at session start. CLAUDE.md is the natural carrier for rules that are also wired into hooks.

Putting it together

The mental model: CLAUDE.md is the agent's persistent operating context — short, dense, always loaded. Skills are the agent's situational briefings — verbose, procedural, loaded on demand. Between them, you can encode rich behavioral rules without paying the context cost of always-on density.

Most projects that have been using Claude Code for a year are mid-migration: their CLAUDE.md is too long because it accumulated workflow-specific sections that should have been skills. The remediation path is to identify the workflow sections, extract each one into a skill, and replace it in CLAUDE.md with a one-line pointer. The shorter CLAUDE.md and the richer skills carry more total weight than the long CLAUDE.md ever did.

If you have not written a skill yet, the cheapest first one is the workflow you find yourself doing most often that has a recognizable shape. Session handoffs are the easy first target because every team does them and the format is well-defined. Plan-writing is another. Code review is another. Once you have one skill working, the second and third come quickly — and the migration of workflow rules out of CLAUDE.md becomes mechanical.

CLAUDE.md and skills are not competitors. They are the two halves of the agent's operating context, scoped differently for different purposes. Knowing which half a new rule belongs in is one of the cleanest design decisions you can make in your harness, and one of the highest-leverage refactors when you realize the existing distribution is wrong.