Skill-to-Agent

Transform any OpenClaw skill into a fully functional agent with proper workspace configuration and session management. Solves common failures like thread=true is unavailable and mode="session" requires thread=true.

Quick Start

1. Analyze skill - Read SKILL.md to understand requirements
2. Prepare workspace - Create agent directory in ~/.openclaw/agents/
3. Configure agent - Set up identity, tools, and memory strategy
4. Spawn with correct binding - Choose appropriate mode based on channel

Workflow

Phase 1: Skill Analysis

• Extract metadata from SKILL.md (name, description, triggers)
• Identify required tools and dependencies
• Determine agent type: isolated, thread-bound, or run-mode

Phase 2: Workspace Setup

• Create agent directory with proper structure
• Copy skill files (references/, scripts/)
• Configure AGENTS.md, TOOLS.md, USER.md

Phase 3: Agent Configuration

• Create SOUL.md and IDENTITY.md with skill personality
• Map skill tools to agent capabilities
• Set up memory strategy (MEMORY.md, memory/ directory)

Phase 4: Agent Registration

• Add agent to OpenClaw's agents.list configuration
• Use gateway tool with config.patch action
• Include agent ID, name, workspace, and agentDir
• Gateway will restart to apply configuration

Phase 5: Session Spawning

• Choose spawn strategy based on channel capabilities
• Execute with correct binding (thread-bound, isolated, run-mode)
• CRITICAL: Always set cwd to agent workspace directory
• Verify agent activation and tool access

Reference Materials

For detailed guidance, refer to:

• Usage Guide - usage-guide.md - Complete workflow with examples
• Troubleshooting - troubleshooting.md - Common errors and solutions
• War Room Example - war-room-example.md - Detailed conversion example

Scripts

• scripts/skill_to_agent.js - Main conversion script

Binding Strategies

Scenario	Mode	Thread	Best For
Discord/Telegram	session	true	Group discussions
WebChat/Control UI	run	false	One-shot tasks
Isolated Processing	session	false	Background work
Cron/Scheduled	run	false	Automated tasks

Decision Tree:

• Channel supports threads? → Yes → thread=true, mode=session
• Isolated processing needed? → Yes → thread=false, mode=session
• Otherwise → thread=false, mode=run

Common Errors & Solutions

Error 1: thread=true is unavailable

• Solution: Use mode="run" without thread binding
• Check channel capabilities first

Error 2: mode="session" requires thread=true

• Solution: Use isolated session mode
• mode="session", thread=false, runtime="subagent"

Error 3: Agent lacks tool access

• Solution: Verify tools in TOOLS.md
• Update workspace configuration

Error 4: Workspace files not accessible

• Solution: Set cwd parameter when spawning agent
• Agent workspace must be at path specified in cwd
• Ensure agent has read/write permissions to workspace

Error 5: Agent can't find its identity files

• Solution: Always set cwd to agent workspace directory
• Agent reads IDENTITY.md, SOUL.md, etc. from current directory
• Test file access with simple read commands

Error 6: Agent not recognized by OpenClaw system

• Solution: Register agent in agents.list configuration
• Use gateway tool with config.patch action
• Gateway restart required for configuration changes
• Verify agent appears in configured agents list

Critical: Workspace Directory (cwd)

When spawning an agent, ALWAYS set the cwd parameter to the agent's workspace directory:

sessions_spawn({
  task: "Agent instructions...",
  label: "agent-name",
  runtime: "subagent",
  mode: "session", // or "run"
  cwd: "/Users/nimbletenthousand/.openclaw/agents/agent-name",
  timeoutSeconds: 300
});

Without cwd, the agent cannot find its identity files (IDENTITY.md, SOUL.md, etc.) and will fail to function properly.

Critical: Agent Registration

After creating an agent workspace, register it in OpenClaw's configuration:

gateway({
  action: "config.patch",
  raw: JSON.stringify({
    agents: {
      list: [
        {
          id: "agent-name",
          name: "Agent Display Name",
          workspace: "/Users/nimbletenthousand/.openclaw/workspace",
          agentDir: "/Users/nimbletenthousand/.openclaw/agents/agent-name"
        }
      ]
    }
  }),
  note: "Added [agent-name] to agents configuration"
});

The gateway will restart automatically to apply the configuration. Without registration, the agent won't be recognized as a configured agent in the system.

Quick Commands

# Check skill structure
node scripts/skill_to_agent.js --analyze --skill /path/to/skill

# Create agent workspace
node scripts/skill_to_agent.js --create --skill /path/to/skill --agent agent-name

# Spawn agent with correct binding
node scripts/skill_to_agent.js --spawn --agent agent-name --mode session --cwd /path/to/agent-workspace

Best Practices

1. Keep it lean - Only copy essential skill files
2. Test binding first - Verify channel capabilities
3. Monitor agent health - Check sessions_list regularly
4. Clean up properly - Remove unused agent workspaces
5. Document conversions - Save configuration for future reference

Next Steps

After creating an agent:

1. Verify it appears in sessions_list
2. Test tool accessibility
3. Configure heartbeat if needed
4. Set up orchestration with parent agent

For advanced usage and complete examples, see the reference files.