Guidance for using Claude Code component architecture and choosing between agents, skills, commands, and hooks. Helps decide which component type fits a use case, understand delegation and isolation, debug cross-component issues, and design cohesive plugin architectures. Use when choosing component types, designing plugins with multiple components, debugging delegation failures, asking about component interaction patterns, or creating Box Factory-compliant components.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
building-blocks/README.mdbuilding-blocks/anti-pattern-catalog.mdbuilding-blocks/decision-frameworks.mdbuilding-blocks/deep-dive-links.mdbuilding-blocks/document-structure.mdbuilding-blocks/navigation-tables.mdbuilding-blocks/quality-checklist.mdbuilding-blocks/reference-sections.mdcomponents/choosing-the-right-component.mdcomponents/communication-and-delegation.mdcomponents/component-paths.mdcomponents/interaction-patterns.mdexamples/example-component-ecosystems.mdprinciples/core-architecture.mdprinciples/knowledge-delta-filter.mdThis meta-skill teaches the Claude Code component and ecosystem architecture - how components interact, when to use each type, and how to design cohesive multi-component solutions. This applies to both Main Claude (choosing what to create) and sub-agents (understanding their role).
Four foundational principles underpin all Claude Code component design:
| Principle | Implication |
|---|---|
| Isolation Model | Only Main Claude has user access. Sub-agents cannot ask questions or see conversation history. |
| Return-Based Delegation | Sub-agents return complete results. No mid-execution interaction - agent must have everything upfront. |
| Progressive Disclosure | Load knowledge when relevant to save tokens. Skills solve selective context loading. |
| Knowledge Delta Filter | Document only what Claude doesn't know. Skip base knowledge; include user-specific delta. |
Design test: If your sub-agent needs to ask questions mid-execution, redesign the delegation pattern.
Deep dive: Core Architectural Concepts - Diagrams, design implications, common misconceptions. Traverse when: debugging delegation issues, need to understand WHY architecture works this way. Skip when: table above answers your question.
Deep dive: Knowledge Delta Filter - Decision framework for content inclusion, examples across component types. Traverse when: writing any component content, reviewing for bloat, unsure what to include/exclude. Skip when: already know the delta principle, content is clearly user-specific.
Claude Code changes rapidly and is post-training knowledge. Fetch the official documentation when designing components to ensure current specifications.
| If you need to... | Go to... |
|---|---|
| Choose a component type (skill vs agent vs command vs hook) | Which Component Should I Choose |
| Debug delegation issues (agent not receiving data, calls failing) | Component Communication |
| Design multi-component workflows (command→agent→skill chains) | Design Patterns |
| Understand isolation model (why agents can't ask questions) | Fundamentals |
| See reference implementations (complete plugin ecosystems) | Example Ecosystems |
| Determine file paths for new components (project vs user vs plugin) | Component Paths |
| Write documentation for components (skills, agents, READMEs) | Building Blocks |
| Get oriented / unsure where to start | Fundamentals then Component Selection |
Most common patterns used in multi-component workflows:
| Pattern | Workflow |
|---|---|
| Simple series of steps or tool call | User -> Command |
| Complex agent flow triggered by command | User -> Command -> Agent |
| Complex agent flow backed by knowledge base | User -> Command -> Agent -> Skill |
Deep dive: Interaction Patterns - 5 detailed patterns (Command→Agent, Agent→Skill, nested delegation, Hook+Agent, shared skills), scope anti-patterns. Traverse when: designing multi-component workflow, debugging component interactions, need pattern examples. Skip when: simple single-component task, workflow table covers your use case.
Quick reference for what each component can do:
| Component | Can | Cannot |
|---|---|---|
| Main Claude | Ask user questions, delegate to agents | N/A (full access) |
| Sub-agent (aka subagent) | Use tools, load skills, return results | Ask questions, see conversation history |
| Command | Trigger agents, expand to prompts | Execute logic directly, access user |
| Skill | Provide guidance when loaded | Execute code, call tools, trigger actions |
| Hook | Run scripts, block/modify tool calls | Ask questions, use judgment |
| MCP Server | Provide custom tools | Access conversation, trigger unprompted |
Deep dive: Component Communication & Delegation - CAN/CANNOT lists for each component type with examples and edge cases. Traverse when: need detailed interaction rules, debugging "why can't my agent do X". Skip when: table above answers the question.
Users can customize Claude Code using components broken into roughly three categories.
| Component Type | When to Use | Avoid When (use instead) |
|---|---|---|
Sub-agent | Complex logic, autonomous delegation | Guidance only (Skill), simple repeatable (Command) |
Skill | Substantial interpretive guidance across contexts | Doing work (Agent), brief context <20 lines (Memory) |
Command | Simple repeatable actions, explicit user control | Complex logic (Agent), knowledge only (Skill) |
Memory | Project knowledge, behavior shaping | Substantial guidance (Skill), enforcement (Hook) |
MCP server | Custom tool integrations, specialized transports | Standard tools suffice (use built-in tools) |
| Component Type | When to Use | Avoid When (use instead) |
|---|---|---|
Hook | Guaranteed enforcement, simple rules | Judgment calls (Agent), guidance (Skill) |
Status Line | Custom session metadata display | Enforcement needed (Hook), any Claude action |
Output Style | Custom response formats, structured outputs | Logic changes (Agent/Skill), enforcement (Hook) |
| Component Type | When to Use | Avoid When (use instead) |
|---|---|---|
Plugin | Bundling multiple components for reuse | Single-project use (project components) |
Marketplace | Discovering and sharing plugins | Private/internal plugins (direct install) |
Deep dive: Choosing the Right Component - Full decision framework with KEY CHARACTERISTIC, CHOOSE IF, DO NOT CHOOSE IF, and Example User Requests for each component. Traverse when: ambiguous component choice, need to map user intent phrases to component type, edge cases not covered by summary. Skip when: summary tables clearly answer the question.
Reusable documentation patterns that apply across all component types:
| Pattern | Purpose |
|---|---|
| Navigation Tables | Routing tables for progressive discovery |
| Decision Frameworks | Structured formats for documenting choices between options |
| Reference Sections | At-a-glance content design for the happy path |
| Deep Dive Links | Cross-reference format with traverse/skip guidance |
| Quality Checklist | Checkbox validation at end of documents |
| Anti-Pattern Catalog | Structure for documenting common mistakes |
Use these patterns when writing documentation for any component type (skills, agents, commands, READMEs).
Claude Code changes rapidly and is post-training knowledge. Fetch these docs when designing components to ensure current specifications:
A very simple ecosystem:
CLAUDE.md # Basic project memory. Indicates to use code-reviewer agent when reviewing code.
commands/review-code.md # Command that triggers code review by delegating to code-reviewer agent.
agents/code-reviewer.md # Code review agent, looks up guidelines from skill.
skills/code-review-guidelines.md # Skill with guidance on code review best practices.
Deep dive: Example Component Ecosystems - 3 complete ecosystems (Testing, Documentation, Code Quality) with architecture diagrams and interaction flows. Traverse when: need reference implementation, learning multi-component patterns, planning similar ecosystem. Skip when: understanding single component, simple use case.
Common architecture mistakes. See linked design skills for detailed guidance.
| Pitfall | Symptom | Fix | Details |
|---|---|---|---|
| User interaction in agents | Agent prompt contains "ask the user", "confirm with" | Remove - agents are isolated, return complete results | sub-agent-design |
| Wrong granularity | Agent for simple task, skill for 10-line guidance | Match complexity: Command < Agent < Skill based on scope | Component Selection |
| Missing tool permissions | Agent fails silently or can't complete task | Add required tools (esp. Skill tool if loading skills) | sub-agent-design |
| Vague agent descriptions | Main Claude doesn't delegate when it should | Use strong triggers: "MUST BE USED when...", "ALWAYS use for..." | sub-agent-design |
| Over-engineering | Plugin for single-project use | Use project-level components until reuse is proven | plugin-design |
Before finalizing component architecture:
Fundamentals:
Component Selection:
Tool Permissions: