Claude Code’s 5-Layer Architecture: CLAUDE.md, Skills, Hooks, Subagents & Plugins
Most engineers think of Claude Code as an AI coding assistant: give it a prompt, let it inspect the codebase, and ask it to make changes.
But there’s much more happening underneath.
Claude Code can be understood as a five-layer agent architecture, with each layer solving a different problem that a language model alone cannot reliably solve.
These aren't simply features or configuration options. They are layers for rules, knowledge, guardrails, delegation, and distribution.
And perhaps the most interesting part is that much of this architecture isn't about prompting at all.
Here’s how the five layers fit together.
The 5 Layers of Claude Code
At a high level:
CLAUDE.md → Skills → Hooks → Subagents → Plugins
Each layer adds a different capability to the agent.
LayerPurposeCore Question
CLAUDE.md
Rules & persistent context
What should the agent always know?
Skills
Specialized expertise
How should it perform this task?
Hooks
Deterministic guardrails
What must happen before or after an action?
Subagents
Delegated execution
What work should be handled separately?
Plugins
Distribution
How do we package and share agent behavior?
External integrations through MCP servers and parallel execution through Agent Teams can then extend the architecture even further.
Let's break down each layer.
Layer 1 — CLAUDE.md: The Agent’s Constitution
The first layer is CLAUDE.md.
Think of it as the persistent instruction and context layer for your coding agent.
It can contain information such as:
- Architecture rules
- Naming conventions
- Coding standards
- Testing expectations
- Repository structure
- Development workflows
- Important project conventions
The key advantage is that this information doesn't need to be repeated in every prompt.
A project can maintain its own:
.claude/CLAUDE.md
while broader instructions can be maintained at a global level, such as:
~/.claude/CLAUDE.md
This creates a persistent foundation for how the agent operates.
Think of CLAUDE.md as the agent's constitution.
It defines the rules and context that should consistently guide its work.
Layer 2 — Skills: Modular Expertise
The second layer is Skills.
Skills solve a different problem.
Instead of putting every possible instruction into the agent's permanent context, you can package specialized knowledge into reusable Skills.
A Skill typically includes a SKILL.md file and can also contain supporting resources such as:
- Reference documents
- Scripts
- Templates
- Examples
- Task-specific instructions
The agent can identify when a particular Skill is relevant and load that expertise when needed.
For example, you might have Skills for:
- Writing technical documentation
- Reviewing pull requests
- Generating release notes
- Running a specific testing workflow
- Working with a particular framework
- Following an organization's deployment process
The important idea is on-demand expertise.
You don't need every possible workflow loaded into the main context all the time.
Think of Skills as specialized playbooks.
CLAUDE.md says:
"These are the rules you should follow."
A Skill says:
"Here's how to perform this particular type of task."
Layer 3 — Hooks: Deterministic Guardrails
This is one of the most powerful—and often overlooked—layers.
Hooks allow you to execute deterministic actions around agent events.
Examples include:
- PreToolUse
- PostToolUse
- SessionStart
- Stop
- SubagentStop
Unlike an LLM instruction, a hook isn't asking the model to remember to do something.
It's an event-driven mechanism that can enforce behavior.
For example:
Before a tool runs:
PreToolUse → check command → allow or block
After a file is written:
PostToolUse → run lint → report result
When a session stops:
Stop → send notification
You could use hooks to:
- Automatically run linters
- Block dangerous commands
- Run validation after changes
- Trigger notifications
- Enforce development policies
This creates an important distinction:
Prompts provide guidance. Hooks can provide enforcement.
If a rule is important enough that you don't want to rely on the model remembering it, a deterministic mechanism can be a better fit.
Layer 4 — Subagents: Delegating Work
The fourth layer is Subagents.
As tasks become more complex, having one agent perform everything inside a single context window can become inefficient.
Subagents allow the main agent to delegate specific work.
A subagent can have its own:
- Context window
- Model
- Tools
- Permissions
- Specialized instructions
The main agent delegates a task, the subagent performs it, and the result is returned to the main agent.
For example, an agent might delegate:
Main Agent ↓ Code Reviewer ↓ Review results
or:
Main Agent ├── Explorer ├── Test Runner └── Code Reviewer
This separation can keep the primary agent's context cleaner while allowing specialized work to happen independently.
Think of subagents as specialized workers.
The main agent coordinates.
The subagent executes a defined piece of work.
Layer 5 — Plugins: Distributing Agent Behavior
The fifth layer is Plugins.
Once you've created useful Skills, agents, hooks, and commands, you may want to distribute them across a team.
Plugins provide a way to package agent capabilities together.
A plugin can bundle components such as:
plugin/ ├── skills/ ├── agents/ ├── hooks/ └── commands/
Instead of asking every engineer to manually recreate the same setup, the team can install the package and inherit the same agent behavior.
This is conceptually similar to how software packages distribute reusable functionality.
Think of Plugins as the distribution layer.
Skills teach the agent something.
Hooks enforce behavior.
Subagents perform specialized work.
Plugins package those capabilities so they can be shared.
Where MCP Fits
The five layers don't exist in isolation.
MCP servers provide another important part of the architecture: external connectivity.
MCP can expose capabilities such as:
- External tools
- Databases
- APIs
- GitHub
- Internal systems
- Custom integrations
This means the agent isn't limited to the information and tools available inside its immediate environment.
A simplified architecture looks like:
CLAUDE.md
│
▼
Skills
│
▼
Hooks
│
▼
Subagents
│
▼
Plugins
│
┌──────────┴──────────┐
▼ ▼
MCP Servers Agent Teams
│ │
▼ ▼
External Systems Parallel Work
MCP provides reach into external systems, while the five layers provide different mechanisms for controlling and organizing agent behavior.
Why This Architecture Matters
The bigger lesson isn't about memorizing five Claude Code features.
It's about understanding how AI agents are evolving.
A basic AI workflow looks like:
Prompt → Model → Response
A more capable engineering agent looks more like:
Rules → Knowledge → Guardrails → Delegation → Distribution → External Tools → Execution
That's a significant shift.
The model is still the reasoning engine, but the surrounding architecture determines how reliably that reasoning can be turned into useful work.
The 5-Layer Stack in One Line
If you remember only one thing, remember this:
CLAUDE.md sets the rules → Skills provide expertise → Hooks enforce quality → Subagents delegate work → Plugins distribute capabilities.
And around that stack, MCP connects external systems, while Agent Teams enable broader parallel orchestration.
The future of AI-assisted engineering isn't just about better prompts or bigger models.
It's about building the infrastructure around those models so agents can remember rules, load expertise, follow guardrails, delegate work, access external systems, and operate consistently across teams.
That's what turns an AI coding assistant into an agent development platform.