Claude Code isn't just a chatbot that writes code. It's 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 haven't 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's 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's 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're 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're the what — what the user wants done. They don't contain complex logic or workflows. That's the skill's job.
Think of commands as a restaurant menu. The customer (user) picks what they want. They don't 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:
- Which agent template to use — the worker that will execute
- Spawn instructions — how to configure and launch the agent
- 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 shouldn't 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's how to get X" (orchestration)
Agent = "I'm 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:
- Autonomous: Once spawned, an agent runs independently. It doesn't ask the user questions mid-execution.
- Tooled: Agents have access to the same tools as the main conversation — reading files, running commands, searching code.
- Bounded: An agent has a specific scope and returns results when done. It doesn't run forever.
- 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's 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 isn't a separate step in the flow. It's 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's not just identity — it's the operating system everything else runs on.
When to Use What
Not every project needs all four pillars. Here's 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 don't 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's 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
- Persona is the foundation — it shapes everything. Start here.
- Commands are shortcuts — create them for any task you do repeatedly.
- Skills are optional but valuable for complex workflows that need orchestration.
- Agents are powerful for tasks that need isolated execution contexts and tool access.
- Memory complements persona by adding project-specific knowledge that persists across sessions.
- Start simple — persona first, then add layers as needed.
- Each pillar has a single responsibility — don't 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 →
Follow my coding journey:
- Instagram: @abduarrahman
- YouTube: @abduarrahmanscode
- TikTok: @anduarrahmans
Support my work:
- Ko-fi: ko-fi.com/abduarrahman
Originally published at abduarrahman.com