agent-smith: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Agent Smith is a Claude Code skill that implements a recursive self-similar multi-agent system. It enables conflict-free parallel task decomposition and execution through a strict directory isolation protocol.

This is a documentation-only project. There are no build scripts, test suites, package managers, or compiled artifacts. The entire "product" is a set of Markdown files that define the skill behavior, agent protocols, examples, and templates.

Project Structure

agent-smith/
├── SKILL.md              # Claude Code skill entry point (trigger definitions, initialization logic)
├── smith.md              # Core agent prompt template (Chinese) — defines Smith identity, protocol, constraints
├── examples/             # Usage examples
│   ├── market-research.md
│   └── code-refactor.md
├── references/           # Reference documentation
│   ├── concepts.md       # Core concepts: Smith definition, directory isolation, recursive decomposition
│   ├── protocol.md       # Conflict-free protocol: write isolation, parent-child rules, queue consumption
│   └── best-practices.md # Task decomposition guidelines, result aggregation tips
└── templates/
    └── task.md.template  # Task file template for inbox/ tasks

Root-level README.md and README_CN.md are user-facing documentation, not part of the skill runtime.

Development Workflow

Installing the Skill for Testing

After editing any skill file, reinstall it to Claude Code's skills directory:

cp -r agent-smith ~/.claude/skills/

Then test by invoking one of the trigger phrases (e.g., "create multi-agent system") in a Claude Code session.

What to Edit

• agent-smith/SKILL.md — Skill metadata, trigger conditions, initialization steps, child-agent creation logic. This is what Claude Code reads when the skill is invoked.
• agent-smith/smith.md — The agent definition template copied to each Smith's directory. Contains the core protocol, recursion limits, write constraints, and result format. Placeholders {SMITH_ID}, {PARENT_ID}, {LEVEL} are replaced at creation time.
• agent-smith/references/ — Deep-dive docs referenced by SKILL.md. Keep in sync if you change protocol rules.
• agent-smith/examples/ — Scenario walkthroughs. Update if you add new features or change decomposition patterns.
• agent-smith/templates/task.md.template — Task file template used when creating inbox tasks.