Claude Code Foundation Architecture

Understand the difference between Commands, Agents, Skills and Rules

Why do some files exist in commands/ AND agents/?

The duplication is intentional and serves different purposes:

• commands/xxx.md = Interactive prompt invoked manually (/xxx)
• agents/xxx.md = Delegable version with YAML frontmatter (model, tools, skills)

Claude Code uses:

1. The command when the user explicitly types /xxx
2. The agent when Claude automatically delegates a sub-task

Key differences

Aspect	Command	Agent
Trigger	Manual (/xxx)	Automatic (delegation)
Frontmatter	No	Yes (model, tools, skills)
Context	Shared	Isolated
Variable	$ARGUMENTS	No
Model	Default	Configurable (haiku/sonnet)
Tools	All	Restricted (configurable)

Concrete example

# The user explicitly types the command
/qa:qa-security

# → Claude loads commands/qa/qa-security.md (prompt)
# → Claude delegates to agents/qa-security.md (isolated context, model: sonnet)
# → The agent uses the security-audit skill
# → Result returned to the main context

This architecture enables:

• Flexibility: The user controls via commands
• Optimization: Claude delegates with the right model
• Isolation: Agents do not pollute the context
• Security: Restricted tools for audits

---

Overview

┌─────────────────────────────────────────────────────────────────┐
│                            USER                                  │
│                             │                                    │
│    ┌───────────────────────┼───────────────────────┐            │
│    │                       ▼                       │            │
│    │  ┌─────────────────────────────────────────┐  │            │
│    │  │              TRIGGER                     │  │            │
│    │  │                                          │  │            │
│    │  │  Manual (/cmd)    Automatic (context)    │  │            │
│    │  │       │                  │               │  │            │
│    │  │       ▼                  ▼               │  │            │
│    │  │  ┌─────────┐      ┌───────────┐         │  │            │
│    │  │  │COMMANDS │      │  SKILLS   │         │  │            │
│    │  │  └────┬────┘      └─────┬─────┘         │  │            │
│    │  │       │                 │               │  │            │
│    │  │       └────────┬────────┘               │  │            │
│    │  │                │                        │  │            │
│    │  │                ▼                        │  │            │
│    │  │         ┌───────────┐                   │  │            │
│    │  │         │  AGENTS   │ (delegation)      │  │            │
│    │  │         └─────┬─────┘                   │  │            │
│    │  │               │                         │  │            │
│    │  │               ▼                         │  │            │
│    │  │         ┌───────────┐                   │  │            │
│    │  │         │  RULES    │ (constraints)     │  │            │
│    │  │         └───────────┘                   │  │            │
│    │  └─────────────────────────────────────────┘  │            │
│    │                                               │            │
│    └───────────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────────────┘

Detailed Comparison

Aspect	Commands	Skills	Agents	Rules
Folder	.claude/commands/	.claude/skills/	.claude/agents/	.claude/rules/
Trigger	Manual (/cmd)	Automatic	Auto delegation	Path-based
Context	Shared	Fork or shared	Isolated	Injected
Tools	All	Configurable	Restricted	N/A
Model	Default	Default	Configurable	N/A
Use case	Explicit actions	Detected patterns	Isolated tasks	Constraints

Commands (131 available)

Definition

Prompts invoked manually with the /command-name syntax.

Characteristics

• Explicit trigger by the user
• Context shared with the conversation
• Access to all tools
• Structure: markdown prompts

File structure

.claude/commands/
├── work/
│   ├── work-explore.md
│   ├── work-plan.md
│   └── work-commit.md
├── dev/
│   ├── dev-tdd.md
│   └── dev-api.md
└── ...

Format

# Command title

## Instructions
Instructions for Claude...

## Variables
$ARGUMENTS - Arguments passed by the user

Usage example

/work:work-explore "understand the authentication system"
/dev:dev-api "CRUD endpoint for users"
/qa:qa-security

When to use

• Explicit workflow
• Specific actions
• Complex tasks requiring a detailed prompt

Skills (54 available)

Definition

Patterns automatically triggered by Claude based on the conversation context.

Characteristics

• Automatic trigger (keywords, context)
• Forked context recommended
• Configurable tools (whitelist)
• Structure: YAML frontmatter + instructions

File structure

.claude/skills/
└── skill-name/
    └── SKILL.md

Format

---
name: skill-name
description: When to trigger this skill
allowed-tools:
  - Read
  - Write
  - Edit
context: fork
---

# Instructions

Instructions for the skill...

Skill example

---
name: test-driven-development
description: TDD development with Red-Green-Refactor cycle
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
context: fork
---

# TDD Skill

When the user mentions "TDD", "test first", or "write tests first"...

When to use

• Recurring patterns
• Desired contextual triggering
• Standardization of behaviors

Agents (63 available)

Definition

Specialized sub-agents with isolated context, automatic delegation.

Characteristics

• Completely isolated context (does not pollute the conversation)
• Restricted tools (security)
• Configurable model (haiku/sonnet/opus)
• Pre/post tool hooks
• Injectable skills

File structure

.claude/agents/
├── work-explore.md
├── qa-security.md
├── dev-debug.md
└── ...

Format

---
name: agent-name
description: Description of the agent
model: haiku | sonnet | opus
permissionMode: plan | default
disallowedTools:
  - Edit
  - Write
hooks:
  PreToolUse:
    - command: validate.sh
skills:
  - security-audit
---

# Instructions

Instructions for the agent...

Available models

Model	Usage	Cost	Speed	Context	Max output
haiku	Simple tasks, reading	$	Fast	200k	8k
sonnet	Complex tasks, analysis	$$	Medium	200k	64k
opus (4.7)	Critical tasks, adaptive thinking	$$$	Slower	1M	128k

Agent example

---
name: qa-security
description: OWASP Top 10 security audit
model: sonnet
permissionMode: plan
disallowedTools:
  - Edit
  - Write
  - NotebookEdit
skills:
  - security-audit
---

# QA Security Agent

Performs a complete security audit based on OWASP Top 10...

When to use

• Tasks requiring isolation
• Audits (read-only)
• Parallelization
• Token savings (haiku)

Rules (30 available)

Definition

Constraints and conventions automatically injected based on file paths.

Characteristics

• Automatic injection by path
• No user trigger
• Global or specific constraints
• Affects Commands, Skills, Agents

File structure (30 rules)

Cross-cutting rules (16):

.claude/rules/
├── workflow.md            # Global — Explore → (Brainstorm) → Specify → Plan → TDD → Audit → Commit
├── git.md                 # Global — Conventional Commits, branches
├── tdd-enforcement.md     # TS/Py/Go/Dart code — TDD mandatory
├── verification.md        # TS/Py/Go/Dart code — 4-phase verification
├── security.md            # auth/, api/, middleware/
├── accessibility.md       # tsx/jsx — WCAG 2.1 AA
├── performance.md         # tsx/ts/pages — Core Web Vitals
├── testing.md             # *.test, *.spec, tests/
├── api.md                 # api/, routes/, controllers/
├── design-style.md        # tsx/jsx, components/, app/
├── deploy-safety.md       # Dockerfile, docker-compose, .env
├── migration-safety.md    # package.json, tsconfig, next.config
├── service-worker.md      # sw.js, service-worker*
├── lsp.md                 # Multi-language — LSP vs Grep
├── research.md            # Multi-language — check native before building
└── base-maintenance.md   # .claude/** — sync catalog counters

Rules per language/framework (14):

├── typescript.md  # **/*.ts, **/*.tsx, **/*.mts
├── python.md      # **/*.py, **/pyproject.toml
├── go.md          # **/*.go, **/go.mod
├── rust.md        # **/*.rs, **/Cargo.toml
├── java.md        # **/*.java, **/pom.xml
├── csharp.md      # **/*.cs
├── ruby.md        # **/*.rb, **/Gemfile
├── php.md         # **/*.php
├── react.md       # **/*.tsx, **/components/**
├── nextjs.md      # **/next.config.*, **/app/**
├── vue.md         # **/*.vue, **/composables/**
├── svelte.md      # **/*.svelte, **/svelte.config.*
├── astro.md       # **/*.astro, **/content/**
└── flutter.md     # **/*.dart, **/lib/**

Format

---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript Rules

## Strict mode
- Always `strict: true`
- No `any` unless justified
...

When to use

• Code conventions
• Security rules
• Quality standards
• Per-technology constraints

Decision Matrix

By task type

Task	Best choice	Reason
Explicit workflow	Command	User control
Recurring pattern	Skill	Auto trigger
Read-only audit	Agent	Isolation, security
Code convention	Rule	Auto injection
Parallel task	Agent	Isolated context
Complex action	Command	Detailed prompt

By frequency of use

Frequency	Best choice
1x per project	Command
Several times/day	Skill
In parallel	Agent
Always (constraint)	Rule

By isolation need

Need	Choice
Share context	Command or Skill
Isolate completely	Agent
Constrain globally	Rule

Concrete Examples

Scenario 1: New feature

1. /work:work-explore        → Command (explicit)
2. TDD pattern detected → Skill (auto)
3. Security audit       → Agent (isolated)
4. /work:work-pr             → Command (explicit)

Applied rules: typescript.md, react.md, security.md

Scenario 2: Urgent bug fix

1. /dev:dev-debug           → Command (explicit)
2. Investigation        → Agent dev-debug (isolated)
3. Fix applied          → Rules typescript.md
4. /work:work-commit         → Command (explicit)

Scenario 3: Full audit

1. /qa:qa-audit            → Command (explicit)
   ├── qa-security      → Agent (parallel)
   ├── qa-perf          → Agent (parallel)
   ├── wcag-audit          → Agent (parallel)
   └── qa-coverage      → Agent (parallel)

All read-only, isolated contexts

Best Practices

Commands

• Explicit names (/work:work-explore not /we)
• Group by domain (work-, dev-, qa-)
• Document expected arguments

Skills

• context: fork recommended
• Limit allowed-tools
• Clear trigger keywords

Agents

• model: haiku for simple tasks
• disallowedTools for security
• Inject relevant skills

Rules

• Specific paths, not too broad
• Clear and actionable rules
• No conflicting rules

Data Flow

┌────────────────────────────────────────────────────────────────┐
│                                                                │
│  User: "/qa:qa-security"                                          │
│       │                                                        │
│       ▼                                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ COMMAND: /qa:qa-security                                    │   │
│  │ → Loads the qa-security.md prompt                        │   │
│  │ → Detects *.ts files → Injects rules/typescript.md      │   │
│  │ → Detects api/ folder → Injects rules/api.md            │   │
│  │ → Detects auth/ folder → Injects rules/security.md      │   │
│  └─────────────────────────────────────────────────────────┘   │
│       │                                                        │
│       ▼                                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ DELEGATION → AGENT: qa-security                          │   │
│  │ → model: sonnet                                          │   │
│  │ → permissionMode: plan (read-only)                       │   │
│  │ → disallowedTools: [Edit, Write]                         │   │
│  │ → skills: [security-audit]                               │   │
│  │ → ISOLATED context                                       │   │
│  └─────────────────────────────────────────────────────────┘   │
│       │                                                        │
│       ▼                                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ SKILL: security-audit (injected into agent)              │   │
│  │ → OWASP Top 10 checklist                                 │   │
│  │ → Vulnerability patterns                                 │   │
│  └─────────────────────────────────────────────────────────┘   │
│       │                                                        │
│       ▼                                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ RESULT → Returns to the main context                     │   │
│  │ → Agent report                                           │   │
│  │ → Main context preserved                                 │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Summary

Concept	Trigger	Context	Main usage
Command	/name	Shared	Explicit actions
Skill	Keywords	Fork	Auto patterns
Agent	Delegation	Isolated	Parallel tasks
Rule	File path	Injected	Constraints