# agent-smith

Adopt this skill: https://proskills.md/skills/other/cyijun-agent-smith-agent-smith

Page: https://proskills.md/skills/other/cyijun-agent-smith-agent-smith
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: agent-smith/SKILL.md
size: 9747
upstream: https://github.com/cyijun/agent-smith/blob/main/agent-smith/SKILL.md

````text
---
name: agent-smith
description: Use when a complex task needs parallel decomposition into independent subtasks, when multiple agents must work simultaneously without conflicts, or when recursive task delegation is required
---

# Agent Smith

实现递归自相似多智能体系统的 Skill。每个智能体（史密斯）拥有独立的工作空间，通过目录隔离协议达成无冲突的并行任务分解与执行。

## Overview

Agent Smith 是一个递归自相似的多智能体协作框架。每个智能体（史密斯）遵循相同的协议，在自己的工作空间内独立运行，通过父子间的 inbox/outbox 通信完成复杂任务的分解与汇总。

## When to Use

在以下场景触发本 Skill：

- 用户请求"创建多智能体系统"或"设置 Agent Smith"
- 任务需要分解为多个并行子任务
- 需要协调多个 Agent 同时工作
- 复杂任务需要递归分解处理
- 要求无冲突的并行执行环境

## When NOT to Use

在以下场景请勿触发本 Skill：

- 单个 Agent 可在 15 分钟内独立完成的任务
- 子任务之间存在严格线性依赖（每一步必须等待上一步完成）
- 仅需单 Agent 即可完成，并行执行无收益
- 任务已充分细化，无需进一步分解

## Hard Constraints (Quick Reference)

以下限制由史密斯协议强制执行。修改这些值需要同时更新 `SKILL.md` 和 `smith.md`。

| 限制 | 值 |
|------|-----|
| 最大递归深度 | 3（Level 0 根节点 → 最大 Level 3） |
| 每层最大子代理数 | 5 |
| Level ≥ 3 行为 | 禁止分解，必须直接执行 |

## 核心概念

**史密斯 (Smith)** 是自相似的智能体单元，每个史密斯拥有唯一 ID 和层级，能够执行任务、分解任务、创建子史密斯并汇总结果。所有史密斯遵循相同的协议，形成递归结构。

所有史密斯均受上述 [Hard Constraints](#hard-constraints-quick-reference) 约束。

**无冲突协议** 通过严格的目录隔离实现并行安全：每个史密斯只能写入自己的 `private/` 和 `outbox/`，只能读取自己 `inbox/` 中父史密斯分配的任务。父史密斯拥有创建子目录和写入子史密斯 inbox 的专属权限。

## 目录结构

```
.agent-smith/
├── smiths/
│   ├── smith-root/             # 根史密斯
│   │   ├── smith.md            # 史密斯定义（只读）
│   │   ├── inbox/              # 任务队列（外部/父写入，自己读取）
│   │   ├── private/            # 私有工作区
│   │   ├── outbox/             # 结果输出
│   │   │   └── result.md
│   │   └── children/           # 子史密斯目录
│   │       └── smith-001/
│   │           ├── smith.md
│   │           ├── inbox/      # 父写入，子读取
│   │           ├── private/
│   │           ├── outbox/
│   │           └── children/
└── results/
    └── final.md                # 最终结果
```

## 初始化矩阵

当用户请求初始化 Agent Smith 时，执行以下步骤：

**1. 创建目录结构**

创建根史密斯环境：
- `.agent-smith/smiths/smith-root/inbox/` —— 任务队列
- `.agent-smith/smiths/smith-root/private/` —— 私有工作区
- `.agent-smith/smiths/smith-root/outbox/` —— 结果输出
- `.agent-smith/smiths/smith-root/children/` —— 子史密斯容器
- `.agent-smith/results/` —— 最终结果

**2. 读取 `smith.md` 模板**

从 `smith.md` 读取史密斯定义模板。

**3. 替换占位符**

替换模板中的变量：
- `{SMITH_ID}` → `smith-root`
- `{PARENT_ID}` → `none`
- `{LEVEL}` → `0`

**4. 写入根史密斯定义**

将替换后的内容写入 `.agent-smith/smiths/smith-root/smith.md`。

**5. 创建任务文件**

基于 `templates/task.md.template` 创建根任务文件 `.agent-smith/smiths/smith-root/inbox/task-root.md`。

替换模板占位符：
- `{TITLE}` → 任务标题
- `{TASK_ID}` → `root`
- `{SMITH_ID}` → `smith-root`
- `{PARENT_TASK_ID}` → `none`
- `{TIMESTAMP}` → 当前时间
- `{LEVEL}` → `0`
- `{DESCRIPTION}` → 任务描述
- `{CONTEXT}` → 相关上下文
- `{EXPECTED_OUTPUT}` → 期望输出

**6. 生成启动指南**

在 `.agent-smith/smiths/smith-root/private/START_HERE.md` 生成启动指南，包含：
- 当前身份确认
- 任务文件位置
- 执行流程说明
- 输出要求

## 创建子史密斯

当父史密斯需要创建子史密斯时，执行以下步骤：

**前置检查（强制）**

创建任何子史密斯之前，必须确认：
- [ ] 当前层级 < 3（若层级 ≥ 3，停止——直接执行）
- [ ] 现有子代理数量 < 5（若已达 5 个，停止——直接执行或重新分解）

**1. 确定新史密斯 ID**

按序号递增生成 ID，如 `smith-001`、`smith-002`。

**2. 创建子目录**

在父史密斯的 `children/` 下创建 `{smith-id}/` 目录结构：
- `inbox/` —— 父写入任务，子读取
- `private/` —— 私有工作区
- `outbox/` —— 结果输出
- `children/` —— 子史密斯容器

**3. 读取模板并替换**

读取 `smith.md` 模板，替换占位符：
- `{SMITH_ID}` → 新 ID（如 `smith-001`）
- `{PARENT_ID}` → 当前史密斯 ID
- `{LEVEL}` → 当前层级 + 1

**4. 写入子史密斯定义**

将替换后的内容写入子目录的 `smith.md`。

**5. 生成子任务文件**

基于 `templates/task.md.template` 在子史密斯的 `inbox/` 下创建任务文件 `task-{SMITH_ID}.md`。

替换模板占位符：
- `{TITLE}` → 子任务标题
- `{TASK_ID}` → 子史密斯 ID（如 `smith-001`）
- `{SMITH_ID}` → 子史密斯 ID
- `{PARENT_TASK_ID}` → 父任务 ID
- `{TIMESTAMP}` → 当前时间
- `{LEVEL}` → 当前层级 + 1
- `{DESCRIPTION}` → 子任务描述
- `{CONTEXT}` → 父上下文
- `{EXPECTED_OUTPUT}` → 期望输出

确保任务文件只写入该子史密斯的 `inbox/`，不得写入任何其他史密斯的目录。

**6. 生成子史密斯启动指南**

在子史密斯的 `private/START_HERE.md` 生成启动指南，包含：
- 子史密斯身份确认
- 父史密斯引用
- 任务文件位置
- 执行约束说明

## 执行流程

1. 读取 `inbox/` 中的任务
2. 分析任务复杂度
3. 判断：能否直接完成？
   - **是** → 执行任务 → 将结果写入 `outbox/result.md` → 结束
   - **否** → 对照 [Hard Constraints](#hard-constraints-quick-reference) 检查当前层级
     - 若层级 ≥ 3：**必须直接执行**（禁止分解）
     - 若层级 < 3：设计子任务（最多 5 个）→ 创建子史密斯目录 → 在子史密斯 `inbox/` 中创建任务文件 → 等待子结果 → 汇总 → 写入 `outbox/result.md` → 结束

## 最终结果汇总

根史密斯（Level 0）在完成自身 `outbox/result.md` 后，还有一项额外职责：

- 将根史密斯的 `outbox/result.md` 复制或汇总到 `.agent-smith/results/final.md`

该文件作为用户获取多智能体会话完整输出的统一入口。

## 写约束协议

**允许写入**：
- 自己的 `private/` —— 草稿、思考、临时文件
- 自己的 `outbox/result.md` —— 最终结果
- 自己的 `children/` —— 创建子史密斯目录（父权限）
- 自己 `children/` 下子史密斯的 `inbox/` —— 创建子任务（父权限）

**禁止写入**：
- 其他史密斯的 `private/` 或 `outbox/`
- 父史密斯的任何目录
- 其他史密斯的 `inbox/`（只能写自己创建的子史密斯的 inbox）

## 常见错误与修复

### Red Flags —— 停止并重新评估

遇到以下任何情况时，**禁止**继续分解，应直接执行：

- 子任务预计耗时少于 15 分钟
- 当前层级已 ≥ 3，仍在考虑分解
- 同层子代理数量将超过 5 个
- 子任务之间耦合紧密或需要频繁同步

### 错误：过度分解

**症状：** 为简单任务创建子史密斯，子任务只需几分钟即可完成。
**修复：** 若任务少于 3 个主要步骤或预计 15 分钟内可完成，直接执行。分解带来的协调开销会超过收益。

### 错误：超出递归深度

**症状：** 在 Level 3 或更深层级仍试图创建子史密斯。
**修复：** 硬限制为 Level 3。当层级 ≥ 3 时，必须直接执行。若任务仍过大，应优化任务定义而非违反协议。

### 错误：写入错误目录

**症状：** 在自己子代理的 `inbox/` 以外创建任务文件，或修改其他史密斯的 `private/` 或 `outbox/`。
**修复：** 重新阅读 [写约束协议](#写约束协议)。只允许写入：自己的 `private/`、自己的 `outbox/`、自己的 `children/`、自己子代理的 `inbox/`。

### 错误：子代理 ID 冲突

**症状：** 两个同层子史密斯使用相同 ID（例如同一父节点下有两个 `smith-001`）。
**修复：** 每个父节点使用严格递增序号（`smith-001`、`smith-002`...）。创建目录前验证无冲突。

## 参考资料

- [核心概念详解](./references/concepts.md) —— 史密斯的定义、目录隔离机制、递归分解策略
- [协议规范](./references/protocol.md) —— 详细的通信协议和约束规则
- [最佳实践](./references/best-practices.md) —— 任务分解原则、结果汇总技巧

## 示例

- [市场研究示例](./examples/market-research.md) —— 展示如何将复杂的市场研究任务分解为 4 个并行子任务
- [代码重构示例](./examples/code-refactor.md) —— 展示如何并行处理大规模代码重构

## 安装

将此目录复制到 Claude Code skills 目录：

```bash
# 从仓库根目录执行
cp -r agent-smith/agent-smith ~/.claude/skills/agent-smith
```
````

## File: README.md
upstream: https://github.com/cyijun/agent-smith/blob/main/README.md

````text
# Agent Smith

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

**English** | [简体中文](README_CN.md)

---

## 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:

```bash
# 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:

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

### Usage

1. **Initialize the Matrix**

   Create the `.agent-smith/` structure in your working directory:
   ```bash
   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:
   ```markdown
   # 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](./agent-smith/examples/market-research.md)

### 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 Aggregation**: Partially aggregate results immediately after subtasks complete to avoid backlog
4. **Traceability**: Reference output paths of each subtask in aggregated results

---

## Project Structure

```
agent-smith/
├── SKILL.md              # Claude Code Skill definition
├── smith.md              # Smith core prompt template
├── examples/             # Usage examples
│   ├── market-research.md
│   └── code-refactor.md
├── references/           # Reference materials
│   ├── concepts.md       # Core concept details
│   ├── protocol.md       # Protocol specification
│   └── best-practices.md # Best practices
└── templates/            # File templates
```

---

## Protocol Specification

### Hard Constraints

These limits are enforced by the Smith protocol. Changing them requires updating both `SKILL.md` and `smith.md`.

| Constraint | Value |
|------------|-------|
| Maximum recursion depth | 3 (Level 0 root → max Level 3) |
| Maximum children per Smith | 5 |
| Level ≥ 3 behavior | Must execute directly; decomposition forbidden |

### Agent Definition File (smith.md)

```yaml
---
smith_id: smith-001
parent_id: smith-root
level: 1
created_at: 2026-03-05
---

# Smith {SMITH_ID}

## Identity
- ID: {SMITH_ID}
- Parent: {PARENT_ID}
- Level: {LEVEL}

## Task
Read inbox/task-{ID}.md and execute

## Constraints
- Only write to your own private/ and outbox/
- Can create child agents under children/
- Must output to outbox/result.md upon completion
```

### Result Output Format (outbox/result.md)

```markdown
# Result: {Task Title}

## Summary
One-sentence summary of the execution result.

## Detailed Results
...

## Subtask References (if any)
- smith-xxx: Responsible for ...
- smith-yyy: Responsible for ...

## Completion Status
- [x] Completed
- Completion time: 2026-03-05 12:00:00
```

### Root Smith Responsibility

After writing its own `outbox/result.md`, the root Smi
````
