Multi-Agent Setup

SKILL.md

---
name: multi-agent-setup
description: Set up new Clawdbot agents with proper workspace structure, gateway configuration, and platform bindings. Use when creating new agents for specialized roles (research, ops, support) or when needing to add agent configurations to the gateway config file.
---

# Multi-Agent Setup

Create and configure new Clawdbot agents with complete workspace setup, identity configuration, and gateway integration.

## Quick Start

For automated setup, use the provided script:

```bash
scripts/setup-agent.sh --name "AgentName" --emoji "🤖" --purpose "Brief purpose" --platform telegram
```

For manual setup, follow the steps below.

## Step 1: Gather Agent Requirements

Before creating an agent, collect:

1. **Name** - Agent's identity (e.g., "Spock", "Ada", "Scotty")
2. **Emoji** - Visual identifier (e.g., 🖖, 🔮, ⚙️)
3. **Purpose** - Primary role/responsibilities (e.g., "Research and ops specialist")
4. **Platform** - Communication channel (telegram, discord, slack, whatsapp)
5. **Workspace Path** - Where agent files live (e.g., `/home/user/clawd-spock`)
6. **Model** - Optional model override (default uses agents.defaults.model)
7. **Account ID** - Platform-specific account identifier for binding

## Step 2: Create Workspace Structure

Create the agent workspace directory with core files:

```bash
mkdir -p /path/to/agent-workspace
cd /path/to/agent-workspace
```

Create these required files using templates:
- `SOUL.md` - Agent's core identity and purpose (template: templates/SOUL.md)
- `IDENTITY.md` - Quick reference identity card (template: templates/IDENTITY.md)
- `AGENTS.md` - Session workflow and coordination rules (template: templates/AGENTS.md)
- `TOOLS.md` - User tool notes (template: templates/TOOLS.md)
- `HEARTBEAT.md` - Heartbeat configuration (optional)

Create supporting directories:
```bash
mkdir -p memory secrets skills
```

## Step 3: Configure Gateway

Add the agent to `~/.clawdbot/clawdbot.json` in three sections:

### 3a. Add Agent Entry

Add to `agents.list` array:

```json
{
  "id": "agent-id",
  "name": "AgentName",
  "workspace": "/path/to/agent-workspace",
  "model": "anthropic/claude-sonnet-4-5",
  "identity": {
    "name": "AgentName",
    "emoji": "🤖"
  },
  "subagents": {
    "allowAgents": []
  }
}
```

**Important fields:**
- `id` - Lowercase identifier, used in bindings (e.g., "spock", "scotty")
- `name` - Display name for the agent
- `workspace` - Absolute path to agent directory
- `model` - Optional; defaults to agents.defaults.model if omitted
- `identity.emoji` - Visual identifier for the agent
- `subagents.allowAgents` - Array of agent IDs this agent can spawn as subagents

### 3b. Add Platform Account (if needed)

If using a dedicated platform account, add to the appropriate channel configuration.

For Telegram, add to `channels.telegram.accounts`:

```json
"agent-id": {
  "dmPolicy": "pairing",
  "botToken": "BOT_TOKEN_HERE",
  "groups": {
    "*": {
      "requireMention": true
    }
  },
  "groupPolicy": "open",
  "streamMode": "block"
}
```

For Discord, add bot token to credentials and configure accordingly.

### 3c. Add Binding

Add binding to route messages to the agent. Add to `bindings` array:

```json
{
  "agentId": "agent-id",
  "match": {
    "channel": "telegram",
    "accountId": "agent-id"
  }
}
```

**Binding logic:**
- `agentId` - Must match the agent's `id` in agents.list
- `match.channel` - Platform (telegram, discord, slack, etc.)
- `match.accountId` - Account identifier (matches the account key in channel config)

## Step 4: Populate Workspace Files

### SOUL.md
Define the agent's:
- Core identity and purpose
- Domain of responsibility
- Personality traits and working style
- Relationship with other agents
- Boundaries and coordination rules

See `templates/SOUL.md` for structure.

### IDENTITY.md
Quick reference card with:
- Name, creature/role description
- Vibe/personality keywords
- Emoji
- Optional: persona, creation date

See `templates/IDENTITY.md` for structure.

### AGENTS.md
Operational procedures:
- Session startup checklist
- Memory management approach
- Coordination with other agents
- Tool usage guidelines
- Session wrap-up procedures

See `templates/AGENTS.md` for structure.

## Step 5: Validation Checklist

Before restarting gateway, verify:

**Config Validation:**
- [ ] Agent `id` is lowercase, no spaces
- [ ] Agent `workspace` path exists and is absolute
- [ ] Agent `identity.emoji` is set
- [ ] Platform account exists (if dedicated account)
- [ ] Platform credentials are valid
- [ ] Binding `agentId` matches agent `id` exactly
- [ ] Binding `match.accountId` matches platform account key
- [ ] JSON syntax is valid (run through `jq`)

**Workspace Validation:**
- [ ] `SOUL.md` exists and defines purpose
- [ ] `IDENTITY.md` exists with name/emoji
- [ ] `AGENTS.md` exists with workflow instructions
- [ ] `memory/` directory exists
- [ ] Permissions allow gateway to read/write

**Test:**
```bash
# Validate JSON syntax
jq empty ~/.clawdbot/clawdbot.json

# Check agent configuration
jq '.agents.list[] | select(.id == "agent-id")' ~/.clawdbot/clawdbot.json

# Check binding
jq '.bindings[] | select(.agentId == "agent-id")' ~/.clawdbot/clawdbot.json
```

## Step 6: Apply Configuration

Restart the gateway to load the new agent:

```bash
# Option 1: Using gateway tool (from within Clawdbot session)
# Request the main agent to restart gateway

# Option 2: Manual restart
pkill -f clawdbot
cd ~/clawdbot && npm start
```

After restart, verify:
1. Gateway starts without errors
2. Agent shows up in session list
3. Messages route to correct agent
4. Agent can access workspace files

## Rollback Instructions

If agent setup fails or causes issues:

### Quick Rollback

1. **Remove binding** - Comment out or delete from `bindings` array
2. **Disable agent** - Remove from `agents.list` or set `enabled: false`
3. **Restart gateway** - Apply changes

### Complete Removal

1. Remove agent entry from `agents.list`
2. Remove platform account config (if dedicated)
3. Remove binding from `bindings` array
4. Backup workspace: `mv /path/to/agent-workspace /path/to/agent-workspace.bak`
5. Validate config: `jq empty ~/.clawdbot/clawdbot.json`
6. Restart gateway

### Restore Previous Config

```bash
# Gateway keeps backups
cp ~/.clawdbot/clawdbot.json.bak ~/.clawdbot/clawdbot.json
# Restart gateway
```

## Common Issues

**Agent not receiving messages:**
- Check binding `agentId` matches agent `id` exactly
- Verify `match.accountId` matches platform account key
- Check platform credentials are valid
- Ensure agent has appropriate DM/group policies

**Gateway won't start:**
- Validate JSON: `jq empty ~/.clawdbot/clawdbot.json`
- Check workspace paths exist and are absolute
- Review gateway logs: `tail -f /tmp/clawdbot/clawdbot.log`
- Restore from backup if needed

**Agent can't access files:**
- Verify workspace path is absolute
- Check directory permissions
- Ensure SOUL.md, IDENTITY.md, AGENTS.md exist

## Multi-Agent Coordination

When setting up multiple agents, consider:

**Subagent Allowlists:**
Main agents can spawn subagents. Configure in agent entry:
```json
"subagents": {
  "allowAgents": ["spock", "scotty"]
}
```

**Shared Resources:**
- Use symlinks for shared files (e.g., `ln -s ~/clawd/USER.md ~/clawd-spock/USER.md`)
- Keep agent-specific memory separate
- Coordinate via sessions_send between agents

**Role Separation:**
- Primary agent handles general tasks and coordination
- Specialist agents focus on specific domains (research, ops, support)
- Avoid overlapping responsibilities

## Examples

### Research Agent Setup
```bash
# Create workspace
mkdir -p ~/clawd-research
cd ~/clawd-research

# Copy templates and customize
cp ~/clawd/skills/multi-agent-setup/templates/*.md .

# Edit SOUL.md for research focus
# Edit IDENTITY.md with name/emoji
# Configure gateway with agent entry + binding
# Restart gateway
```

### Operations Agent Setup
```bash
scripts/setup-agent.sh \
  --name "Scotty" \
  --emoji "⚙️" \
  --purpose "Operations and infrastructure specialist" \
  --platform telegram \
  --workspace ~/clawd-scotty \
  --account-id scotty
```

## See Also

- Real examples: Check session logs or existing agent workspaces
- Gateway config reference: `gateway config.schema` action
- Platform setup guides in skills/discord/ and skills/telegram/