Agent Architecture
The full orchestration stack — from subagent delegation and parallel agent teams to isolated worktrees, reusable skills, and extensible plugins.
AGENT.md files define named, reusable specialist subagents that Claude Code can invoke automatically or on demand. This article covers every frontmatter field, placement rules, and the design principles behind effective subagent definitions.
Claude Code provides four distinct ways to invoke subagents — from automatic selection to explicit CLI flags. Knowing which pattern to use determines whether your agents fire reliably or silently miss.
Agent teams are independent Claude Code sessions that communicate peer-to-peer through a shared task list. Unlike subagents that report back to a caller, teammates coordinate directly — making them the right tool for work that requires handoffs, sequential dependencies, or parallel specialization.
AutoDream is a discovery tool that generates structured planning artifacts — architecture docs, task breakdowns, risk assessments — from a natural language description of what you want to build. It is the pre-session stage before you open a Claude Code session or spawn an agent team.
You do not pre-configure agent teams — you describe what you need and the Lead orchestrates. This article walks through the runtime patterns for spawning, assigning work, monitoring progress, and merging teammate output.
Hooks on agent team events — TeammateIdle, TaskCompleted, TaskCreated — let you enforce quality standards automatically. When a hook exits with code 2, it sends feedback to the teammate, which must address the issue before the event can proceed.
/batch takes a single instruction and fans it out into a swarm of independent parallel agents — each in its own worktree, each opening its own PR. It is purpose-built for large-scale parallelizable changes that do not require inter-agent coordination.
Git worktrees let you have multiple branches checked out simultaneously in separate directories — no stashing, no switching. Claude Code wraps this capability to give each session and subagent its own isolated workspace.
The --worktree flag starts Claude Code in an isolated git worktree. The session gets its own branch and working directory — the main tree is completely untouched until you choose to merge.
Worktrees make failed experiments zero-cost. Try a major refactor, compare two approaches simultaneously, or review a PR — without ever touching your main working directory.
The real power of Claude Code is not a faster single session — it is running multiple focused sessions simultaneously. This article covers how to split work for parallelism, manage multiple worktree sessions, and think like a manager coordinating workstreams instead of a typist doing the work.
In large monorepos, full worktree checkouts include files the agent will never touch. Sparse worktrees limit the checkout to only the paths you specify — faster startup, less disk usage, and sharper Glob/Grep results.
Setting isolation: worktree in AGENT.md gives each subagent spawn its own git branch and working directory. This is what enables parallel subagents to edit the same codebase without conflicts, and what makes /batch work at 30 agents simultaneously.
Skills, agents, and hooks are three distinct abstractions for automating Claude Code behavior. They are not competing alternatives — they compose. Understanding when each is the right tool changes how you design your Claude Code workflow.
SKILL.md files define slash commands backed by a reusable prompt. This article covers every frontmatter field, the full set of auto-invocation controls, the /skills browser, and the design principles behind skills that actually get used.
Skills become dramatically more reusable when they can accept arguments. Claude Code supports five substitution variables — $ARGUMENTS, $0/$1/$2, $ARGUMENTS[N], and two environment variables — that let a single skill serve a family of related tasks.
The paths field in SKILL.md restricts a skill to activating only when the working directory matches specific glob patterns. This makes skills context-aware — a component-patterns skill fires in src/components/, not globally — without any manual invocation.
Committing .claude/skills/ to your repository turns your skills into shared team infrastructure. Every developer who clones the repo gets the same workflow library automatically — no setup, no documentation drift, no diverging practices.
The difference between a skill that saves 30 seconds and one that changes your workflow is depth. Effective skills encode multi-step, multi-tool workflows that cross boundaries — tests + implementation + PR creation in a single command. This article shows what those skills look like and how to build them.
A Claude Code plugin bundles one or more capability types into a distributable unit. Understanding all eight types — from skills to LSP servers to background monitors — determines what problems plugins can solve and when building one is the right choice.
Plugin management follows a clear CLI interface: install from a registry, GitHub, or local path; enable or disable per project; reload without restarting. Understanding the lifecycle avoids the common pitfall of installing a plugin and wondering why nothing changed.
Language Server Protocol (LSP) support landed in Claude Code v2.0.74 (December 2025). Plugins that bundle LSP servers give Claude real code intelligence — type information, live diagnostics, go-to-definition — dramatically improving code generation accuracy compared to text-based search alone.
Background monitors continuously watch external sources — log files, process output, CI pipelines — and deliver notifications to Claude Code when conditions change. Unlike hooks (which react to Claude's own tool events), monitors watch the world outside Claude.
Plugins can render interactive HTML directly in the Claude Code Desktop app's preview pane. This enables richer output formats — interactive diagrams, data tables, test reports, dashboards — that communicate more than prose alone when working with complex or visual information.
Enterprise Claude Code deployments require control over which plugins developers can install. The allowedChannelPlugins setting governs Channels-based plugins; broader enterprise plugin management includes internal marketplaces, MDM distribution, and plugin security review processes.