Box Factory Architecture

This 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).

Fundamentals

Four foundational principles underpin all Claude Code component design:

Isolation Model

Components operate independently, and have limited access to the user or each other.

These are our RULES (based on spec & best practices):

• Only Main Claude has user access
• Sub-agents:
  • CANNOT: ask the user questions, see conversation history, reference Skill files by name
  • CAN: use tools, load skills, reference Skill content by subject
• Skills:
  • CANNOT: reference any other component (single exception: Box Factory skills can reference Box Factory Architecture as a prerequisite)
  • CAN: Provide information and instruction
• Commands:
  • CANNOT: execute logic, access user directly
  • CAN: trigger Sub-agents, reference Skills

Return-Based Delegation

Sub-agents return complete results. No mid-execution interaction - agent must have everything upfront.

Progressive Disclosure

Load knowledge only when relevant (this preserves context and saves tokens). Use Skills tosolve 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.

Instructions

1. Select a workflow based on your needs from Workflow Selection

Claude Code changes rapidly and is post-training knowledge. Fetch the official documentation when designing components to ensure current specifications.

Workflow Selection

Design Patterns in Claude Code Components

Most common patterns used in multi-component workflows:

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.

Component Communication and Delegation

Quick reference for what each component can do:

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.

Which Component Should I Choose

Users can customize Claude Code using components broken into roughly three categories.

Components used by Claude

Components for the UX of the User

Distribution Wrappers for Components

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.

Building Blocks

Reusable documentation patterns that apply across all component types:

Use these patterns when writing documentation for any component type (skills, agents, commands, READMEs).

Claude Code Official Documentation

Claude Code changes rapidly and is post-training knowledge. Fetch these docs when designing components to ensure current specifications:

• https://code.claude.com/docs/en/sub-agents - Agent architecture and isolation model
• https://code.claude.com/docs/en/slash-commands - Command structure and triggering
• https://code.claude.com/docs/en/hooks - Hook lifecycle and execution
• https://code.claude.com/docs/en/plugins - Plugin packaging and distribution
• https://code.claude.com/docs/en/mcp - MCP server configuration and transports
• https://code.claude.com/docs/en/memory - CLAUDE.md, rules, and project memory
• https://code.claude.com/docs/en/skills - Skill definition and loading

Example Component Ecosystems

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.

Anti-Patterns

Common architecture mistakes. See linked design skills for detailed guidance.

Quality Checklist

Before finalizing component architecture:

Fundamentals:

• Agents have no user interaction language ("ask", "confirm", "clarify")
• Agents return complete results (not partial or interactive)
• Progressive disclosure applied (skills for substantial guidance, memory for brief)

Component Selection:

• Component type matches task complexity (see Which Component Should I Choose)
• "Avoid When" conditions checked for each component

Tool Permissions:

• Agent tools match responsibilities (Read-only for reviewers, Write for creators)
• Skill tool included if agent loads skills
• Task tool included if agent delegates to sub-agents