Claude Code Explained

Claude Code Architecture Overview

Claude Code is more than just a coding assistant—it's a framework for orchestrating AI agents. Think of it as having multiple layers of customization that work together to extend what Claude can do.

Core Components

Skills

What they are: Modular capabilities that activate automatically based on context

• Live in ~/.claude/skills/ (global) or .claude/skills/ (project-specific)

• Each skill is a directory containing a SKILL.md file with YAML frontmatter + instructions

• Claude automatically discovers and loads skills when their description matches the current task

• Use progressive disclosure—Claude loads information in stages rather than all at once

Key difference: Skills activate automatically when relevant, not manually invoked

Example structure:

~/.claude/skills/explain-code/
├── SKILL.md           # Main instructions
├── workflows/         # Optional commands nested in the skill
└── context/          # Supporting reference materials

Use when: You want Claude to automatically apply specific knowledge or workflows (like "always use these formatting rules for blog posts")

Commands (Slash Commands)

What they are: User-initiated shortcuts you explicitly trigger

• Live in ~/.claude/commands/ or ~/.claude/skills/{domain}/workflows/

• Single markdown files that become /command-name in the terminal

• Can include $ARGUMENTS placeholder to pass parameters

• Can orchestrate other features (invoke subagents, use specific skills)

Key difference: Commands are manually triggered from the terminal, not auto-discovered

Use when: You want repeatable, deterministic workflows with terminal autocomplete (like /pr-review or /scaffold)

Note: Commands have been merged into the skills system—you can now put them in skill workflows directories where they belong with related context.

Agents (Subagents)

What they are: Specialized AI instances that execute work in parallel or isolation

• Live in ~/.claude/agents/

• Standalone markdown files defining specialized expertise

• Run with their own context to prevent "context pollution"

• Can be invoked by skills, commands, or the main Claude instance

• Built-in agents include: Explore, Plan, general-purpose

Key difference: Agents are standalone workers that can execute skills and commands in isolation

Architecture insight: Agents aren't nested in skills—they're standalone entities that can EXECUTE skills and commands as parallel workers

Use when:

• You need parallel execution of multiple tasks

• You want to isolate heavy computational work

• You need specialized deep-dive analysis without polluting your main context

Hooks

What they are: Event-driven automation that runs at specific lifecycle points

• Configured in ~/.claude/settings.json

• Execute bash scripts or commands at precise moments

• Available hook types:

  • Setup - Runs with --init or --maintenance flags

  • SessionStart - Runs when Claude Code starts

  • PreToolUse - Before Claude uses a tool (can block/allow)

  • PermissionRequest - When permission dialog appears

  • PostToolUse - After a tool completes

  • PrePrompt - When user submits a prompt

  • ResponseComplete - When Claude finishes responding

  • SubagentComplete - When a subagent finishes

  • Notification - When Claude Code sends notifications

Key difference: Hooks are deterministic enforcement, while CLAUDE.md rules are suggestions

Critical insight: CLAUDE.md saying "don't edit .env" is parsed by LLM and maybe followed. PreToolUse hook blocking .env edits always runs and blocks the operation

Use when: You need guaranteed automation (auto-format code, block dangerous commands, enforce quality gates)

MCP (Model Context Protocol)

What it is: A protocol that connects Claude to external tools and data sources

• Configured in .mcp.json (project root) or settings

• Makes external capabilities available as native commands

• Examples: JIRA, GitHub, Slack, databases, Puppeteer

• Claude Code functions as both MCP server and client

Key difference: MCP provides connectivity to external systems, not just internal workflows

Use when: You need to integrate external tools (pull GitHub issues, query databases, access company APIs)

Important: Don't enable all MCPs at once. Your 200k context window can shrink to 70k with too many tools enabled

Plugins

What they are: Bundled packages that combine all the above components

• Collections of skills, agents, commands, hooks, and MCP servers

• Installed with single command: /plugin install

• Distributed via "marketplaces" (curated GitHub repositories)

• Can be official (from Anthropic) or community-created

Key difference: Plugins are the distribution mechanism for complete workflows

Use when: You want to share complete setups with teams or install pre-built workflows

How They Work Together

Here's a real-world example workflow:

1. CLAUDE.md contains project standards ("write tests first")

2. MCP server connects to GitHub for issue tracking

3. /research command (slash command) launches multiple subagents in parallel

4. Skills automatically activate for documentation after implementation

5. Hooks enforce quality standards (run linters, block dangerous operations)

6. Plugin bundles all of the above for team distribution

The Architecture Hierarchy

Skills operate through prompt expansion and context modification, injecting specialized instructions into the conversation history and dynamically modifying Claude's execution environment

Think of it this way:

• MCP = External connectivity

• Skills = Automatic knowledge/process

• Commands = Manual triggers

• Agents = Parallel workers

• Hooks = Lifecycle automation

• Plugins = Distribution packaging

All of these use Claude's VM environment with filesystem access, enabling progressive disclosure and sophisticated orchestration beyond what's possible with prompts alone.

---

To Install Claude Code in Windows, Open "PowerShell" (the more modern version of the Cmd terminal), and use Winget:

winget install Anthropic.ClaudeCode