CLAUDE.md vs Skills: What Belongs in Each?

Use CLAUDE.md for the stable instructions Claude needs across work in a project. Use skills for reusable procedures or specialist guidance that is needed for a particular task. Keep changing tasks, accepted decisions, and progress in a shared record such as fenbs, rather than copying the current state into both kinds of file.

The difference is purpose, not file length alone. A short procedure can still belong in a skill, and an important rule should remain visible even when no skill is invoked. This comparison focuses on Claude Code; do not assume another Claude surface loads the same files in the same way.

Which instructions should remain available across tasks?

Put information in CLAUDE.md when omitting it would make many ordinary tasks start incorrectly. That could include the package manager, the correct test entry point, or the rule that payment calculations belong in the service layer. These instructions help the assistant make basic choices before it knows which specialist workflow it will need.

Use a concrete test: would a developer need this instruction while fixing an unrelated typo, investigating a calculation, and adding a small interface feature? If yes, broad project guidance is a reasonable home. If it matters only during a quarterly export, it probably does not need to occupy every session.

Anthropic’s memory documentation↗ (opens in a new tab) explains that instruction files provide context rather than enforced configuration. Write rules clearly, but do not mistake their presence for proof that the assistant followed them. Review behavior against the project’s actual requirements.

For wording examples, see CLAUDE.md examples. The important distinction here is between a durable expectation and the steps for one kind of work. Keep the expectation easy to find even if you move its detailed procedure elsewhere.

When does guidance become a reusable procedure?

A skill becomes useful when you keep pasting the same sequence of instructions for a recognizable job. A release review might inspect a change, check the documentation, run a selected test set, and produce a structured report. That sequence has a trigger and an outcome, making it easier to reuse as a named workflow.

A good procedure explains its inputs, the steps to follow, the evidence to collect, and the result to return. It also says when to stop for missing information. “Review the code carefully” is an aspiration; a checklist describing which behavior to inspect and how to report a finding is something a person can evaluate.

CLAUDE.md
- Preserve existing public responses unless a change is approved.
- Report the checks actually run and any unverified behavior.

Review skill
- Read the requested diff and its acceptance criteria.
- Trace changed inputs through the affected code.
- Check error cases and compatibility with existing callers.
- Return supported findings with a concrete failure scenario.

The first two rules should matter outside reviews too. The checklist supplies detail for the review task without repeating the entire project orientation. Browse Claude skills examples for other procedures that benefit from this separation.

Do not create a skill just to give every paragraph a separate filename. If nobody can say when to invoke it, the split may create more searching than value. A small project with a few stable instructions can work well with one well-maintained file.

How do loading and invocation differ?

Claude Code makes applicable project instructions available as context, while a skill’s full instructions load when it is used. Skills can be invoked directly and can also be selected when relevant, subject to their configuration. Check the official skills documentation↗ (opens in a new tab) for the supported behavior in your setup.

That difference affects what can safely live only in a skill. A rule every task needs should not depend on the assistant guessing that a specialist workflow is relevant. Keep a universal approval boundary in the project guidance, then repeat the reminder inside a sensitive procedure only when it helps a person understand the step.

Test the intended path. Start a fresh session, check which project instructions loaded, and invoke the skill on a small sample task. Ask the assistant to describe its required inputs before it acts. If you cannot discover or invoke the skill reliably, fix that before entrusting a larger job to it.

Neither arrangement makes a successful outcome automatic. A loaded instruction may be ambiguous, a skill may contain a stale command, and a task can still lack essential evidence. The placement decision improves the workflow; verification establishes whether that workflow worked on the current task.

What should stay outside both files?

Keep the current assignment, its accepted plan, outstanding checks, and where work stopped with the task itself. Those facts can change several times in a day. Turning them into standing instructions leaves later sessions unsure whether they describe today’s work or a permanent requirement.

Say a developer is replacing a checkout message. The standing rule is to preserve the payment calculation. The reusable procedure explains how to review customer-facing messages. The current task says the new wording is approved, a screen check remains, and the next person should start there. Each record answers a different question.

Separate an accepted decision from a proposed shortcut as well. An assistant may suggest skipping a check; that suggestion does not rewrite the project’s rule. Save the person’s choice and its scope. In fenbs, Decisions and rules keep those choices with the shared project rather than in competing local copies.

Can a skill manage or update CLAUDE.md?

Yes, a reusable procedure can help audit a file and propose changes. Give it a narrow job: identify repeated instructions, dead links, conflicting commands, and entries that describe temporary state. Require an explanation for each proposed change so a shorter file does not quietly lose an important boundary.

For example, the procedure can classify each entry as keep, clarify, move, or remove. A reviewer should decide whether an instruction reflects a project choice or a mistaken assumption. The assistant should not turn its own preferred tool or workflow into a permanent rule merely because it is editing an instructions file.

Use the dedicated CLAUDE.md audit guide for that workflow. If the problem is that an existing file is not being seen, use CLAUDE.md not working instead. Reorganizing a missing file will not make it load.

How should you move content without losing useful guidance?

1. Choose one procedure people already repeat. Write down the trigger and the output it should produce.
2. Move its detailed steps into a skill, keeping broadly relevant rules in the project instructions.
3. Point to existing reference material instead of copying long sections that have another maintained home.
4. Run a representative task and compare the result with the previous workflow. Check both behavior and the final report.
5. Review any duplicate lines. Keep a deliberate reminder where it helps, but avoid two separately maintained versions of the procedure.

If you need a packaging walkthrough, follow how to create a Claude skill. Work in small steps so a broken move is easy to spot. Moving every instruction at once makes it hard to tell whether a missed rule came from loading, wording, or the procedure itself.

Which controls protect actions that need approval?

Treat both instruction files and skill text as guidance for the assistant. For actions with real consequences, configure appropriate tool permissions and restrict access to the underlying service. Anthropic’s permissions guide↗ (opens in a new tab) explains the available controls; choose them for the actual environment rather than relying on a warning sentence.

A review skill should not grant a deployment credential just because deployment appears in a later checklist. Ask whether the current job needs that access at all. Keep proposed changes, approved changes, and authorized actions distinct so the workflow remains understandable to the person responsible for it.

How to do this with fenbs

1. Create a free account and add the project whose instructions you want to organize.
2. Save your reusable procedure in Skills and prompts, including its purpose and expected result.
3. Record the standing rules people have agreed in Decisions and rules. Keep unanswered choices open.
4. Keep the active plan and verification result on the task. Ask the connected assistant to save progress before ending the session.

fenbs is free for one person, with no credit card. It does not automatically install or synchronize a local SKILL.md file. If your work stays entirely inside one repository and one tool, local files may be enough; the shared record becomes useful when several people or supported assistants need the same decisions and next steps.