Episode 2: Layered Architecture

⏱ Est. reading time: 7 min Updated on 5/7/2026

What layers does a request pass through from user input to completion? This episode breaks down the full call chain using Mermaid diagrams.

Call Chain Overview

sequenceDiagram
    participant User
    participant CLI as Claude Code CLI
    participant Hook as Hook System
    participant Skill as Skill Engine
    participant Claude as Claude AI
    participant Tool as Tool System
    participant MCP as MCP Server

    Note over User,MCP: Scenario 1: User enters /gsd-quick

    User->>CLI: /gsd-quick fix button color
    CLI->>Hook: UserPromptSubmit Event
    Hook-->>CLI: Injects context (e.g., memory from claude-mem)
    CLI->>Skill: Matches gsd-quick SKILL.md
    Skill->>Claude: Injects Skill instructions + user input
    Claude->>Tool: Calls Read (read file)
    Tool-->>Claude: Returns file content
    Claude->>Tool: Calls Edit (modify file)
    Tool-->>Hook: PostToolUse Event
    Hook-->>CLI: Logs operation

    Note over User,MCP: Scenario 2: User enters /mem-search

    User->>CLI: /mem-search terminal comparison
    CLI->>Hook: UserPromptSubmit Event
    Hook-->>CLI: Injects context
    CLI->>Skill: Matches mem-search SKILL.md
    Skill->>Claude: Injects Skill instructions
    Claude->>Tool: Calls MCP Tool: search("terminal comparison")
    Tool->>MCP: stdio request → mcp-server.cjs
    MCP-->>Tool: Returns search results
    Tool-->>Claude: Results presented to AI
    Claude-->>User: Structured answer

The Three Layers

┌──────────────────────────────────────────────┐
│ Layer 1: Distribution Layer (Plugin)           │
│   Bundles Skill + Hook + MCP + Command        │
│   One-command install, auto-registers all     │
├──────────────────────────────────────────────┤
│ Layer 2: Functional Layer (Skill + Hook + MCP) │
│   Skill = Workflow definition (Markdown)      │
│   Hook = Automated scripts (Shell/Node)       │
│   MCP = External tool services (Process)      │
├──────────────────────────────────────────────┤
│ Layer 3: Capability Layer (Tool)               │
│   Built-in atomic: Read/Write/Edit/Bash/...   │
│   MCP Tool: search/get_observations/analyze   │
└──────────────────────────────────────────────┘

File System Mapping

graph LR
    subgraph "~/.claude/"
        A[settings.json
Global config
hooks + MCP servers]
        B[skills/
Skill folders
each with SKILL.md]
        C[plugins/
Plugin cache
installed_plugins.json]
    end

    subgraph "Project/.claude/"
        D[settings.json
Project config
hooks + permissions]
        E[settings.local.json
Local config
MCP servers]
    end

    subgraph "Project Root"
        F[CLAUDE.md
Project rules
auto-loaded in all sessions]
    end

    A -->|Global| G[Claude Code]
    D -->|Project| G
    B -->|Skill registration| G
    C -->|Plugin registration| G
    F -->|Project context| G

    style A fill:#e74c3c,color:#fff
    style D fill:#f39c12,color:#fff
    style F fill:#2ecc71,color:#fff
Config Location Scope Typical Content
~/.claude/settings.json All projects Global hooks, MCP servers, permissions
Project/.claude/settings.json Current project Project-level hooks, permissions
Project/.claude/settings.local.json Current project (no git) Local MCP servers (with keys)
~/.claude/skills/ Global Manually installed Skills
~/.claude/plugins/ Global Auto-installed Plugins
Project/CLAUDE.md Current project Project constraints and instructions