Agent Smith

Recursive Self-Similar Multi-Agent System —— Conflict-free Parallel Task Decomposition and Execution through Directory Isolation Protocol

English | 简体中文

---

Introduction

Agent Smith is a general-purpose multi-agent collaboration framework that enables multiple AI agents to work in parallel without conflicts through a strict directory isolation protocol.

Core Design Principles:

• Self-Similarity: Each agent (Smith) follows the same protocol and can recursively spawn child agents
• Conflict-Free Parallelism: Directory isolation ensures multiple agents can work simultaneously without interference
• Task Decomposition: Automatically breaks down complex tasks into parallelizable subtasks
• Platform Agnostic: Can run on any system or platform that supports multi-agent execution

---

Quick Start

Installation

Option 1: Claude Code Skill (Recommended)

Copy the agent-smith directory to Claude Code's skills directory:

# macOS / Linux
cp -r agent-smith ~/.claude/skills/

# Windows (PowerShell)
Copy-Item -Recurse agent-smith $env:USERPROFILE\.claude\skills\

Option 2: Standalone Usage

Copy the .agent-smith/ directory structure to your project:

cp -r .agent-smith-template ./my-project/.agent-smith

Usage

1. Initialize the Matrix

   Create the .agent-smith/ structure in your working directory:

   mkdir -p .agent-smith/smiths/smith-root/{inbox,private,outbox,children}
   mkdir -p .agent-smith/results
   

2. Define the Task

   Create a task file in the root agent's inbox/ directory:

   # task-001.md
   ## Task: AI Agent Market Research
   
   ### Objective
   Comprehensive understanding of AI Agent market landscape
   
   ### Subtasks
   1. Market trend analysis
   2. Key vendor research
   3. Technology development tracking
   4. Application scenario research
   

3. Start Execution

   The root agent reads the task and decides to execute directly or decompose and create child agents

---

Core Concepts

Smith (Agent)

A self-similar agent unit. Each Smith has:

• Unique ID (e.g., smith-root, smith-001)
• Level indicator (Level 0 is root, increments downward)
• Parent Smith reference (root has no parent)

Directory Isolation Protocol

.agent-smith/
├── smiths/
│   ├── smith-root/        # Root agent
│   │   ├── smith.md       # Agent definition (prompt)
│   │   ├── inbox/         # Task queue (parent writes, self reads)
│   │   ├── private/       # Private workspace
│   │   ├── outbox/        # Result output
│   │   └── children/      # Child agent directory
│   └── smith-001/         # Child agent
│       ├── smith.md
│       ├── inbox/         # Parent writes, self reads
│       ├── private/
│       ├── outbox/
│       └── children/
└── results/
    └── final.md           # Final result

Access Control Rules:

Directory	Permission	Description
inbox/	Parent write, self read	Task distribution queue
private/	Self-write only	Drafts, thoughts, temporary files
outbox/	Self-write only	Final result output
children/	Self-write only	Create child agents (parent privilege)

Execution Flow

Read task from inbox/
    ↓
Analyze task complexity
    ↓
┌─────────────┴─────────────┐
↓                           ↓
Can complete directly   Needs decomposition
    ↓                           ↓
Execute task          Design subtasks
    ↓                           ↓
Write to outbox/      Create child agents
                            ↓
                      Write tasks to child inbox/
                            ↓
                      Wait for child results
                            ↓
                      Aggregate results
                            ↓
                      Write to outbox/
                            ↓
                      End

---

Platform Integration

Claude Code

This repository includes a complete Claude Code Skill configuration:

• Skill Entry: agent-smith/SKILL.md
• Trigger Phrases: "create multi-agent system", "set up agent matrix", "decompose task for parallel execution"
• Auto-initialization: Automatically creates .agent-smith/ directory structure when triggered

Other Platforms

Agent Smith is an open protocol that can be implemented on:

• AutoGen - Using UserProxyAgent + AssistantAgent combination
• LangGraph - As a state machine workflow
• CrewAI - As Crew + Agents structure
• Custom Systems - Any environment supporting directory I/O and multi-processing

---

Example Scenarios

Market Research

Decompose complex AI Agent market research into 4 parallel subtasks:

1. Market trend analysis
2. Key vendor research
3. Technology development tracking
4. Application scenario research

→ View Full Example

Code Review

Break down large-scale code review into module-level parallel processing:

1. Data layer review
2. Business logic layer review
3. API interface layer review
4. Frontend component review

Content Creation

Distributed collaboration for content projects:

1. Outline design
2. Section writing (multiple authors in parallel)
3. Editing and proofreading
4. Format standardization

---

Best Practices

Task Decomposition Principles

1. Granularity Control: Each subtask should be completable in 1-4 hours
2. Independence First: Subtasks should have low coupling and minimal dependencies
3. Clear Interfaces: Each task should have well-defined input and output formats
4. Endgame Mindset: Avoid infinite decomposition; set maximum levels (recommend no more than 3)

Result Aggregation Tips

1. Cross-Validation: Check consistency between subtask results
2. Conflict Resolution: When conflicts are found, analyze causes and provide reasonable explanations
3. **Incremental Aggregatio