title: "Agent Development Kit" description: "6-layer model - understand the complete architecture" section: "Core" readTime: "18 min" badge: "POPULAR"

Agent Development Kit: The 6-Layer Model

"Claude Code isn't a coding assistant. It's an agent platform."

Most people are using 10% of it.

The key is understanding the 6-layer composition model that powers everything.

Layer 1: CLAUDE.md — Memory Layer

Your agent's constitution.

Think of it as an employee onboarding document, not a novel. Keep it under 200 lines.

## Tech Stack
- Node.js 20
- TypeScript
- React 19
 
## Conventions
- Kebab-case filenames
- camelCase variables
- ESLint strict mode
 
## Architecture
- /src/app (Next.js App Router)
- /src/components (React)
- /src/lib (utilities)
 
## Security
- No .env in git
- API keys environment-only
- Rate limiting on all endpoints

What goes in CLAUDE.md:

• Tech stack (not installation instructions)
• Coding conventions (not tutorials)
• Architecture overview (not detailed design)
• Hard constraints (banned patterns, security rules)
• Key file locations (not every file)

What belongs in Skills instead:

• Multi-step workflows
• Complex procedures
• Decision trees
• Testing strategies
• Deployment procedures

Layer 2: Skills — Knowledge Layer

Extend your agent with reusable knowledge modules.

Skills use the Agent Skills open standard (agentskills.io).

Skill Anatomy

---
name: db-migrate
description: "Safe schema migrations with rollback. Use when adding or changing database tables."
user-invocable: true
disable-model-invocation: false
allowed-tools: ["Read", "Bash(npx prisma *)"]
model: "sonnet"
effort: "high"
context: "fork"
hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          if: "Bash(*ALTER TABLE*)"
          command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-migration.sh"
paths:
  - "db/migrations/**"
  - "prisma/schema.prisma"
---
 
# Database Migration Skill
 
Use this skill to create safe migrations...
 
## Usage
- /db-migrate "add users table"
- /db-migrate --rollback
 
## Current schema
!`head -20 prisma/schema.prisma`

Skill Frontmatter Fields

Dynamic Context: Code Injection

$ARGUMENTS             # All arguments as typed
$ARGUMENTS[0]          # First argument (shorthand: $0)
${CLAUDE_SESSION_ID}   # Current session UUID
${CLAUDE_SKILL_DIR}    # Skill directory path
 
!`git log -1 --oneline`  # Shell output injection (runs before Claude sees the skill)

A skill is a directory with a required SKILL.md (e.g. .claude/skills/db-migrate/SKILL.md) plus optional supporting files such as reference.md or scripts/, which load only when needed. Keep SKILL.md under 500 lines.

Skill Scope Priority

1. Enterprise (global across org, managed policy)
2. Personal (~/.claude/skills/)
3. Project (.claude/skills/)
4. Plugin (namespaced as /plugin-name:skill-name, so they never collide with the others)

When the same name exists at several levels, the higher one wins: enterprise over personal, personal over project.

Skill directories are watched live — adding or editing a SKILL.md takes effect in the current session without restarting. If you create a brand-new top-level skills directory mid-session, run /reload-skills.

In monorepos, skills in nested .claude/skills/ directories are discovered automatically the first time Claude reads or edits a file in that subdirectory.

Layer 3: Hooks — Guardrail Layer

Hooks intercept Claude Code at specific points:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/confirm-rm.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git commit *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/notify-commit.sh"
          }
        ]
      }
    ]
  }
}

Common Hook Events:

• PreToolUse — Before a tool call; can block it or ask for confirmation
• PostToolUse — After a tool call succeeds
• Notification — When Claude Code sends a notification
• Stop — When Claude finishes responding
• SessionEnd — When a session terminates

There are no dedicated events for commits or file deletion; filter PreToolUse/PostToolUse with matcher and if instead. See Hooks for the full format.

Layer 4: Subagents — Delegation Layer

Isolate context. Run agents in parallel.

---
context: fork    # Runs in isolated subagent
---
 
This skill always runs in a fresh context window.
It starts in the same working directory and sees
the same files, but none of the main conversation.

A subagent gets its own context window, system prompt, and tool access — but not a separate filesystem. For an isolated copy of the repo, a custom subagent can set isolation: worktree.

Built-in Agent Types:

• Explore agent (read-only codebase search and analysis)
• Plan agent (read-only research during plan mode)
• General-purpose agent (all tools; complex multi-step tasks)

Define your own as Markdown files with name/description frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (personal).

Parallel Execution:

/batch migrate all API routes from Express to Fastify

/batch takes one instruction, researches the codebase, splits the work into 5–30 independent units, and — after you approve the plan — runs one background subagent per unit in its own git worktree.

Each parallel agent consumes its own tokens, so parallelism costs more in total but saves wall-clock time.

Layer 5: Plugins — Distribution Layer

Bundle skills, subagents, hooks, and MCP servers into one installable unit. A plugin is a directory with a manifest — not an npm package:

acme-tools/
├── .claude-plugin/
│   └── plugin.json        # manifest (only this file goes here)
├── skills/
│   ├── db-migrate/SKILL.md
│   └── deploy/SKILL.md
├── agents/reviewer.md
├── hooks/hooks.json
└── .mcp.json

{
  "name": "acme-tools",
  "description": "Acme's shared Claude Code setup",
  "version": "1.0.0"
}

Components are discovered from their standard directories; plugin skills run as /acme-tools:db-migrate.

Plugins are distributed through marketplaces (catalogs listed in a .claude-plugin/marketplace.json). Install:

# Inside a session (opens the plugin's details so you can pick a scope)
/plugin install commit-commands@claude-plugins-official
 
# From your shell
claude plugin marketplace add your-org/plugins
claude plugin install acme-tools@your-org --scope project
 
# Test locally without installing
claude --plugin-dir ./acme-tools

Bundled Skills (Pre-Loaded)

Type / for the full current list; the disableBundledSkills setting turns them all off.

Layer 6: Auto Memory — Learning Layer

Claude writes notes for itself across sessions — without you doing anything.

What Claude remembers:

• Build commands it discovered
• Debugging insights from your sessions
• Architecture patterns specific to your project
• Code style preferences it inferred

Storage: ~/.claude/projects/<project>/memory/MEMORY.md plus topic files (debugging.md, api-conventions.md, etc.).

The first 200 lines / 25KB of MEMORY.md load at every session start. Topic files load on demand.

# Browse and edit memory in a session
/memory

Putting It Together: A Real Example

Project Structure:
├── CLAUDE.md                    # Layer 1: Memory
├── .claude/
│   ├── skills/
│   │   ├── db-migrate/SKILL.md # Layer 2: Skills
│   │   └── deploy/SKILL.md
│   ├── agents/                 # Layer 4: Custom subagents
│   └── settings.json           # Layer 3: Hooks
├── .mcp.json                   # MCP config (project root)
├── .git/
└── src/

User runs: claude "Add user authentication"

Agent process:

1. Reads CLAUDE.md (constraints, tech stack)
2. Checks hooks (pre-tool safety rules)
3. Searches for relevant Skills
4. Creates plan (ask for approval)
5. Forks subagent if using isolation
6. Executes with fallback to Layer 2, 3 constraints
7. Logs via Hooks (Layer 3)

Programmatic Access: Claude Agent SDK

Every layer above also works when you embed Claude Code in your own app. The Claude Agent SDK (formerly the Claude Code SDK) gives Python and TypeScript the same tools, agent loop, and context management that power the CLI.

npm install @anthropic-ai/claude-agent-sdk   # TypeScript (Node.js 18+)
pip install claude-agent-sdk                 # Python 3.10+
export ANTHROPIC_API_KEY=your-api-key

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
    settingSources: ["user", "project"] // load CLAUDE.md, skills, hooks
  }
})) {
  if (message.type === "result") console.log(message.subtype);
}

See the Agent SDK overview for sessions, permissions, MCP, and hosting.

Composition Benefits

✅ Reusable knowledge (Skills)
✅ Safety guardrails (Hooks)
✅ Scalability (Plugins)
✅ Isolation (Subagents)
✅ Governance (CLAUDE.md)
✅ Persistent learning (Auto Memory)

Next: Explore Architecture for runtime details, or dive into Skills and Auto Memory for deep-dives.