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.
Guides you in choosing the right Claude Code component type (agents, skills, commands, hooks) and designing multi-component plugin architectures. Use when deciding between component types, debugging delegation failures, or designing cohesive plugin ecosystems.
/plugin marketplace add racurry/neat-little-package/plugin install box-factory@neat-little-packageThis 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:
Components operate independently, and have limited access to the user or each other.
These are our RULES (based on spec & best practices):
Sub-agents return complete results. No mid-execution interaction - agent must have everything upfront.
Load knowledge only when relevant (this preserves context and saves tokens). Use Skills tosolve selective context loading.
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: