# Swarmclaw

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

- Skill: `swarmclawai/swarmclaw-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add swarmclawai/swarmclaw-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swarmclawai/swarmclaw-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: swarmclawai (https://skillmd.com/u/swarmclawai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swarmclawai/swarmclaw-2

---


# SwarmClaw Platform

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.

Website: https://swarmclaw.ai
Docs: https://swarmclaw.ai/docs
GitHub: https://github.com/swarmclawai/swarmclaw
npm: `npm install -g swarmclaw`

## The 6 Primitive Tools

Every agent has access to these core tools. They cover the full range of agent capabilities.

| Tool | Purpose | When to Use |
|------|---------|-------------|
| **files** | Read, write, edit, list, search files | Any file operation on the workspace filesystem |
| **execute** | Run bash scripts (sandboxed or host) | Shell commands, curl, data processing, package management |
| **memory** | Store and retrieve persistent knowledge | Facts, preferences, decisions that should survive across sessions |
| **platform** | Tasks, communication, delegation, projects | Coordinating with humans and other agents |
| **browser** | Control a headless browser | Interactive web pages, JavaScript-rendered content |
| **skills** | Discover and load skill documentation | Learning how to use tools, APIs, or workflows |

### Tool Selection Guide

| Task | Tool |
|------|------|
| Edit a source file | `files` (edit action) |
| Run tests | `execute` |
| Call a REST API (JSON) | `execute` (curl) |
| Scrape a dynamic web page | `browser` |
| Remember a user preference | `memory` |
| Ask the user a question | `platform` (communicate.ask_human) |
| Send a Slack message | `platform` (communicate.send_message) |
| Hand off work to another agent | `platform` (communicate.delegate) |
| Find out how a tool works | `skills` (read action) |

## Credentials

Credentials are configured per agent in the SwarmClaw UI. They are:

- **Injected as environment variables** into `execute` tool runs (e.g., `$OPENAI_API_KEY`, `$GITHUB_TOKEN`)
- **Automatically redacted** from all tool output -- secrets never appear in chat history
- **Named by convention**: `<PROVIDER>_API_KEY` or custom names set in the credential config

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.

## The Skill System

Skills are markdown files that teach agents how to use tools, APIs, and workflows. They are documentation, not executable code.

### Loading Skills

```json
{ "tool": "skills", "action": "list" }
{ "tool": "skills", "action": "read", "name": "tools/files" }
{ "tool": "skills", "action": "search", "query": "github pr" }
```

### Skill Locations

- `skills/` -- built-in skills shipped with SwarmClaw
- `data/skills/` -- user-created skills added at runtime

### When to Load Skills

- Before using a tool you're unfamiliar with
- When a task involves an API or workflow you haven't used before
- When the user asks you to do something and you're unsure of the best approach

## Agent Capabilities

### Memory

Agents have persistent memory across sessions:

- **Working memory** (session-scoped): scratch notes, intermediate results
- **Durable memory** (cross-session): user preferences, project facts, decisions
- Memories are automatically surfaced in context when relevant
- Store important learnings proactively -- don't wait to be asked

### Dreaming

Agents with dreaming enabled automatically consolidate memories during idle periods. You can also trigger a dream manually:

#### Check dream status
```json
{ "tool": "memory", "action": "list", "category": "dream_reflection" }
```

#### Manual dream trigger
Use the platform API to trigger a dream cycle:
```json
{ "tool": "execute", "command": "curl -s -X POST http://localhost:3456/api/memory/dream -H 'Content-Type: application/json' -d '{\"agentId\":\"YOUR_AGENT_ID\"}'" }
```

Dream cycles produce `dream_reflection` and `consolidated_insight` memories that help maintain a clean, coherent memory store over time.

### Delegation

Agents can delegate work to other agents:

- **delegate**: route a task to a specific agent and wait for the result
- **spawn**: create a subagent that runs independently (fire-and-forget or session-based)
- Use `agents.list` to discover available agents and their specializations

### Connectors

Agents can communicate through external platforms:

- Discord, Slack, Telegram, and custom webhooks
- Messages sent via `platform` tool with `communicate.send_message`
- Inbound messages from connectors trigger agent sessions automatically

### MCP Servers

Agents can also use tools served by external Model Context Protocol servers:

- Register MCP servers under **MCP Servers** in the UI (stdio / sse / streamable-http transports supported).
- 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.
- Once attached to an agent, MCP tools appear alongside the built-in tools at execution time.

## Workspace Conventions

- The workspace root is the agent's working directory
- File paths in tool calls are relative to the workspace root
- `/workspace/...` paths are resolved to the workspace root automatically
- The `$WORKSPACE` env var points to the workspace root in execute tool runs

## Best Practices

1. **Load skills before unfamiliar operations.** A 30-second skill read prevents minutes of trial and error.

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.

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.

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.

5. **Delegate when appropriate.** If another agent is better suited for a subtask, delegate. Check `agents.list` to know what's available.

6. **Be explicit about what you're doing.** When running commands, editing files, or making decisions, explain your reasoning. Transparency builds trust.

7. **Respect file access boundaries.** Stay within the workspace unless the agent has machine-scope access. Never write to system directories.

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.