claude-config/skills/openclaw-create-agent/SKILL.md

name, description

name	description
openclaw-create-agent	Create a new OpenClaw agent with Discord integration -- directory setup, bootstrap files, config update, and verification on the homelab server.

Create OpenClaw Agent

When to Use

• User asks to create/add a new OpenClaw agent
• User wants to connect a new AI bot to Discord via OpenClaw
• User says "create agent", "add agent", "new bot" in the context of OpenClaw

Do NOT use for modifying existing agents -- use the openclaw skill instead.

---

Environment

• Server: yiukai@192.168.68.108
• Config: /home/yiukai/.openclaw/openclaw.json (JSON, hot-reloads on save)
• Home: /home/yiukai/.openclaw/
• Owner Discord ID: 964122056163721286
• Default model: kimi-coding/k2p5
• All commands run via ssh yiukai@192.168.68.108 '<command>'

---

Required Input

Gather ALL before starting. Ask the user for any missing items:

Item	Required	Default	Example
Agent ID	Yes	--	xhs-creator (lowercase, hyphenated)
Display Name	Yes	--	小红薯
Discord Bot Token	Yes	--	MTQ4NTMw...
Guild ID	Yes	--	1485305839379021871
Channel ID	Yes	--	1485305839828074620
Purpose	Yes	--	小红书内容创作、话题分析
Require Mention	No	false	true for shared channels
Model	No	kimi-coding/k2p5	google-antigravity/claude-opus-4-6-thinking

Remind user of Discord bot prerequisites if they don't have a token yet:

1. https://discord.com/developers/applications > New Application
2. Bot page > Reset Token > copy
3. Enable Message Content Intent (Privileged Gateway Intents)
4. OAuth2 > URL Generator > scope bot > permissions: Send Messages, Read Message History, Add Reactions
5. Invite bot to the target server using the generated URL

---

Procedure

Step 1: Pre-flight Checks

Decode the bot user ID from the token's first segment (before first .):

echo "FIRST_SEGMENT" | base64 -d

Then verify the agent doesn't already exist:

ssh yiukai@192.168.68.108 'node -e "
const cfg = JSON.parse(require(\"fs\").readFileSync(\"/home/yiukai/.openclaw/openclaw.json\", \"utf8\"));
const exists = cfg.agents.list.some(a => a.id === \"AGENT_ID\");
console.log(exists ? \"CONFLICT: agent already exists\" : \"OK: agent ID available\");
"'

If CONFLICT, stop and ask user to choose a different ID or confirm they want to update the existing agent.

Step 2: Create Directories

ssh yiukai@192.168.68.108 "mkdir -p ~/.openclaw/workspace-AGENT_ID ~/.openclaw/agents/AGENT_ID/agent"

Step 3: Write AGENTS.md

Write to /home/yiukai/.openclaw/workspace-AGENT_ID/AGENTS.md via SSH heredoc. IMPORTANT: All .md bootstrap files go in the WORKSPACE directory, NOT agentDir. agentDir only stores JSON config files (auto-managed by OpenClaw).

Tailor content to the agent's purpose. Every AGENTS.md must include:

1. Identity statement -- one sentence: who the agent is and what it specializes in
2. Core capabilities -- 3-5 numbered sections with concrete descriptions
3. Workflow or output templates -- structured format the agent should follow when producing output
4. Constraints -- what the agent must NOT do

Use the user's stated purpose to generate domain-specific content. Do NOT use generic placeholder text.

Step 4: Write SOUL.md

Write to /home/yiukai/.openclaw/workspace-AGENT_ID/SOUL.md via SSH heredoc.

Keep it short (20-30 lines). Must include:

1. Identity -- one-line character description
2. Tone -- 3-4 bullet points on communication style
3. Language -- specify primary language (usually Chinese)
4. Boundaries -- 3-4 things the agent refuses to do

Step 5: Update Config

Use a single Node.js script via SSH to atomically update all three config sections. The script must:

1. Read the current config
2. Add agent entry to agents.list
3. Add Discord account to channels.discord.accounts
4. Add binding to bindings
5. Write back

ssh yiukai@192.168.68.108 'node -e "
const fs = require(\"fs\");
const path = \"/home/yiukai/.openclaw/openclaw.json\";
const cfg = JSON.parse(fs.readFileSync(path, \"utf8\"));

// --- Agent ---
cfg.agents.list.push({
  id: \"AGENT_ID\",
  name: \"AGENT_ID\",
  workspace: \"/home/yiukai/.openclaw/workspace-AGENT_ID\",
  agentDir: \"/home/yiukai/.openclaw/agents/AGENT_ID/agent\",
  model: \"MODEL\",
  identity: { name: \"DISPLAY_NAME\" },
  groupChat: {
    mentionPatterns: [
      \"<@!?BOT_USER_ID>\",
      \"DISPLAY_NAME\",
      \"SHORT_ALIAS\",
      \"BOT_USER_ID\"
    ]
  }
});

// --- Discord Account ---
cfg.channels.discord.accounts[\"AGENT_ID\"] = {
  name: \"DISPLAY_NAME\",
  enabled: true,
  token: \"FULL_BOT_TOKEN\",
  groupPolicy: \"open\",
  streaming: \"off\",
  guilds: {
    \"GUILD_ID\": {
      requireMention: REQUIRE_MENTION_BOOL,
      users: [\"964122056163721286\", \"BOT_USER_ID\"],
      channels: { \"CHANNEL_ID\": { allow: true } }
    }
  }
};

// --- Binding ---
cfg.bindings.push({
  agentId: \"AGENT_ID\",
  match: { channel: \"discord\", accountId: \"AGENT_ID\" }
});

fs.writeFileSync(path, JSON.stringify(cfg, null, 2));
console.log(\"OK: config updated\");
"'

Substitute ALL placeholders before executing. Never leave template variables in the actual command.

Step 6: Verify

Wait 5 seconds for hot-reload, then check logs:

ssh yiukai@192.168.68.108 'journalctl --user -u openclaw-gateway --since "30 sec ago" --no-pager 2>&1 | grep -iE "AGENT_ID|error|reload"'

Success indicators (all three must appear):

• [reload] config change detected -- hot-reload triggered
• [discord] [AGENT_ID] starting provider -- bot connected to Discord
• channels resolved: GUILD_ID/CHANNEL_ID -- channel mapped successfully

If hot-reload fails, restart manually:

ssh yiukai@192.168.68.108 'systemctl --user restart openclaw-gateway'

Then recheck logs.

If bot fails to connect, common causes:

• Bot not invited to server -- remind user to use OAuth2 invite link
• Message Content Intent not enabled -- user must enable in Developer Portal
• Invalid token -- ask user to regenerate

Step 7: Report to User

Summarize:

• Agent ID and display name
• Discord server and channel (by name if visible in logs)
• Mention requirement
• Model
• Next step: send a test message in the Discord channel

---

Optional: Add Cron Job

If the user wants scheduled tasks:

ssh yiukai@192.168.68.108 'node -e "
const fs = require(\"fs\");
const path = \"/home/yiukai/.openclaw/openclaw.json\";
const cfg = JSON.parse(fs.readFileSync(path, \"utf8\"));
if (!cfg.cron) cfg.cron = { enabled: true, entries: [] };
if (!cfg.cron.entries) cfg.cron.entries = [];
cfg.cron.entries.push({
  name: \"JOB_NAME\",
  schedule: \"CRON_EXPRESSION\",
  timezone: \"Europe/Stockholm\",
  agentId: \"AGENT_ID\",
  message: \"TASK_PROMPT\",
  deliver: { channel: \"discord\", target: \"channel:CHANNEL_ID\" }
});
fs.writeFileSync(path, JSON.stringify(cfg, null, 2));
console.log(\"OK: cron job added\");
"'

Optional: Enable Agent-to-Agent Communication

1. Add agent ID to tools.agentToAgent.allow array
2. Set subagents.allowAgents on the calling agent
3. Set requireMention: true on all collaborating agents in the shared guild