swarmclaw

Files (1)

• SKILL.md

SKILL.md (first lines)

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

From swarmclawai/swarmclaw, MIT.

More from swarmclawai/swarmclaw