OpenClaw Agent Builder

Create specialized openclaw agents with complete workspace structure, identity files, and skills.

When to Use

When building a new openclaw agent for a specific purpose:

Domain-specific agents (Android dev, SEO, content writing, etc.)
Multi-agent routing scenarios
Isolated agent personalities
Workspace-based AI assistants

Core Concepts

OpenClaw Agent Structure

Each agent = isolated brain with:

Workspace: Files (AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md, etc.)
State dir: ~/.openclaw/agents/<agentId>/agent (auth, config)
Sessions: ~/.openclaw/agents/<agentId>/sessions (chat history)

Workspace Files

Required:

AGENTS.md - Operating instructions, memory management, behavior rules
SOUL.md - Persona, tone, communication style
USER.md - User context and how to address them
IDENTITY.md - Agent name, emoji, role, mission
TOOLS.md - Tool notes and conventions

Optional:

HEARTBEAT.md - Heartbeat checklist (keep short)
BOOT.md - Startup checklist when gateway restarts
memory/ - Daily memory logs (YYYY-MM-DD.md)
MEMORY.md - Curated long-term memory
skills/ - Workspace-specific skills

Agent Builder Workflow

1. Ask Questions First

Before building, clarify:

Agent purpose: What problem does this agent solve?
Domain expertise: What specialized knowledge needed?
Communication style: Professional? Casual? Technical?
Tools/integrations: APIs, databases, external systems?
Skills needed: Custom capabilities or workflows?

2. Create Workspace Structure

# Create agent workspace
mkdir -p ~/.openclaw/workspace-<agent-name>
cd ~/.openclaw/workspace-<agent-name>

# Initialize git (recommended)
git init

3. Build Core Files

IDENTITY.md - Who the agent is:

# IDENTITY.md

## Name
[Agent Name]

## Emoji
[1-2 relevant emojis]

## Role
[Short role description - e.g., "Android spec writer", "SEO optimizer"]

## Mission
[Concise mission statement - what the agent does and why]

SOUL.md - Personality and tone:

# SOUL.md - [Agent Name]

## Who You Are

[Description of expertise, background, strengths]

## Your Expertise

### [Domain 1]
- [Specific skill or knowledge area]
- [Another capability]

### [Domain 2]
- [Capability]

## Your Approach

### [Trait 1 - e.g., Analytical, Pragmatic]
- [How this manifests]

### [Trait 2]
- [Behavior pattern]

## Your Tone

[Communication style - concise/verbose, formal/casual, technical level]

## Your Values

1. **[Value 1]** - [Why it matters]
2. **[Value 2]** - [Explanation]

AGENTS.md - Operating instructions:

# AGENTS.md - [Agent Name]

[Brief agent description and primary role]

## Primary Responsibilities

1. **[Task 1]** - [Description]
2. **[Task 2]** - [Description]

## Workflow

### On User Request: "[Trigger Pattern]"

1. **[Step 1]** [Action description]
   [Details, commands, or sub-steps]

2. **[Step 2]** [Next action]

### On User Request: "[Another Pattern]"

[Workflow steps]

## [Domain-Specific Section - e.g., "iOS Codebase Structure"]

[Relevant context, file paths, patterns]

## [Another Section - e.g., "Translation Guidelines"]

[Reference tables, mappings, rules]

## Memory

- Log [what to track] in `memory/YYYY-MM-DD.md`
- [Memory strategy specific to agent purpose]

## Tools

See `TOOLS.md` for [domain-specific tools or integrations]

## Skills

- **[skill-name]** - [Purpose]
- **[another-skill]** - [Purpose]

USER.md - User context:

# USER.md

## Who You Are

[User description, preferences, context]

## Your Goals

[What user wants to achieve with this agent]

## Communication Preferences

[How user prefers to interact]

TOOLS.md - Tool conventions:

# TOOLS.md

## [Domain] Tools

- **[Tool/API name]**: [Purpose and usage notes]
- **[Another tool]**: [Notes]

## Authentication

[If agent needs API keys, credentials, etc.]

## Conventions

[Domain-specific conventions or patterns]

4. Add Skills (Optional)

Create workspace-specific skills:

mkdir -p skills/<skill-name>

Each skill needs SKILL.md:

---
name: skill-name
description: What the skill does
---

# Skill Name

[Skill documentation following agentskills.io format]

## When to Use

[Trigger conditions]

## Steps

[Detailed workflow]

## Examples

[Usage examples]

5. Setup Memory System

mkdir -p memory
touch memory/$(date +%Y-%m-%d).md

Optional MEMORY.md for curated knowledge:

# MEMORY.md

## [Category]

- [Key fact or pattern]
- [Lesson learned]

## [Another Category]

[Organized knowledge]

6. Register Agent

# Add agent to openclaw
openclaw agents add <agent-name>

# Set workspace path
# Edit ~/.openclaw/openclaw.json:
{
  "agents": {
    "list": [
      {
        "id": "<agent-name>",
        "workspace": "~/.openclaw/workspace-<agent-name>"
      }
    ]
  }
}

7. Add Bindings (Multi-Agent Routing)

Route specific channels/users to this agent:

{
  "bindings": [
    {
      "agentId": "<agent-name>",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "direct", "id": "+1234567890" }
      }
    }
  ]
}

Design Principles

Agent Identity

Clear purpose: Single, focused responsibility
Distinct personality: Unique tone/approach vs other agents
Expertise depth: Deep knowledge in specific domain

Communication Style

Concise: Default to brevity unless domain requires detail
Professional: Match industry standards
Actionable: Focus on what to do, not just description

Memory Strategy

Daily logs: Track important events/decisions
Curated knowledge: Extract patterns into MEMORY.md
Context preservation: Save state before /new or /reset

Skill Organization

Workspace skills: Agent-specific capabilities
Shared skills: Common utilities in ~/.openclaw/skills/
Override pattern: Workspace skills override shared/bundled

Example Agents

Android Spec Generator

Purpose: Analyze iOS features, generate Android requirement specs
Style: Concise, technical, requirement-focused
Skills: ios-analyzer, android-spec-generator, github-issue-creator

SEO Expert

Purpose: Content optimization, keyword research, SEO strategy
Style: Data-driven, analytical, actionable
Skills: keyword-research, content-analyzer, competitor-analysis

Content Writer

Purpose: Blog posts, documentation, technical writing
Style: Clear, engaging, audience-aware
Skills: content-planner, seo-writer, editor

Anti-Patterns

❌ Don't:

Mix multiple unrelated domains in one agent
Create verbose, chatty agents unless purpose requires it
Duplicate content across AGENTS.md, SOUL.md, TOOLS.md
Store secrets in workspace (use ~/.openclaw/credentials/)

✅ Do:

Keep single, clear focus per agent
Match communication style to domain norms
Organize by responsibility (identity/soul/operations)
Use git for workspace backup (private repo)

Testing Agent

# Start gateway with agent
openclaw gateway --agent <agent-name>

# Or use binding to route to agent
openclaw gateway

# Send test message via WhatsApp/Telegram/Discord
# Verify agent responds with expected personality/capability

Maintenance

Update Agent

cd ~/.openclaw/workspace-<agent-name>
git add .
git commit -m "Update [what changed]"
git push

Add New Skill

cd ~/.openclaw/workspace-<agent-name>/skills
mkdir new-skill
# Create SKILL.md

Backup Agent

# Workspace already in git
# Separately backup sessions if needed:
tar -czf sessions-backup.tar.gz ~/.openclaw/agents/<agent-name>/sessions/

Resources

Questions Before Building?

Ask user to clarify:

Agent purpose and scope
Communication style preferences
Required integrations/APIs
Routing strategy (dedicated channel vs shared)
Skill requirements