6.1 KiB
| name | description | version |
|---|---|---|
| agent-system-design | 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" | 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
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-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