Claude Code Instructions, Skills & Agents: What Goes Where

Claude Code’s instructions, skills, and agents are three separate configuration layers: instructions (CLAUDE.md files) set persistent project or user preferences, skills add reusable procedural knowledge, and agents are custom subagents with specialized system prompts. You put global or project-wide rules in CLAUDE.md, package reusable workflows as skills, and define focused task-specialists as agents in .claude/agents.

Background: Why the Separation Matters

Claude Code is Anthropic’s command-line tool for agentic coding. As it grew, users needed ways to shape its behavior beyond the built-in default. Anthropic introduced three distinct mechanisms, each with a different purpose and storage location. Mixing them up causes confusion: a skill that should be a reusable workflow ends up as a static instruction, or an agent prompt bloats CLAUDE.md and slows every session. Understanding what goes where starts with understanding what each layer is designed to do.

Instructions: CLAUDE.md Files

Instructions are the most basic layer. They are plain-text files named CLAUDE.md that Claude Code reads automatically at session start. They set persistent context, preferences, and rules. There are two scopes:

User-level: ~/.claude/CLAUDE.md applies to all your projects.
Project-level: ./CLAUDE.md in the project root applies to that project only.

You can also create nested CLAUDE.md files in subdirectories; Claude Code loads the most relevant one based on the files being edited. Instructions are best for things like: code style preferences, testing commands, architecture notes, do-not-touch files, and common pitfalls. They are always loaded, so they should be concise and high-signal. If you add too much, you waste tokens and dilute attention.

Skills: Reusable Procedural Knowledge

Skills are a newer feature (introduced in early 2025) that let you package a procedure, a set of steps, or domain knowledge into a folder that Claude Code can invoke on demand. A skill is a directory with a SKILL.md file (the instructions for when and how to use the skill) plus optional scripts, templates, or reference files. Skills live in ~/.claude/skills/ (user) or .claude/skills/ (project).

Skills are not loaded automatically. Claude Code reads the skill’s name and description and decides to use it when the task matches. This makes them ideal for workflows that are too long to put in CLAUDE.md but too generic to warrant a dedicated agent. Examples: running a specific test suite, performing a code review checklist, migrating a database schema, or following a release process. You can also create agent skills that are only available to a specific agent by placing them in the agent’s subdirectory.

Agents: Specialized Subagents

Agents (or subagents) are custom Claude Code instances with their own system prompt, tools, and model settings. They are defined as Markdown files in .claude/agents/ (project) or ~/.claude/agents/ (user). Each agent file has a frontmatter block with name, description, tools, and model, plus a body that acts as the system prompt. You invoke an agent by name (e.g., @code-reviewer).

Agents are best for focused, repeatable tasks that need a distinct persona or toolset: a security auditor, a documentation writer, a database expert, or a code reviewer. They are not automatically invoked; you call them explicitly. Because they have their own system prompt, they can be much more detailed than a CLAUDE.md entry without affecting the main agent’s behavior.

How to Choose: A Decision Guide

When you have a new behavior to add, ask three questions:

Should it always apply? If yes, put it in CLAUDE.md. If it applies to all projects, use the user-level file; if only this project, use the project-level file.
Is it a multi-step procedure that can be triggered by a description? If yes, make it a skill. Skills are perfect for things you’d otherwise paste into the chat every time.
Does it need a different persona, toolset, or strict focus? If yes, create an agent. Agents are ideal for roles that should not bleed into the main coding flow.

There is overlap: a skill can contain instructions, and an agent can use skills. But the rule of thumb is: instructions are rules, skills are procedures, agents are specialists.

Common Problems and Misconceptions

One frequent mistake is putting procedural steps in CLAUDE.md. That bloats every session and wastes tokens. Another is creating an agent for something that should be a skill—if the task doesn’t need a different toolset or persona, a skill is lighter and easier to maintain. Some users wonder if skills are loaded automatically; they are not—Claude Code decides based on the description, so a poorly written description means the skill never gets used.

Another misconception: agents can only be used in the same directory as their definition. In fact, project agents are available anywhere in that project, and user agents are available in all projects. Also, you cannot define an agent inside a skill folder; agents and skills are separate top-level directories.

Comparison: Instructions vs Skills vs Agents

Here’s a quick side-by-side:

Storage: Instructions in CLAUDE.md files; skills in skill folders; agents in agent folders.
Loading: Instructions always; skills on-demand by description; agents on-demand by name.
Content: Rules and preferences; step-by-step procedures; full system prompts with tool restrictions.
Best for: Project-wide conventions; reusable workflows; specialized roles.

You can combine them: an agent can reference a skill, and a skill can reference a CLAUDE.md rule. For example, a code-review agent might use a skill that contains the review checklist, while the project CLAUDE.md sets the coding style the reviewer should enforce.

Cost and Performance Considerations

Each layer has a token cost. CLAUDE.md files are read at every session start, so keep them lean—a huge CLAUDE.md wastes tokens and can slow down the model’s focus. Skills are only read when invoked, so they can be longer without penalty. Agents have their own system prompt that is loaded when the agent is called, so you can be very detailed there. But remember: the more tokens in the system prompt, the higher the cost per call and the more likely the model is to get distracted. Use the smallest layer that does the job.

Frequently Asked Questions

Can a skill be used by an agent?

Yes. Place a skill in the agent’s subdirectory (e.g., .claude/agents/my-agent/skills/skill-name/) and that agent will have access to it. The skill’s description should mention the agent’s task so it gets triggered at the right time.

Do CLAUDE.md instructions apply to subagents?

Yes, subagents inherit the project’s CLAUDE.md context by default, unless you explicitly override it in the agent’s system prompt. This is useful for ensuring consistency across all agents.

What happens if a skill and an instruction conflict?

There is no built-in conflict resolution. The skill’s instructions are written into the context when the skill is used, so they may override or contradict CLAUDE.md. It’s best to avoid conflicts by keeping instructions high-level and skills specific.

Can I have multiple CLAUDE.md files in one project?

Yes. You can have a root CLAUDE.md and nested ones in subdirectories. Claude Code loads the most relevant one based on the files being edited. This is useful for monorepos with different conventions per package.

Are skills available in the API or only in the CLI?

Skills are a Claude Code feature, not a general API feature. They work in the CLI and in IDE integrations that support Claude Code. The API does not automatically load skills; you’d have to implement that logic yourself.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →