Claude Code Agent Development Kit: All 5 Layers Explained

Most Claude Code tutorials cover CLAUDE.md in one post, hooks in another, subagents somewhere else. You end up with five tabs open and no idea how the pieces connect.

A diagram by developer Brij Kishore Pandey maps all five layers into a single stack — think of it as a community-coined "Agent Development Kit" framing. Anthropic doesn't officially brand it that way, but the architecture is real and the mental model is genuinely useful. This guide walks through each layer from the ground floor up, explains what it does, and tells you when to actually reach for it.

What Is the Claude Code Agent Development Kit?

It's a way to think about Claude Code's extensibility features as a coherent stack rather than a bag of independent tricks. Each layer has a distinct job. They compose — you can use one layer without the others, or stack all five for a fully autonomous agent system.

The community label "Agent Development Kit" comes from Pandey's diagram, not from Anthropic's documentation. What Anthropic ships are the individual features: memory files, skills, hooks, subagents, and a nascent plugin concept. The "kit" framing is the lens, not the product name.

Why think in layers?

Because the failure mode for beginners is trying to do everything in one CLAUDE.md prompt. When something breaks, you don't know which part failed. When you need to reuse a behavior across projects, you don't have a place to put it. The layer model gives you a slot for everything.

The 5-layer stack at a glance

| Layer | Name | Job | |-------|------|-----| | 1 | CLAUDE.md | Memory — persistent context loaded every session | | 2 | Skills | Knowledge — reusable, auto-invoked task modules | | 3 | Hooks | Guardrails — deterministic triggers on tool events | | 4 | Subagents | Delegation — parallel Claude instances with isolated context | | 5 | Plugins | Distribution — bundling layers 1–4 for sharing |

Layer 1 — CLAUDE.md: The Memory Layer

CLAUDE.md is the foundation. It's a plain Markdown file in your project root (or home directory) that Claude Code reads at the start of every session, automatically, without you asking.

It's not a prompt you type. It's ambient context that's always loaded. Think of it as the standing orders every session starts with.

What goes in CLAUDE.md (and what doesn't)

Good candidates: project conventions, file structure, tech stack notes, how you name branches, what commands to avoid, who the target user is.

Bad candidates: step-by-step task instructions, content that changes per task, anything you'd only need once. Those belong in a prompt or a skill.

Why it's always loaded, always active

Unlike a skill (which Claude invokes when relevant) or a hook (which fires on specific events), CLAUDE.md is unconditional. It shapes every response in every session for that project. That makes it powerful for project-wide standards and fragile if you clutter it with one-off instructions that contradict each other over time.

The difference between CLAUDE.md and a prompt

A prompt is ephemeral — it lives in one conversation. CLAUDE.md persists across sessions and is invisible to you mid-chat, which means mistakes in it silently affect all your work. Keep it lean, review it regularly, and put specifics in skills instead.

For a full breakdown of what to put in each section, see the deep dive on CLAUDE.md files.

Layer 2 — Skills: The Knowledge Layer

Skills are Markdown files that teach Claude Code how to do a specific thing — write tests in your style, format commit messages, review a PR for security issues. You save them as .md files and reference them in CLAUDE.md or via a dedicated skills directory.

What a SKILL.md file actually is

A skill is just a Markdown document with a description: field at the top. The description tells Claude when the skill applies. The body tells Claude how to execute the task.

Example structure:

---
description: Use this when writing unit tests for React components
---

## React Unit Test Standards

- Use Vitest, not Jest
- Test user behavior, not implementation details
- Always mock external API calls
...

How auto-invocation works via description matching

When Claude Code encounters a task, it scans the descriptions of available skills. If a description matches the current context, it loads the skill's content into the conversation automatically. You don't have to tell it "use the testing skill" — it figures that out.

This is the key difference from CLAUDE.md: CLAUDE.md loads everything always. Skills load selectively when relevant.

For the full setup walkthrough, see what are Claude Code skills and the auto-activation guide.

Context fork: skills and subagents

Some skill configurations route execution through a subagent, giving the skill its own isolated context window. This matters when a skill's task is long or tool-heavy enough that you don't want it polluting the main conversation's context. The context: fork frontmatter field and accompanying agent field enable this — specifying which subagent type handles execution (Explore, Plan, general-purpose, or a custom subagent). Add context: fork and the skill content becomes the prompt that drives the subagent, running in isolation without access to your conversation history. This shipped in Claude Code as documented behavior — earlier builds didn't honor these fields, so older guides may tell you to restructure the skill as a custom subagent definition instead, but that workaround is no longer necessary.

Layer 3 — Hooks: The Guardrail Layer

Hooks are the only layer that is explicitly not AI. They are deterministic scripts — shell commands, Python scripts, Node scripts — that fire on specific events during a Claude Code session.

Where CLAUDE.md and skills influence what Claude thinks, hooks control what happens around Claude's actions.

The hook event types

Claude Code exposes a large set of hook trigger points. The four most commonly used are:

• PreToolUse — runs before Claude uses a tool (file write, bash command, etc.)
• PostToolUse — runs after a tool completes successfully
• Stop — fires when Claude finishes a turn
• SubagentStop — fires when a subagent finishes (an official event, distinct from Stop)

The full event catalog is extensive — it also includes SessionStart, SessionEnd, UserPromptSubmit, PreCompact, PostCompact, SubagentStart, FileChanged, and more. See the hooks reference for the complete list.

You configure hooks in your Claude Code settings, mapping each event to a script.

Hooks are deterministic — not AI

This is the most important thing to understand about hooks. They don't ask Claude anything. They don't feed results back into the conversation as suggestions. A PreToolUse hook that blocks a rm -rf command blocks it — no negotiation, no override by the model.

That makes hooks the right place for hard constraints: security checks, compliance rules, anything that must happen regardless of what Claude decides.

Real examples

• Auto-lint on write: PostToolUse hook runs ESLint every time Claude writes a JS file
• Block dangerous commands: PreToolUse hook rejects any bash command matching a blocklist
• Slack ping on stop: Stop hook sends a Slack message when a long-running task finishes

See what are Claude Code hooks for the setup syntax, and hooks for clean code for practical examples.

Layer 4 — Subagents: The Delegation Layer

Subagents are separate Claude instances that the main Claude Code session can spawn. Each one has its own context window, its own model selection, its own tool permissions, and its own CLAUDE.md scope.

The main agent delegates a task to a subagent, the subagent executes it, and the main agent gets back a result.

Fire-and-forget vs. blocking execution

The Pandey diagram uses the shorthand "delegate-only" and "results-only" — these are not official Claude Code terms. In the official docs, the nearest equivalent is the background: true frontmatter field: setting it on a subagent definition tells Claude Code to always run that subagent as a background task (fire and forget) rather than waiting for its output.

In practice, you choose the pattern based on whether the main task depends on the subagent's output. Background subagents are useful for long-running work that doesn't need to block the main session.

Each subagent gets its own context window

This is why subagents matter. Your main session accumulates context as a task grows — files read, edits made, tool calls logged. At some point, that context gets expensive and cluttered. Delegating a well-scoped subtask to a subagent keeps it out of the main context entirely.

The subagent starts fresh, does its job, and hands back a summary. The main agent knows what was done without needing to hold all the detail.

Why subagents prevent infinite recursion

A subagent can itself spawn subagents, but each operates in its own permission scope. This nesting structure, combined with isolated context windows, is what keeps complex multi-step tasks from collapsing into a single unwieldy session. The orchestrator stays clean; the workers do the heavy lifting.

For a full explanation of the subagent model, see what are Claude Code agents.

Layer 5 — Plugins: The Distribution Layer

Plugins are the uppermost layer — they don't add new capabilities so much as they package the layers below them for easy sharing.

A plugin bundles together:

• Skills (the .md knowledge files)
• Subagent configurations
• Hook scripts
• Custom slash commands

The official marketplace is live

Anthropic's official plugin marketplace (claude-plugins-official) is a live, browse-and-install product. Run /plugin inside Claude Code and go to the Discover tab, or browse the catalog at claude.com/plugins. The official marketplace is automatically available — no setup required.

The marketplace ships plugins organized into categories: code intelligence (LSP integrations for Go, Python, TypeScript, Rust, and more), external service integrations (GitHub, Figma, Slack, Vercel, etc.), and development workflow bundles (commit helpers, PR review agents, plugin development tools).

For teams, the same plugin system lets you distribute your own skill and hook bundles internally — the "npm analogy for agent capabilities" that makes onboarding a new engineer a single install step instead of manual configuration.

Bonus: MCP Servers and Agent Teams

Two things sit alongside the five-layer stack rather than inside it.

MCP servers as the external tool bridge

Model Context Protocol (MCP) servers give Claude Code access to external systems — GitHub, databases, web search, internal APIs. They're not part of the agent development layers per se; they extend what tools are available to every layer. A subagent can use an MCP server just as easily as the main agent can.

See what is MCP for the concept and best MCP servers for beginners for a practical starter set.

Agent teams: parallel execution

When you have multiple subagents running simultaneously — one researching, one writing, one reviewing — you have an agent team. A lead orchestrator manages the team: it spawns workers, passes messages between them, and collects results. This is where Claude Code starts to feel less like a coding assistant and more like a small automated engineering team.

How the Layers Work Together: A Concrete Example

Say you're building a feature that requires writing code, adding tests, and opening a pull request.

1. CLAUDE.md tells Claude your project uses TypeScript strict mode, your branch naming convention, and to never push directly to main.
2. A skill for writing tests auto-invokes when Claude sees the task involves new functions — it knows your test framework and style preferences.
3. A PreToolUse hook fires before any git push command, running a script that checks the branch name against your convention.
4. A subagent handles the PR description generation in isolation — it reads the diff, writes the description, and hands back the text without loading all that file content into the main session.
5. A plugin (if your team has packaged this workflow) means a new engineer installs the whole setup in one step instead of configuring each layer manually.

Each layer does exactly one job. They don't overlap. When something breaks, you know exactly which layer to check.

Which Layer Should You Start With?

Start with the layer that solves your most immediate pain. Don't build the whole stack on day one.

Recommended order for beginners

1. CLAUDE.md first — even a ten-line file with your tech stack and one or two project rules will noticeably improve Claude Code's responses
2. Skills second — once you notice yourself repeating the same instructions, extract them into a skill
3. Hooks third — add guardrails after you know which mistakes Claude makes repeatedly in your codebase
4. Subagents fourth — reach for these when tasks get long enough that context pollution becomes a real problem
5. Plugins last — only relevant once you have a working setup worth packaging and sharing

One-line rule for each layer

• CLAUDE.md: If it's true for every session in this project, it belongs here.
• Skills: If you've typed the same instruction three times, make it a skill.
• Hooks: If it must happen regardless of what Claude decides, use a hook.
• Subagents: If a subtask would fill up your context window, delegate it.
• Plugins: If your team should all have the same setup, package it.

If you're choosing between Claude Code and a browser-based AI coding tool, the architecture described here is one of the core reasons Claude Code has an edge for complex projects — see the Claude Code vs Cursor comparison for beginners and how Claude Code's agent model differs from Claude.ai for more context.

The natural next step is getting Claude Code running on your machine, then dropping a simple CLAUDE.md in your main project. Everything else follows from there.