075383990f
Build complete autonomous agent systems with Claude Code. 7-phase guided workflow: map work, CLAUDE.md, agent team, pipeline, security, deployment, test. Components: - commands/build.md: main guided workflow - agents/builder.md: scaffolding agent - skills/agent-system-design: architecture knowledge + 4 references - scripts/templates: hooks, automation, launchd, systemd Covers 22 OpenClaw capabilities across 4 deployment targets (local, Mac Mini, VPS, Managed Agents). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
115 lines
6.1 KiB
Markdown
115 lines
6.1 KiB
Markdown
---
|
|
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/<name>/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: <slug> # required, used for routing
|
|
description: | # required, must include <example> blocks
|
|
...
|
|
model: sonnet|opus # required
|
|
tools: [...] # required, explicit allowlist
|
|
color: <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-builder: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`
|