agent-builder/skills/agent-system-design/SKILL.md

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-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