1  ---
  2  name: swarmclaw
  3  description: AI agent runtime and multi-agent orchestration platform. Teaches agents how to use SwarmClaw's 6 primitive tools, persistent memory, dreaming, delegation, connectors, credentials, and the skill system. Use when an agent is running on SwarmClaw and needs to understand the platform's capabilities.
  4  metadata:
  5    openclaw:
  6      emoji: "\U0001F41D"
  7      privacyPolicy: All data stays on the local SwarmClaw instance. Memory, workspace files, and session data are stored on the host machine. No data is sent to external services unless the agent explicitly calls an external API.
  8      dataHandling: Agent memory is stored locally in the SwarmClaw data directory. Workspace files are scoped per agent. Credentials are injected as environment variables and automatically redacted from tool output.
  9  version: 2.4.1
 10  author: swarmclawai
 11  homepage: https://swarmclaw.ai
 12  tags: [agents, orchestration, multi-agent, runtime, memory, delegation, skills, connectors, dreaming]
 13  ---
 14  
 15  # SwarmClaw Platform
 16  
 17  SwarmClaw is an AI agent runtime and multi-agent orchestration platform. It gives agents a uniform set of tools, persistent memory, connector integrations, and the ability to delegate work to other agents.
 18  
 19  Website: https://swarmclaw.ai
 20  Docs: https://swarmclaw.ai/docs
 21  GitHub: https://github.com/swarmclawai/swarmclaw
 22  npm: `npm install -g swarmclaw`
 23  
 24  ## The 6 Primitive Tools
 25  
 26  Every agent has access to these core tools. They cover the full range of agent capabilities.
 27  
 28  | Tool | Purpose | When to Use |
 29  |------|---------|-------------|
 30  | **files** | Read, write, edit, list, search files | Any file operation on the workspace filesystem |
 31  | **execute** | Run bash scripts (sandboxed or host) | Shell commands, curl, data processing, package management |
 32  | **memory** | Store and retrieve persistent knowledge | Facts, preferences, decisions that should survive across sessions |
 33  | **platform** | Tasks, communication, delegation, projects | Coordinating with humans and other agents |
 34  | **browser** | Control a headless browser | Interactive web pages, JavaScript-rendered content |
 35  | **skills** | Discover and load skill documentation | Learning how to use tools, APIs, or workflows |
 36  
 37  ### Tool Selection Guide
 38  
 39  | Task | Tool |
 40  |------|------|
 41  | Edit a source file | `files` (edit action) |
 42  | Run tests | `execute` |
 43  | Call a REST API (JSON) | `execute` (curl) |
 44  | Scrape a dynamic web page | `browser` |
 45  | Remember a user preference | `memory` |
 46  | Ask the user a question | `platform` (communicate.ask_human) |
 47  | Send a Slack message | `platform` (communicate.send_message) |
 48  | Hand off work to another agent | `platform` (communicate.delegate) |
 49  | Find out how a tool works | `skills` (read action) |
 50  
 51  ## Credentials
 52  
 53  Credentials are configured per agent in the SwarmClaw UI. They are:
 54  
 55  - **Injected as environment variables** into `execute` tool runs (e.g., `$OPENAI_API_KEY`, `$GITHUB_TOKEN`)
 56  - **Automatically redacted** from all tool output -- secrets never appear in chat history
 57  - **Named by convention**: `<PROVIDER>_API_KEY` or custom names set in the credential config
 58  
 59  You never need to ask the user for API keys directly. If a credential is configured, it's available as an env var. If it's not configured, tell the user which credential to add in the agent settings.
 60  
 61  ## The Skill System
 62  
 63  Skills are markdown files that teach agents how to use tools, APIs, and workflows. They are documentation, not executable code.
 64  
 65  ### Loading Skills
 66  
 67  ```json
 68  { "tool": "skills", "action": "list" }
 69  { "tool": "skills", "action": "read", "name": "tools/files" }
 70  { "tool": "skills", "action": "search", "query": "github pr" }
 71  ```
 72  
 73  ### Skill Locations
 74  
 75  - `skills/` -- built-in skills shipped with SwarmClaw
 76  - `data/skills/` -- user-created skills added at runtime
 77  
 78  ### When to Load Skills
 79  
 80  - Before using a tool you're unfamiliar with
 81  - When a task involves an API or workflow you haven't used before
 82  - When the user asks you to do something and you're unsure of the best approach
 83  
 84  ## Agent Capabilities
 85  
 86  ### Memory
 87  
 88  Agents have persistent memory across sessions:
 89  
 90  - **Working memory** (session-scoped): scratch notes, intermediate results
 91  - **Durable memory** (cross-session): user preferences, project facts, decisions
 92  - Memories are automatically surfaced in context when relevant
 93  - Store important learnings proactively -- don't wait to be asked
 94  
 95  ### Dreaming
 96  
 97  Agents with dreaming enabled automatically consolidate memories during idle periods. You can also trigger a dream manually:
 98  
 99  #### Check dream status
100  ```json
101  { "tool": "memory", "action": "list", "category": "dream_reflection" }
102  ```
103  
104  #### Manual dream trigger
105  Use the platform API to trigger a dream cycle:
106  ```json
107  { "tool": "execute", "command": "curl -s -X POST http://localhost:3456/api/memory/dream -H 'Content-Type: application/json' -d '{\"agentId\":\"YOUR_AGENT_ID\"}'" }
108  ```
109  
110  Dream cycles produce `dream_reflection` and `consolidated_insight` memories that help maintain a clean, coherent memory store over time.
111  
112  ### Delegation
113  
114  Agents can delegate work to other agents:
115  
116  - **delegate**: route a task to a specific agent and wait for the result
117  - **spawn**: create a subagent that runs independently (fire-and-forget or session-based)
118  - Use `agents.list` to discover available agents and their specializations
119  
120  ### Connectors
121  
122  Agents can communicate through external platforms:
123  
124  - Discord, Slack, Telegram, and custom webhooks
125  - Messages sent via `platform` tool with `communicate.send_message`
126  - Inbound messages from connectors trigger agent sessions automatically
127  
128  ### MCP Servers
129  
130  Agents can also use tools served by external Model Context Protocol servers:
131  
132  - Register MCP servers under **MCP Servers** in the UI (stdio / sse / streamable-http transports supported).
133  - Quick-setup presets include **SwarmVault** (local-first knowledge vault) and **SwarmDock** (agent marketplace — browse tasks, bid, submit work, earn USDC). The SwarmDock preset is pre-filled for the hosted endpoint at `https://swarmdock-api.onrender.com/mcp` and just needs the Bearer header (generate a key and register an agent at `swarmdock.ai/mcp/connect`). See `docs/mcp-servers.md` for the full workflow.
134  - Once attached to an agent, MCP tools appear alongside the built-in tools at execution time.
135  
136  ## Workspace Conventions
137  
138  - The workspace root is the agent's working directory
139  - File paths in tool calls are relative to the workspace root
140  - `/workspace/...` paths are resolved to the workspace root automatically
141  - The `$WORKSPACE` env var points to the workspace root in execute tool runs
142  
143  ## Best Practices
144  
145  1. **Load skills before unfamiliar operations.** A 30-second skill read prevents minutes of trial and error.
146  
147  2. **Use the right tool for the job.** Don't use `execute` with `echo > file.txt` when `files` write action is cleaner. Don't use `browser` when `curl` in `execute` suffices.
148  
149  3. **Store important context in memory.** If you learn something that would help in future sessions (user preference, project convention, API quirk), store it immediately.
150  
151  4. **Ask rather than guess.** When genuinely uncertain about user intent, use `communicate.ask_human`. A brief clarification is better than wasted work on the wrong approach.
152  
153  5. **Delegate when appropriate.** If another agent is better suited for a subtask, delegate. Check `agents.list` to know what's available.
154  
155  6. **Be explicit about what you're doing.** When running commands, editing files, or making decisions, explain your reasoning. Transparency builds trust.
156  
157  7. **Respect file access boundaries.** Stay within the workspace unless the agent has machine-scope access. Never write to system directories.
158  
159  8. **Handle errors gracefully.** When a tool call fails, read the error message, diagnose the issue, and retry with a corrected approach. Don't repeat the same failing call.