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

bash

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

markdown

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

markdown

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

markdown

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

markdown

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

markdown

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

bash

mkdir -p skills/<skill-name>

Each skill needs

SKILL.md

markdown

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

bash

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

Optional

MEMORY.md

for curated knowledge:

markdown

# MEMORY.md

## [Category]

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

## [Another Category]

[Organized knowledge]

6. Register Agent

bash

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

json5

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

bash

# 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

bash

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

Add New Skill

bash

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

Backup Agent

bash

# 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

openclaw-agent-builder

NPX Install

Tags

SKILL.md Content

OpenClaw Agent Builder

When to Use

Core Concepts

OpenClaw Agent Structure

Workspace Files

Agent Builder Workflow

1. Ask Questions First

2. Create Workspace Structure

3. Build Core Files

4. Add Skills (Optional)

5. Setup Memory System

6. Register Agent

7. Add Bindings (Multi-Agent Routing)

Design Principles

Agent Identity

Communication Style

Memory Strategy

Skill Organization

Example Agents

Android Spec Generator

SEO Expert

Content Writer

Anti-Patterns

Testing Agent

Maintenance

Update Agent

Add New Skill

Backup Agent

Resources

Questions Before Building?