--- name: agent-system-design description: | This skill should be used when the user asks about "building an agent", "autonomous agent system", "agent architecture", "OpenClaw alternative", "always-on agent", "personal AI agent", "complete agent system", "agent that runs itself", "agent pipeline design", "multi-agent system", "how to build an agent with Claude Code" version: 0.1.0 --- ## What is an autonomous agent system An autonomous agent system is a set of Claude Code components that work together to execute multi-step workflows with minimal human intervention. The system runs on a schedule, responds to triggers, processes inputs, and produces outputs — all orchestrated through Claude Code's native primitives. You do not need a separate orchestration framework. Claude Code provides everything required: subagents, skills, hooks, and automation scripts. ## Core architecture pattern The foundational pattern is a three-agent pipeline with a skill that chains them: ``` Trigger (launchd/cron/manual) → Pipeline skill → Agent 1: Researcher (gather and structure inputs) → Agent 2: Writer (produce primary output) → Agent 3: Reviewer (evaluate and approve or revise) → Save outputs → Update memory ``` The pipeline skill is a `.claude/skills//SKILL.md` file with step-by-step instructions. Each step invokes an agent using the `Agent` tool. Agents are defined in `.claude/agents/*.md`. This pattern scales from simple (one agent, one step) to complex (six agents, branching logic, parallel execution). ## System components A complete agent system has seven components: | Component | Location | Purpose | |-----------|----------|---------| | CLAUDE.md | project root | Context, rules, and memory pointers for the project | | Agents | `.claude/agents/*.md` | Specialized subagents with defined roles and tool access | | Pipeline skills | `.claude/skills/*/SKILL.md` | Orchestration sequences that chain agents | | Knowledge skills | `.claude/skills/*/SKILL.md` | Reference knowledge auto-injected by topic | | Hooks | `hooks/*.sh` | Pre/post tool use guards for automated safety | | Settings | `.claude/settings.json` | Permissions, tool allowlists, and hook wiring | | Automation | `scripts/` + `launchd/` | Scheduled execution (Mac: launchd, Linux: systemd/cron) | | Memory | `memory/` or `data/` | Persistent state files updated each run | Not all components are required for every system. Start with agents + one pipeline skill. Add hooks and automation when you move to scheduled/unattended operation. ## Design principles **Start with 2-3 agents.** A researcher and a writer cover most content workflows. A reviewer adds quality gates. Resist the urge to create more agents than you need — each agent adds latency and cost. **Pipeline skills chain agents.** The skill file is the orchestrator. It contains the sequencing logic, error handling instructions, and output routing. Keep agents dumb and focused; put the workflow intelligence in the skill. **Hooks protect automated runs.** When Claude runs unattended, hooks are your circuit breakers. Use `PreToolUse` hooks to block writes to sensitive paths, enforce naming conventions, or validate inputs before destructive operations. Without hooks, an unattended run has no guardrails. **Memory persists state between runs.** Agents cannot remember previous sessions by default. A memory file (e.g., `memory/MEMORY.md` or `data/run-state.json`) gives the system continuity. Update it at the end of every pipeline run. **One concern per agent.** Agents that do too many things are hard to tune and debug. A researcher should research. A writer should write. Mixing concerns makes prompt engineering harder and output quality lower. ## Deployment options | Platform | Best for | Notes | |----------|----------|-------| | Local workstation | Development, on-demand runs | Use launchd (Mac) or cron (Linux) for scheduling | | Mac Mini (always-on) | Personal production pipelines | Runs overnight; launchd + wake schedule | | VPS (Hetzner, DO) | Server-side automation, webhooks | systemd service; pair with SSH access | | Managed Agents | High-volume, API-driven workflows | Claude API `/v1/agents` endpoint; no local shell needed | For most personal or small-team use cases, a Mac Mini or VPS running launchd/systemd is sufficient and much cheaper than Managed Agents at scale. ## OpenClaw capability coverage This architecture covers 22 OpenClaw capabilities. 13 are a full match via native Claude Code primitives. 8 use a different approach but achieve the same outcome. 1 gap remains. For the detailed mapping, see: `${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/feature-map.md` ## Agent frontmatter fields ```yaml name: # required, used for routing description: | # required, must include blocks ... model: sonnet|opus # required tools: [...] # required, explicit allowlist color: # optional, UI hint ``` The `description` field is what triggers agent selection. Write it with concrete user phrases, not abstract capability descriptions. ## Common mistakes - **No examples in agent description** — Claude cannot reliably select the agent without seeing what user messages should trigger it - **Hooks skipped in automation** — unattended runs need guards; add hooks before scheduling - **Memory not updated** — next run starts blind; always write state at the end of a pipeline - **One giant agent** — harder to tune, harder to debug; split by role - **Wrong model for the job** — opus for synthesis and narrative, sonnet for retrieval and transformation ## Getting started Run `/agent-factory:build` for the guided 7-phase workflow. It interviews you about your use case, selects the right pattern, and generates all files. For pipeline design patterns and agent role templates, see: `${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/pipeline-patterns.md` For scheduling and deployment configuration, see: `${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/deployment-config.md` For the OpenClaw feature map, see: `${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/feature-map.md`