Claude Code Prompt Architecture

Analysis of Claude Code's five prompt augmentation mechanisms through network traffic instrumentation.

Architecture Overview

Claude Code operates on three layers:

API Request Structure:
├── system[]           ← Output Styles
├── messages[]         ← CLAUDE.md, Slash Commands & Skills
└── tools[]            ← Sub-Agents

The Five Mechanisms

1. CLAUDE.md: Project-Level Context Injection

CLAUDE.md is automatically injected into every user message as a <system-reminder> if the file exists in your project root. This is completely transparent and persists for all requests.

Network trace:

{
  "messages": [{
    "role": "user",
    "content": [{
      "type": "text",
      "text": "<system-reminder>\n# claudeMd\nContents of /path/to/CLAUDE.md (project instructions):\n\n[your CLAUDE.md content]\n</system-reminder>"
    }]
  }]
}

Use for: Project standards, architecture decisions, domain knowledge (committed to git)

---

2. Output Styles: System Prompt Mutation

When you run /output-style software-architect, Claude Code appends a text block to the system array in the API request. This persists for the entire session.

Network trace:

{
  "system": [
    {"type": "text", "text": "You are Claude Code..."},
    {"type": "text", "text": "# Output Style: software-architect\n[instructions...]"}
  ],
  "messages": [...]
}

Use for: Session-wide behavior changes (response format, technical depth, verbosity)

---

3. Slash Commands: Deterministic Prompt Injection

Slash commands read .claude/commands/*.md, replace {arg1} placeholders, and inject into the current user message.

Network trace:

{
  "messages": [{
    "role": "user",
    "content": [{
      "type": "text",
      "text": "<command-message>review is running…</command-message>\n[file contents]\nARGUMENTS: @file.js"
    }]
  }]
}

Use for: Repeatable workflows with explicit triggers

---

4. Skills: Model-Invoked Capability Extension

Claude autonomously decides when to invoke a skill by matching requests against SKILL.md frontmatter descriptions.

Network trace:

// Assistant decides to use skill
{
  "role": "assistant",
  "content": [{
    "type": "tool_use",
    "name": "Skill",
    "input": {"command": "slack-gif-creator"}
  }]
}

// Skill content returned
{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "content": "[SKILL.md injected]"
  }]
}

Security note: Skills execute code directly. Use MCP for production.

Use for: Domain-specific expertise that should activate automatically

---

5. Sub-Agents: Conversation Delegation

Sub-agents spawn entirely separate conversations with their own system prompts.

Network trace:

// Main conversation delegates
{"role": "assistant", "content": [{
  "type": "tool_use",
  "name": "Task",
  "input": {
    "subagent_type": "Explore",
    "prompt": "Analyze auth flows..."
  }
}]}

// Sub-agent runs in isolated conversation
{
  "system": "[Explore agent system prompt]",
  "messages": [{"role": "user", "content": "Analyze auth flows..."}]
}

// Results returned
{"role": "user", "content": [{
  "type": "tool_result",
  "content": "[findings]"
}]}

Use for: Multi-step autonomous tasks (codebase analysis, security audits)

---

Comparison Matrix

Mechanism	Injection Point	Activation	Scope
CLAUDE.md	User messages (<system-reminder>)	Automatic	Project-wide
Output Styles	System prompt	Manual	Session-wide
Slash Commands	User messages (<command-message>)	User-explicit	Single turn
Skills	User messages (via tool_result)	Model-decided	Single turn
Sub-Agents	Separate conversation	Model-decided	Isolated

Quick Decision Guide

CLAUDE.md vs Output Styles:

• Team-wide standards → CLAUDE.md (committed to repo)
• Personal preferences → Output styles (session-only)

Skills vs Slash Commands vs MCP:

• Need automation → Skills or MCP
• Need control → Slash commands
• Need security → MCP only

MCP Resources: Check out AgiFlow's AI Code Toolkit for production-ready MCP servers and tooling.

---

Data Source

Analysis derived from network logs in data/:

• claude-md.log - CLAUDE.md automatic injection mechanism
• output-style.log - System prompt override mechanism
• skills.log - Skill tool invocation patterns
• slash-command.log - File content injection
• sub-agents.log - Task tool delegation

Full technical writeup: blog.md - Deep dive into all five mechanisms with network traces, security analysis, and practical recommendations.