Five Layers Inside Claude Code: Memory, Skills, Hooks, Subagents and Plugins

Plenty of engineers treat Claude Code as a very capable coding assistant: open a terminal, hand over a task, let it read files and run commands, and watch the work move forward. That description is accurate and incomplete. Anthropic's documentation presents it as an agentic coding tool that lives in the terminal, understands a codebase, carries out routine tasks and reaches external systems through mechanisms like MCP. Read closely, the product is less a model wrapped in a command-line shell and more a structured agent runtime with several distinct control surfaces.

Those surfaces include a CLAUDE.md file that persists as memory, reusable Skills, deterministic Hooks, Subagents to which work is delegated, Plugins that can be installed, and MCP links to external systems. So the useful question shifts. Asking what Claude Code can generate matters less than asking how its behaviour can be shaped, constrained, specialised and shared across a team.

A stack in five layers

A base model can write code, explain files and answer questions. On its own it leaves several things unsolved: remembering a project between sessions, reusing task expertise, enforcing guardrails at the infrastructure level, limiting what gets delegated, and distributing consistent behaviour to a team. Those concerns live outside the prompt, and Claude Code's design increasingly reflects that. The docs describe persistent instruction files, extendable Skills, custom subagents, hooks, settings scopes, plugins and MCP connectivity as separate mechanisms. Together they are not a grab bag of features. They form layers that make agent behaviour more dependable, reusable and manageable:

1. CLAUDE.md is the memory and policy layer.
2. Skills are the knowledge layer, supplying expertise on demand.
3. Hooks are the guardrail layer, enforcing rules deterministically.
4. Subagents are the delegation layer, handling bounded side work.
5. Plugins, together with scoped settings, are the distribution layer.

MCP and agent-team patterns wrap around the stack as the systems that tie it to the outside world.

The framing explains a pattern in failed agent projects: the model was rarely the weak point. A layer was missing. One team relies entirely on prompting with no persistent project memory. Another has thorough instructions but no deterministic controls around risky tool use. A third overloads one generalist agent when the work should be split across specialists. Most agent failures are architectural, not prompt problems. Each layer is covered below, starting at the base.

Why an architectural lens beats a feature list

Looking at Claude Code as a list of features invites the question of what it can do. Looking at it as an architecture invites a better one: which layers does it expose for controlling how agent behaviour is shaped, constrained, delegated and shared? Once the question changes, the stack becomes easy to reason about, and so does the diagnosis when something goes wrong in practice.

Two points follow from the documentation. First, none of these mechanisms lives inside the model. They sit around it, in files, event handlers, configuration scopes and packaging formats. Second, each one answers a different failure. Memory answers forgetting, skills answer generic behaviour, hooks answer unreliability, subagents answer cluttered context, and plugins answer the cost of repeating a good setup by hand.

Layer one: CLAUDE.md as memory

The foundation is CLAUDE.md. The docs describe it as the place for persistent instructions about how to work in a project, while a separate auto memory feature stores notes Claude writes for itself after repeated corrections and preferences.

The split matters. CLAUDE.md is not a scratchpad for temporary prompts. Teams put long-lived context here: house coding standards, past architectural decisions, favoured libraries, review checklists and workflow limits, anything that ought to be in view before the first message of a session.

How it loads is the interesting technical part. It is not a single file read only from the current directory. Claude walks up the directory tree from the working directory and loads each CLAUDE.md and CLAUDE.local.md it finds. The files are concatenated into context instead of overriding one another, and instructions nearer the launch directory are read later.

That makes it a scoped memory system, not a lone config file. A top-level file can hold repository-wide rules such as naming conventions, test expectations or architectural boundaries, and a file deeper in the tree can narrow behaviour for one subsystem. Picture a monorepo: the root file states how tests are named and where service boundaries lie, while a file inside the payments directory adds the stricter rules that apply only there. Whoever starts a session in that directory gets both, with the more specific guidance read last.

Imports add composability. An @path/to/import syntax lets teams split large instruction sets into smaller reusable modules, so that one markdown file does not turn into a junk drawer. Launch expands the imported files into context, and an import may itself import others, up to five hops down. In practice, CLAUDE.md behaves more like a composable project memory than a static prompt template.

Auto memory differs in role. Both are loaded at the beginning of every conversation, but CLAUDE.md holds what humans deliberately wrote, while auto memory holds Claude's own accumulated notes in a machine-local directory, indexed through MEMORY.md. Only the first 200 lines or 25 KB of that index load at session start. CLAUDE.md files, by contrast, load in full regardless of length, although Anthropic observes that shorter files get followed better. One is controlled and declarative; the other is adaptive and emergent.

A better mental model than "context pasted once so Claude remembers a style" is a working charter for the agent. Anthropic even specifies organisation-wide locations for centrally managed CLAUDE.md files across the major desktop operating systems, which signals that this layer is meant for durable operating policy and not only personal taste. It spares teams from restating the same constraints each session and gives the agent a stable baseline before any task-specific work starts.

A practical consequence of the loading rules is that CLAUDE.md deserves editorial care. Because every discovered file is loaded in full, bloat is paid for in every session, and the guidance that Anthropic gives about shorter files being followed better is a reason to prune regularly. Procedures that have outgrown the file are the first candidates to move out, which leads directly to the next layer.

Layer two: Skills as on-demand knowledge

If CLAUDE.md is persistent memory and policy, Skills provide modular expertise that arrives when needed. Per the documentation, writing instructions into a SKILL.md file is how Claude gains a new ability. A slash command calls a skill explicitly, or Claude may pull it in by itself when it decides the task fits.

The architectural point is timing. A skill's body is not permanent project memory. It enters context only when required, so reusable procedures, checklists and domain guidance can be attached without bloating every session.

Many engineers treat customisation as one long prompt: stuff everything into persistent context and hope the model works out what matters. Skills are a more structured option. Anthropic recommends creating one when the same instructions get pasted repeatedly, or when a section of CLAUDE.md has grown from a fact into a procedure. CLAUDE.md should carry durable project rules; Skills should carry reusable operational know-how. That keeps always-loaded context lean and turns complicated workflows into modules Claude can pull in when appropriate.

Skills are also not simply renamed custom commands. Older .claude/commands/.md files and newer .claude/skills//SKILL.md definitions behave similarly at the point of invocation, but skills add control. They allow a directory with supporting files, decide whether the user, Claude or both may trigger them, support dynamic context injection and can even run inside a subagent. That is why "knowledge layer" fits: a skill is the unit through which expertise, procedures and task context become composable inside the runtime.

Think of a skill as a sealed packet of knowledge for one kind of job. Its description states the purpose, matching at runtime decides whether it fits the current request, and the instructions inside get loaded only when they would help. The documentation notes that bundled skills such as /debug, /loop and /simplify are prompt-based, not fixed logic, which is a telling clue about the design. Behaviour becomes modular without hard-coding everything into the core product, a far more scalable pattern than expecting one giant base prompt to cover every workflow.

Consider a team with a standard method for debugging flaky tests, reviewing SQL migrations or drafting release notes. Persistent memory is too broad for those and one-off prompting is too repetitive. The team packages the procedure once, keeps reference material next to it, and Claude loads it only when the task calls for it. Long reference content inside a skill costs almost nothing until it is used, so the pattern is cleaner and also cheaper to run.

Skills therefore reward a habit of noticing repetition. Whenever the same explanation is typed a third time, or a paragraph in CLAUDE.md starts reading like a numbered procedure, it is probably a skill waiting to be extracted. The move costs a few minutes and pays back every time the task recurs.

Put together, CLAUDE.md gives the agent stable ground rules, and Skills give it targeted, reusable expertise without inflating the main context window. The next layer is what makes that behaviour safer.

Layer three: Hooks as guardrails

Hooks turn agent behaviour into something enforceable. The official docs frame them as event-driven automation: a command runs before or after a given action in Claude Code, triggered by the event itself. The hooks guide catalogues the typical uses: formatting code automatically after edits, refusing edits to protected files, restoring context once a conversation has been compacted, auditing configuration changes, refreshing environment state when files change, and pre-approving particular permission prompts.

That is a different job from prompting. A prompt can suggest behaviour; a hook can intercept or transform it deterministically. For that reason hooks are best seen as the guardrail layer, not merely an automation convenience.

A concrete case comes from the cost guide: a PreToolUse hook catches Bash commands, recognises test runs and rewrites them, so the output Claude receives contains only failures and not the full stream. Mechanically, the hook receives a JSON payload describing the pending call, examines the command, and answers with JSON that edits the tool input. Nothing in that is the AI deciding better. It is infrastructure governing what the model is allowed to see or do at that point in the workflow.

The contrast with prompt-level rules deserves emphasis. Soft guardrails are often too weak for production. Suppose generated code must always be reformatted, sensitive files must never change, or destructive tool calls need stricter review. Depending on written instructions alone is fragile, whereas hooks move the control outside the model's discretion and enforce workflow rules at the event level.

Hooks also sit beside context management, not inside it. The troubleshooting docs list "hooks not firing" as its own configuration problem, and recommend /doctor to diagnose issues with hooks, MCP servers and context usage. Both details show that hooks belong to the execution environment: configuration-driven behaviour that has to be wired correctly into the session runtime, not text Claude reads.

There is a cost angle too. Anthropic's cost guide recommends pushing processing into hooks and skills, since hooks can preprocess large inputs before the model ever sees them. Its example is filtering a huge test log down to failures only, shrinking what could be tens of thousands of tokens into a much smaller payload. So hooks serve efficiency as well as safety: they cut token waste, keep context cleaner and spare the model predictable filtering work that deterministic shell logic does more cheaply and reliably.

It helps to picture a before and after. Before hooks, a team writes "always run the formatter" in the instructions and hopes. After hooks, the formatter runs on every edit whether or not the model remembers, and a protected file simply cannot be modified. The agent still reasons freely about what to build; the hook decides what is permitted to happen around that reasoning.

Most teams underestimate this layer first. Memory helps the agent remember and skills help it specialise, but hooks convert repeated operational expectations into policy. They sit exactly where model-driven reasoning meets system-enforced behaviour, which is where many production failures actually happen. Without them, quality leans too heavily on the prompt.

Layer four: Subagents for delegation

Where hooks address control, subagents address delegation. The docs describe them as specialised AI assistants that handle particular kinds of tasks in their own context window and return only the result.

The reasoning is simple. One of the fastest ways to degrade a session is to let side tasks pollute the main conversation with logs, search output or exploratory reasoning that will never be reused. Instead of forcing one generalist through everything in a single thread, the main agent hands a side task to a specialised worker that runs independently and reports back a summary. Benefits include:

• Exploration and implementation stay out of the main conversation, preserving context.
• Limited tool access enforces constraints.
• Configurations can be reused across projects.
• Focused prompts specialise behaviour.
• Suitable tasks can be routed to cheaper models such as Haiku, reducing cost.

Calling a subagent a named prompt undersells it. What it really is: a self-contained unit of work, carrying a description, a system prompt, a chosen model, a set of permitted tools, memory settings and a runtime boundary.

Built-in examples show the intent. Explore is optimised for read-only search and codebase analysis, Plan serves planning workflows, and the general-purpose agent takes on complex multi-step work that mixes reasoning and action. The docs add that built-in subagents inherit the parent conversation's permissions plus additional tool restrictions, so delegation is bounded by design.

One more limit: subagents do not recurse. Anthropic states that a subagent cannot spawn other subagents, which is how Claude avoids infinite nesting while still gathering the context it needs. Without a hard boundary, delegation can drift into uncontrolled agent trees that are expensive, hard to monitor and hard to reason about. The model stays simple: the main agent pushes work down, the subagent does it in isolation and the result comes back up.

On the practical side, subagents are configurable at multiple scopes. They can be created interactively with the /agents command, stored per user in ~/.claude/agents/, stored per project in .claude/agents/, passed on the command line for one session, or shipped inside plugins. Each is a Markdown file with YAML frontmatter, yet the behaviour it defines is rich: model choice, tool access, memory behaviour, hooks and skills can all be scoped to that delegated worker. They are packaged execution profiles, not role labels.

This is why subagents rank among the most important layers. CLAUDE.md grounds the main agent in project rules, skills supply modular expertise and hooks enforce policy at runtime, but subagents stop everything from collapsing into one overloaded conversation with too many responsibilities. Isolation is the quiet benefit. A subagent can read dozens of files, run searches and follow dead ends without any of that exploration landing in the main thread, which receives only the conclusion. They draw hard boundaries around side work, let teams specialise workflows and keep the main context cleaner and longer-lived. With delegation in place, the remaining problem is organisational: how to package all of this for a team.

Choosing where each rule belongs

With five layers available, placement becomes a design decision. A useful test is to ask how the rule should behave. If it must always be known, put it in CLAUDE.md. If it is a procedure needed only sometimes, make it a skill. If it must be enforced no matter what the model decides, it is a hook. If the work is noisy, self-contained or suited to a cheaper model, give it to a subagent. If the whole arrangement needs to travel, package it as a plugin. Rules placed in the wrong layer tend to fail in familiar ways: a policy left in prose gets ignored, a long procedure left in memory crowds out everything else, and a clever setup left on one laptop never reaches the team.

Layer five: Plugins for distribution

Suppose a team already has its memory file, its skills, its hooks and its subagents. The issue is no longer local behaviour. It is distribution. How can that setup travel across repositories, machines and teammates without being rebuilt by hand each time?

Anthropic exposes several mechanisms for packaging and reusing behaviour across scopes: user-level and project-level subagents, shared Skills, plugin settings, organisation-wide CLAUDE.md deployment, and plugins that ship code intelligence or other capabilities. Claude Code is not configurable only for one person; it is increasingly meant for teams to standardise and distribute how the agent behaves.

The clearest official signal is the plugin and settings model. The settings documentation describes dedicated plugin configuration sections, allowlists and permissions such as codeIntelligence.*, with project-local settings and inherited user settings. It also notes that CLI arguments like the append-system-prompt and allowed-tools flags do not propagate into plugins, which confirms that plugins are bounded distribution units with their own behaviour surface, not passive extensions of the parent session. So plugins are less about adding tools and more about packaging agent behaviour so it can be installed, reused and governed at scale.

The same pattern appears elsewhere. Subagents support user-level, project-level, session-only and plugin-defined installation. Skills follow a modular design that lets reusable know-how live outside the always-loaded memory layer. The architecture does not stop at whether the agent can do something. It increasingly asks how the capability can be packaged and shared, the hallmark of a platform rather than a single-user assistant.

Governance is part of it as well. One shared bundle may hold vetted subagents, tightly limited tool permissions, standard hooks, or workflows particular to an organisation, so teams distribute policy and not just convenience. The enterprise paths for centrally managed CLAUDE.md files show that standardisation was planned from the start. The same layered design that speeds up one engineer can become a team-wide operating model in which memory, expertise, controls and delegation are shared instead of rebuilt.

What goes wrong when a layer is missing

Seen as a whole, the stack gives a practical checklist for diagnosing an unreliable agent setup. The symptom usually points at the missing layer.

• The agent keeps asking the same questions or ignoring house style. Memory is absent. Durable rules belong in CLAUDE.md, scoped by directory and split into imports where the file grows large.
• Every session starts with a long pasted procedure. Knowledge is trapped in prompts. Move the repeatable parts into skills so they load only when the task demands them.
• Risky actions depend on the model remembering to be careful. Guardrails are only suggestions. Hooks make formatting, file protection and command rewriting happen regardless of what the model decides.
• The main conversation fills with logs and dead ends. Delegation is missing. Subagents with limited tools take the noisy side work and return a summary.
• A setup that works for one person fails for the next. Distribution is missing. Plugins, shared settings and centrally managed instruction files carry the same behaviour to every repository and teammate.

The common thread is that none of these fixes is a better sentence in a prompt. They are structural changes, which is why they hold up under real workloads. Treating Claude Code as an agent development kit that happens to ship inside a terminal makes those changes easier to see, easier to discuss with a team and easier to roll out deliberately, one layer at a time.