Claude Code Architecture — How Persona, Agent, Command & Skill Work Together

Claude Code is not just a chatbot that writes code. It is a customizable AI development platform with a layered architecture that lets you define who the AI is, what actions are available, how those actions are organized, and who executes the work.

Most people use Claude Code as-is — type a prompt, get code back. But once you understand the four pillars of its customization architecture, you can build an entire AI-powered development system tailored to your workflow.

This post breaks down the four pillars — Persona, Command, Skill, and Agent — and shows how they work together to create something greater than the sum of their parts.

If you have not read my post on AI personas yet, start there — it covers the “why” behind personas. This post focuses on the full architecture.

The Four Pillars — Overview

Before diving into each pillar, here is the big picture:

╔═══════════════════════════════════════════════════════════════════╗
║                CLAUDE CODE — FOUR PILLARS                        ║
╠═══════════════════════════════════════════════════════════════════╣
║                                                                   ║
║   ┌──────────┐                                                    ║
║   │ PERSONA  │  WHO the AI is                                     ║
║   │          │  Identity, personality, communication style         ║
║   └──────────┘  Lives in: CLAUDE.md                               ║
║        │                                                          ║
║        │  (applies to ALL interactions)                            ║
║        ▼                                                          ║
║   ┌──────────┐    ┌──────────┐    ┌──────────┐                    ║
║   │ COMMAND  │───▶│  SKILL   │───▶│  AGENT   │                    ║
║   │          │    │          │    │          │                    ║
║   │ Trigger  │    │ Orchestr │    │ Executor │                    ║
║   │ /deploy  │    │ Spawns   │    │ Does the │                    ║
║   │ /test    │    │ Formats  │    │ work     │                    ║
║   └──────────┘    └──────────┘    └──────────┘                    ║
║                                                                   ║
╚═══════════════════════════════════════════════════════════════════╝

Each pillar has a distinct role:

Pillar	Role	Lives In	Analogy
Persona	Identity	CLAUDE.md	The employee’s personality and work ethic
Command	Trigger	.claude/commands/	The button the user clicks
Skill	Orchestrator	.claude/skills/	The project manager who assigns work
Agent	Executor	.claude/agents/	The specialist who does the work

Let’s explore each one.

Pillar 1: Persona (Identity)

The Persona is the foundation layer. It defines who the AI is across all interactions. Think of it as the base operating system that everything else runs on top of.

Where It Lives

The persona is defined in CLAUDE.md, which can exist at two levels:

• Global (~/.claude/CLAUDE.md) — applies to every project, every session
• Project (your-project/CLAUDE.md) — applies only to that project

Both files are loaded and merged. The global one establishes identity; the project one adds project-specific rules.

What It Defines

## WHO AM I?

- **Name:** Devi
- **Role:** Senior Developer & Coding Partner
- **Style:** Professional, direct, helpful

**When responding:**
- Be concise. Code first, explanation when asked.
- Read files before suggesting changes.
- Ask before taking destructive actions.

## Workflow Rules
1. NEVER give explanation without being asked
2. ALWAYS read relevant files before proposing edits
3. Verify solutions before finishing

Why It Matters for the Architecture

The persona is not an isolated feature — it is the base layer that influences everything above it. When an agent executes a task, it does so through the persona’s lens. When a command triggers a workflow, the persona’s communication style shapes the output.

A good persona ensures that no matter which command you run or which agent fires, the experience feels consistent.

Pillar 2: Command (Trigger)

Commands are the user-facing entry points. They are slash commands that users type to trigger actions, like shortcuts in a text editor.

Where They Live

.claude/commands/
├── deploy.md
├── test.md
├── review.md
└── project/
    ├── setup.md
    └── sync.md

What a Command Looks Like

A command file is a Markdown file with optional YAML frontmatter and a prompt body:

---
description: "Run the test suite and report results"
arguments:
  - name: scope
    description: "Test scope (all, unit, integration)"
    required: false
---

Run the $ARGUMENTS test suite for this project. Execute the tests,
capture the output, and report:
1. Total tests run
2. Pass/fail counts
3. Any failures with file paths and line numbers
4. Suggestions for fixing failures

The Design Philosophy

Commands are intentionally simple. They are the what — what the user wants done. They do not contain complex logic or workflows. That is the skill’s job.

Think of commands as a restaurant menu. The customer (user) picks what they want. They do not need to know how the kitchen (skill + agent) prepares it.

Built-in vs Custom Commands

Claude Code ships with built-in commands like /help and /clear. Custom commands extend this with project-specific or workflow-specific actions. The beauty is that custom commands feel identical to built-in ones from the user’s perspective.

Pillar 3: Skill (Orchestrator)

Skills are the middleware — they sit between the command and the agent, orchestrating the workflow. A skill reads the agent template, spawns the agent process, and formats the results.

Where They Live

.claude/skills/
├── deploy.md
├── test.md
├── review.md
└── project/
    ├── setup.md
    └── sync.md

What a Skill Does

A skill file is a prompt that describes:

1. Which agent template to use — the worker that will execute
2. Spawn instructions — how to configure and launch the agent
3. Output format — how to present results to the user

## Skill: Test Runner

### Agent Template
Read and use: `.claude/agents/test-runner.md`

### Spawn Instructions
1. Parse the user's test scope argument
2. Spawn a general-purpose agent with the test-runner template
3. Pass the project root, test framework, and scope as context
4. Wait for the agent to complete

### Output Format
Present results as a structured summary:
- Test counts in a table
- Failures as expandable sections
- Fix suggestions as action items

Why Skills Exist

You might wonder: why not have commands spawn agents directly? Because the skill layer provides orchestration that the command and agent should not care about:

• Formatting: The agent returns raw results; the skill formats them nicely
• Error handling: If the agent fails, the skill can retry or provide a fallback
• Composition: A skill can spawn multiple agents and combine their results
• Caching: Skills can check if work has already been done

The Separation Principle

Command = "I want X"     (user intent)
Skill   = "Here is how to get X"  (orchestration)
Agent   = "I am doing X"   (execution)

Each layer has a single responsibility. Commands express intent. Skills coordinate. Agents execute.

Pillar 4: Agent (Executor)

Agents are the workers — autonomous processes that execute a specific workflow independently. They run in their own context, have access to tools, and return results to the skill.

Where They Live

.claude/agents/
├── test-runner.md
├── deploy-agent.md
├── code-reviewer.md
└── docs-generator.md

What an Agent Template Looks Like

An agent template is a detailed prompt that defines:

## Agent: Test Runner

### Identity
You are a test execution specialist. Your job is to run tests
and report results accurately.

### Workflow
1. Identify the test framework from project files
2. Run the test command with the specified scope
3. Capture stdout and stderr
4. Parse the output for test results
5. If failures exist, read the failing test files
6. Analyze failures and suggest fixes

### Error Handling
- If test command not found, report "No test framework detected"
- If tests timeout, report which tests hung
- If syntax errors prevent running, report the first error

### Return Format
Return a structured result:
- total: number
- passed: number
- failed: number
- failures: [{ file, line, message, suggestion }]

Agent Characteristics

Agents have some important properties:

1. Autonomous: Once spawned, an agent runs independently. It does not ask the user questions mid-execution.
2. Tooled: Agents have access to the same tools as the main conversation — reading files, running commands, searching code.
3. Bounded: An agent has a specific scope and returns results when done. It does not run forever.
4. Stateless: Each agent invocation starts fresh. It receives context from the skill and returns results.

Why Agents Matter

Without agents, every complex task runs in the main conversation context. That means:

• The agent’s working state (file reads, command outputs) fills up the main context window
• Complex tasks with many steps can exhaust the context window
• Errors in one task can pollute the context for subsequent tasks

Agents solve this by running in an isolated context. They do their work, return results, and the main conversation only sees the summary. This is a huge win for context window management.

How They Flow Together

Now let’s see the full flow in action. Here is what happens when a user triggers a command:

┌─────────────────────────────────────────────────────────────────┐
│                        COMPLETE FLOW                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. USER types: /test all                                       │
│     │                                                           │
│     ▼                                                           │
│  2. COMMAND parses "all" as scope argument                      │
│     │                                                           │
│     ▼                                                           │
│  3. SKILL reads test-runner agent template                      │
│     │   Spawns agent with { scope: "all", projectRoot: "..." }  │
│     │                                                           │
│     ▼                                                           │
│  4. AGENT executes autonomously:                                │
│     │   • Detects test framework                                │
│     │   • Runs test command                                     │
│     │   • Parses output                                         │
│     │   • Analyzes failures                                     │
│     │   • Returns structured result                             │
│     │                                                           │
│     ▼                                                           │
│  5. SKILL formats the result:                                   │
│     │   • Pretty table with pass/fail counts                    │
│     │   • Expandable failure sections                           │
│     │   • Action items for fixes                                │
│     │                                                           │
│     ▼                                                           │
│  6. USER sees formatted results in the conversation             │
│                                                                 │
│  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │
│                                                                 │
│  NOTE: Persona is active throughout ALL steps above,            │
│  shaping communication style and behavior.                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Persona as the Base Layer

Notice that the persona is not a separate step in the flow. It is the base layer that influences everything:

• The command’s description is interpreted through the persona’s communication style
• The skill’s orchestration follows the persona’s workflow preferences
• The agent’s output is shaped by the persona’s formatting rules
• The final result is presented in the persona’s tone

This is why the persona comes first in the architecture. It is not just identity — it is the operating system everything else runs on.

When to Use What

Not every project needs all four pillars. Here is a guide:

Scenario	Persona	Command	Skill	Agent
Basic coding assistant	Yes	No	No	No
Repeated manual tasks	Yes	Yes	No	No
Complex multi-step workflows	Yes	Yes	Yes	Yes
Team-shared conventions	Yes	Yes	Yes	Optional
Heavy automation	Yes	Yes	Yes	Yes

Start Simple, Grow as Needed

Level 1: Persona only
  → Consistent AI behavior across sessions

Level 2: Persona + Commands
  → Quick shortcuts for common tasks

Level 3: Persona + Commands + Skills
  → Orchestrated workflows with formatted output

Level 4: Persona + Commands + Skills + Agents
  → Full automation with isolated execution contexts

You do not need to build the whole pyramid on day one. Start with a persona. Add commands when you find yourself typing the same prompts repeatedly. Add skills when commands get complex. Add agents when tasks need isolation.

Memory System — The Fifth Layer

There is a bonus layer worth mentioning: Auto-Memory. This is a persistent storage mechanism that carries context across sessions.

How It Works

Claude Code can maintain a memory directory that persists between conversations:

.claude/
├── CLAUDE.md           # Persona (identity)
├── commands/           # Commands (triggers)
├── skills/             # Skills (orchestrators)
├── agents/             # Agents (executors)
└── memory/             # Auto-Memory (persistence)
    ├── MEMORY.md       # Core project context
    ├── patterns.md     # Code patterns discovered
    └── troubleshooting.md  # Known issues and fixes

Why It Complements the Persona

The persona defines who the AI is. The memory system defines what the AI knows about your project. Together, they create both identity and knowledge:

Persona = "I am Devi, a coding partner who is direct and concise"
Memory  = "This project uses React 19, Zustand for state, and
           Vitest for testing. The auth module is in src/auth/.
           Known issue: test timeout on CI needs --timeout=10000"

The AI enters every session with both a consistent identity AND project-specific knowledge. That combination is powerful.

Memory vs Persona

Aspect	Persona (CLAUDE.md)	Memory (memory/)
What	Identity and rules	Project knowledge
Scope	Global or project	Project-specific
Who writes	You (manually)	AI (automatically) + You
When loaded	Every session	Every session
Token cost	Fixed (same every call)	Variable (grows over time)
Example	”Be concise"	"Project uses React 19”

Practical Example — Building a Command System

Let me walk through building a real command system from scratch. Imagine you frequently need to review your code before committing.

Step 1: The Persona (Already Done)

Your CLAUDE.md already defines the persona. No changes needed — the persona applies automatically.

Step 2: The Command

Create .claude/commands/review.md:

---
description: "Review staged changes before commit"
---

Review all currently staged changes in this repository.
Analyze for:
1. Potential bugs or logic errors
2. Security vulnerabilities (XSS, injection, etc.)
3. Code style consistency with the rest of the project
4. Missing error handling
5. Performance concerns

Provide a summary with severity ratings (critical/warning/info).

Step 3: The Skill (Optional for Simple Cases)

For a simple review command, the command itself is enough. But if you want structured output, create .claude/skills/review.md:

## Skill: Code Review

### Agent Template
Read and use: `.claude/agents/code-reviewer.md`

### Output Format
Present the review as:

## Review Summary
- Files reviewed: N
- Issues found: N (critical: N, warning: N, info: N)

## Critical Issues
[Expandable sections for each critical finding]

## Warnings
[Expandable sections for each warning]

## Suggestions
[Info-level observations]

Step 4: The Agent

Create .claude/agents/code-reviewer.md:

## Agent: Code Reviewer

### Identity
You are a meticulous code reviewer with expertise in security
and performance optimization.

### Workflow
1. Run `git diff --staged` to get all staged changes
2. For each changed file:
   a. Read the full file for context
   b. Analyze the diff for the categories above
   c. Rate each finding by severity
3. Return structured results

### Return Format
JSON with: { files, findings: [{ severity, file, line, message, suggestion }] }

The Result

Now when you type /review, the full pipeline fires:

/review  →  Command parses intent
         →  Skill spawns Code Reviewer agent
         →  Agent reads staged diff, analyzes each file
         →  Skill formats the structured output
         →  You see a clean review summary

And the whole time, your persona ensures the review is presented in your preferred style — concise, actionable, no fluff.

Building a Complete System

The real power comes when you combine all pillars into a complete system:

╔════════════════════════════════════════════════════════════╗
║              COMPLETE CLAUDE CODE SYSTEM                   ║
╠════════════════════════════════════════════════════════════╣
║                                                            ║
║  ┌─────────────────────────────────────────────────────┐   ║
║  │                   PERSONA LAYER                      │   ║
║  │   Identity + Communication + Workflow Rules          │   ║
║  └─────────────────────────────────────────────────────┘   ║
║                           │                                ║
║  ┌─────────────────────────────────────────────────────┐   ║
║  │                   MEMORY LAYER                       │   ║
║  │   Project knowledge + Patterns + Troubleshooting     │   ║
║  └─────────────────────────────────────────────────────┘   ║
║                           │                                ║
║  ┌──────────┐  ┌──────────┐  ┌──────────┐                 ║
║  │ /deploy  │  │  /test   │  │ /review  │  ... more       ║
║  └────┬─────┘  └────┬─────┘  └────┬─────┘                 ║
║       │              │              │                       ║
║  ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐                 ║
║  │ Deploy   │  │  Test    │  │ Review   │  ... skills      ║
║  │ Skill    │  │  Skill   │  │ Skill    │                  ║
║  └────┬─────┘  └────┬─────┘  └────┬─────┘                 ║
║       │              │              │                       ║
║  ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐                 ║
║  │ Deploy   │  │  Test    │  │ Code     │  ... agents      ║
║  │ Agent    │  │  Agent   │  │ Reviewer │                  ║
║  └──────────┘  └──────────┘  └──────────┘                 ║
║                                                            ║
╚════════════════════════════════════════════════════════════╝

Each layer builds on the one below it. The persona and memory provide the foundation. Commands provide the interface. Skills provide the orchestration. Agents provide the execution power.

Key Takeaways

1. Persona is the foundation — it shapes everything. Start here.
2. Commands are shortcuts — create them for any task you do repeatedly.
3. Skills are optional but valuable for complex workflows that need orchestration.
4. Agents are powerful for tasks that need isolated execution contexts and tool access.
5. Memory complements persona by adding project-specific knowledge that persists across sessions.
6. Start simple — persona first, then add layers as needed.
7. Each pillar has a single responsibility — do not mix concerns.

Build a system, not just a chatbot. Your future self will thank you.

---

This post is the second in my AI coding workflow series. The first post covers AI personas in depth — read it here.