⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
agent-smith
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
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
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
-
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 -
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 -
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:
- Market trend analysis
- Key vendor research
- Technology development tracking
- Application scenario research
Code Review
Break down large-scale code review into module-level parallel processing:
- Data layer review
- Business logic layer review
- API interface layer review
- Frontend component review
Content Creation
Distributed collaboration for content projects:
- Outline design
- Section writing (multiple authors in parallel)
- Editing and proofreading
- Format standardization
Best Practices
Task Decomposition Principles
- Granularity Control: Each subtask should be completable in 1-4 hours
- Independence First: Subtasks should have low coupling and minimal dependencies
- Clear Interfaces: Each task should have well-defined input and output formats
- Endgame Mindset: Avoid infinite decomposition; set maximum levels (recommend no more than 3)
Result Aggregation Tips
- Cross-Validation: Check consistency between subtask results
- Conflict Resolution: When conflicts are found, analyze causes and provide reasonable explanations
- Incremental Aggregation: Partially aggregate results immediately after subtasks complete to avoid backlog
- 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)
---
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)
# 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
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
agent-smith/SKILL.md9.5 KBupstream ↗
--- 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 ```README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/cyijun-agent-smith-agent-smith.md