{"skill":{"slug":"agent-swarm-network","displayName":"Agent Swarm Network","summary":"Agent communication protocol skill. Provides: inter-agent messaging, context snapshot/restore, event-driven collaboration, model dispatch notifications, sub-...","description":"---\nname: Agent Swarm Network\nversion: 1.0.6\ndescription: >\n  Agent communication protocol skill. Provides: inter-agent messaging, context\n  snapshot/restore, event-driven collaboration, model dispatch notifications,\n  sub-agent management, task routing, file transfer, and network diagnostics.\n  Invoke this Skill when cross-session context persistence, multi-agent coordination,\n  or context overflow handling is needed.\n  Built on top of Pilot Protocol (https://github.com/TeoSlayer/pilotprotocol).\n---\n\n# Agent Swarm Network — Agent Communication Skill\n\n> A unified communication backbone for every AI tool in the OpenClaw ecosystem\n> (OpenClaw / Antigravity / Codex).\n>\n> Analogy: This network = the Agent's nervous system. OpenClaw = the Agent's brain.\n\n## Acknowledgments\n\nThis Skill is built on top of [Pilot Protocol](https://github.com/TeoSlayer/pilotprotocol) by [@TeoSlayer](https://github.com/TeoSlayer). Pilot Protocol provides the core daemon, encrypted tunnels, NAT traversal, and peer-to-peer addressing that this Skill leverages. Huge thanks to the Pilot Protocol team for building the Internet of Agents.\n\n---\n\n## Permissions & Privacy\n\n**This Skill executes local CLI commands and writes files to the `~/.pilot/` directory.** Full transparency:\n\n| Permission | What | Why |\n|------------|------|-----|\n| **CLI Exec** | `~/.pilot/bin/pilotctl` | All agent operations go through this binary |\n| **File Write** | `~/.pilot/inbox/` | Context snapshots and incoming messages land here |\n| **File Write** | `~/.pilot/received/` | Received files from peer agents |\n| **File Read** | `~/.pilot/inbox/` | Reading snapshots for context restoration |\n| **File Read** | `~/.pilot/received/` | Reading transferred files |\n| **Network** | Local Unix socket | Daemon communication (localhost only) |\n| **Network** | UDP tunnels (encrypted) | Agent-to-agent communication (AES-256-GCM) |\n| **Script Exec** | `~/.pilot/context-snapshot.sh` | Context snapshot helper script |\n| **Script Exec** | `~/.pilot/pilot-publish.sh` | Event publishing helper script |\n| **Process** | Daemon lifecycle | Start/stop/status of the pilotctl daemon |\n\n> **Privacy Note:** All inter-agent traffic is encrypted end-to-end using X25519 key exchange + AES-256-GCM. Agents are private by default and require mutual trust handshake before communication. No data passes through relay servers. The rendezvous registry defaults to localhost (`127.0.0.1:9000`) — no peer-discovery metadata leaves the machine unless you explicitly change `registry_url` to a remote address. Snapshots are unencrypted JSON; you must secure the `~/.pilot/` directory (`chmod 700`).\n\n---\n\n## Prerequisites\n\n| Tool | Purpose | Required? |\n|------|---------|-----------|\n| **Pilot Protocol** | Core daemon + CLI (`pilotctl`) | ✅ Required |\n| **OpenClaw** | Skill host + Agent orchestration | ✅ Required |\n\n## Configuration\n\nEdit `config.json` after installation:\n\n```json\n{\n  \"pilotctl_path\": \"~/.pilot/bin/pilotctl\",\n  \"daemon_start_script\": \"~/.pilot/start-local.sh\",\n  \"snapshot_script\": \"~/.pilot/context-snapshot.sh\",\n  \"publish_script\": \"~/.pilot/pilot-publish.sh\",\n  \"inbox_path\": \"~/.pilot/inbox/\",\n  \"received_path\": \"~/.pilot/received/\",\n  \"agent_hostname\": \"keke-agent\"\n}\n```\n\n| Field | Description | Default |\n|-------|-------------|---------|\n| `pilotctl_path` | Path to the pilotctl binary | `~/.pilot/bin/pilotctl` |\n| `daemon_start_script` | Script to start the daemon | `~/.pilot/start-local.sh` |\n| `snapshot_script` | Context snapshot helper script | `~/.pilot/context-snapshot.sh` |\n| `publish_script` | Event publish helper script | `~/.pilot/pilot-publish.sh` |\n| `inbox_path` | Directory for incoming messages/snapshots | `~/.pilot/inbox/` |\n| `received_path` | Directory for received files | `~/.pilot/received/` |\n| `agent_hostname` | This agent's hostname on the Pilot network | `keke-agent` |\n\n### First-time Setup\n\n1. **Install Pilot Protocol securely:** We strongly recommend **building from source** to eliminate supply-chain risk. Clone `https://github.com/TeoSlayer/pilotprotocol`, audit the source, compile via `go build`, and place the binary at `~/.pilot/bin/pilotctl`.\n2. Secure your directories: `chmod 700 ~/.pilot`\n3. Start the daemon: `~/.pilot/start-local.sh`\n4. Verify: `~/.pilot/bin/pilotctl --json daemon status`\n\n---\n\n## Global Rules\n\n1. All `pilotctl` commands use the full path: `~/.pilot/bin/pilotctl`\n2. Always append the `--json` flag for structured output\n3. Check the returned `status` field: `ok` = success, `error` = failure\n4. On failure, read the `hint` field for remediation guidance\n\n---\n\n## ⚠️ Single-Node Mode (Current State)\n\nCurrently running with only one node (`keke-agent`). **Cannot send network messages to self** (publish/send-message will return `connection_failed`).\n\n### Single-Node Workarounds\n\n| Operation | Multi-node Command | Single-node Alternative |\n|-----------|-------------------|------------------------|\n| Publish event | `pilotctl publish keke-agent topic --data ...` | `~/.pilot/pilot-publish.sh topic '{\"key\":\"val\"}'` |\n| Send to inbox | `pilotctl send-message keke-agent --data ...` | Write file directly to `~/.pilot/inbox/` |\n| Context snapshot | `pilotctl send-message ...` | `~/.pilot/context-snapshot.sh` |\n| Read inbox | `pilotctl inbox` → read `~/.pilot/inbox/` | Same (read directory directly) |\n| Check status | `pilotctl info` | ✅ Works normally |\n| Set tags | `pilotctl set-tags ...` | ✅ Works normally |\n\nWhen a second node joins (e.g., VPS or another Mac), network commands will activate automatically.\n\n---\n\n## Capability 1: Context Snapshot & Restore (Highest Priority)\n\n### 1.1 Save Context Snapshot\n\nWhen a session ends, compaction triggers, or manual request is made, save critical context:\n\n```bash\n# Using the snapshot script (works in both single-node and multi-node)\n~/.pilot/context-snapshot.sh SESSION_ID \"Key summary of current context\"\n\n# Or manually write to inbox\necho '{\"type\":\"context_snapshot\",\"session_id\":\"ID\",\"summary\":\"Summary\"}' > ~/.pilot/inbox/snapshot_$(date +%Y%m%d_%H%M%S).json\n```\n\n### 1.2 Restore Context\n\nWhen a new session starts, read the previous session's snapshot:\n\n```bash\n~/.pilot/bin/pilotctl --json inbox\n```\n\nReturns a `messages` array sorted by `received_at`. Read the most recent `context_snapshot` type message.\n\n### 1.3 Context Overflow Protocol\n\nWhen context usage exceeds 80%:\n\n```\nStep 1: Extract critical information from current context\nStep 2: Serialize as JSON snapshot\nStep 3: pilotctl send-message keke-agent --data \"{snapshot}\" --type json\nStep 4: pilotctl publish keke-agent context.overflow --data \"overflow at TOKEN_COUNT tokens\"\nStep 5: Suggest user starts a new session\nStep 6: New session automatically restores from inbox\n```\n\n---\n\n## Capability 2: Event-Driven Collaboration\n\n### 2.1 Publish Events\n\nWhen significant events occur, use `pilot-publish.sh` (automatically handles single-node/multi-node):\n\n```bash\n# Model switch\n~/.pilot/pilot-publish.sh model.switch '{\"from\":\"flash-lite\",\"to\":\"opus-4.6\",\"reason\":\"strategic analysis\"}'\n\n# Task completion\n~/.pilot/pilot-publish.sh task.complete '{\"task\":\"intelligence_ingestion\",\"source\":\"twitter\"}'\n\n# Context compaction\n~/.pilot/pilot-publish.sh context.compaction '{\"before_tokens\":150000,\"after_tokens\":30000}'\n\n# Error alert\n~/.pilot/pilot-publish.sh error.alert '{\"type\":\"model_402\",\"model\":\"gemini\",\"action\":\"fallback\"}'\n\n# Intelligence ingested\n~/.pilot/pilot-publish.sh intel.ingested '{\"source\":\"url\",\"title\":\"Article Title\",\"category\":\"infra\"}'\n```\n\n### 2.2 Subscribe to Events\n\nListen for specific topics (used by sub-agents or external monitors):\n\n```bash\n# Listen to all events\n~/.pilot/bin/pilotctl --json subscribe keke-agent \"*\" --timeout 60s\n\n# Listen only to model switches\n~/.pilot/bin/pilotctl --json subscribe keke-agent model.switch --count 1\n\n# Listen for error alerts\n~/.pilot/bin/pilotctl --json subscribe keke-agent error.* --timeout 300s\n```\n\n### 2.3 Standard Event Topics\n\n| Topic | Trigger | Data Schema |\n|-------|---------|-------------|\n| `context.snapshot` | Session end / manual save | `{session_id, summary, key_decisions}` |\n| `context.overflow` | Token usage > 80% | `{token_count, threshold}` |\n| `context.compaction` | Compaction triggered | `{before_tokens, after_tokens}` |\n| `model.switch` | Model changed | `{from, to, reason}` |\n| `model.error` | Model failure | `{model, error, fallback}` |\n| `task.start` | Task initiated | `{task, type, model}` |\n| `task.complete` | Task finished | `{task, result_summary}` |\n| `task.error` | Task failed | `{task, error, retry}` |\n| `intel.ingested` | Information ingested | `{source, title, category, value}` |\n| `error.alert` | Error notification | `{type, details, action}` |\n| `agent.spawn` | Sub-agent created | `{hostname, purpose, model}` |\n| `agent.exit` | Sub-agent exited | `{hostname, reason, result}` |\n\n---\n\n## Capability 3: Sub-Agent Management\n\n### 3.1 Naming Convention\n\n```\nPrimary agent:    keke-agent\nSub-agents:       keke-sub-{purpose}  (e.g., keke-sub-code, keke-sub-writer)\nNested sub:       keke-sub-{purpose}-{n}\n```\n\n### 3.2 Spawning Sub-Agents\n\nWhen OpenClaw needs to create a sub-agent for overflow tasks:\n\n```bash\n# Publish agent spawn event\n~/.pilot/bin/pilotctl --json publish keke-agent agent.spawn \\\n  --data '{\"hostname\":\"keke-sub-code\",\"purpose\":\"code refactoring\",\"model\":\"sonnet-4.6\"}'\n```\n\n### 3.3 Collecting Sub-Agent Results\n\n```bash\n# Sub-agent sends results via Data Exchange\n~/.pilot/bin/pilotctl --json send-message keke-agent \\\n  --data '{\"type\":\"sub_agent_result\",\"from\":\"keke-sub-code\",\"result\":\"refactoring complete\",\"files_changed\":3}' \\\n  --type json\n\n# Primary agent checks results\n~/.pilot/bin/pilotctl --json inbox\n```\n\n---\n\n## Capability 4: Task Routing\n\n### 4.1 Route by Tags\n\nAssign capability tags to different agents:\n\n```bash\n# Tag self\n~/.pilot/bin/pilotctl --json set-tags orchestrator chinese fast\n```\n\nTag conventions:\n\n| Tag | Meaning | Best Fit Agent |\n|-----|---------|---------------|\n| `orchestrator` | Scheduling & dispatch | OpenClaw primary agent |\n| `deep-reasoning` | Deep reasoning tasks | Antigravity (Opus) |\n| `code-gen` | Code generation | Codex (Sonnet) |\n| `local-inference` | Local model inference | LM Studio (Qwen) |\n| `fast` | Fast responses | Flash Lite instances |\n| `chinese` | Chinese language tasks | Qwen / Chinese-optimized models |\n\n### 4.2 Find the Best Agent\n\n```bash\n~/.pilot/bin/pilotctl --json peers --search \"code-gen\"\n```\n\n---\n\n## Capability 5: Model Dispatch Notifications\n\n### 5.1 Publish Model Switch Events\n\nEvery model switch gets logged to the event stream:\n\n```bash\n~/.pilot/bin/pilotctl --json publish keke-agent model.switch \\\n  --data '{\"from\":\"CURRENT_MODEL\",\"to\":\"NEW_MODEL\",\"reason\":\"reason\",\"timestamp\":\"ISO8601\"}'\n```\n\n### 5.2 Model Fallback Chain\n\nOn model failure, automatically publish degradation events:\n\n```bash\n~/.pilot/bin/pilotctl --json publish keke-agent model.error \\\n  --data '{\"model\":\"gemini-3-flash\",\"error\":\"402 quota exceeded\",\"fallback\":\"minimax-m2.5\"}'\n```\n\n---\n\n## Capability 6: File Transfer\n\n### 6.1 Send File\n\n```bash\n~/.pilot/bin/pilotctl --json send-file keke-agent /path/to/file\n```\n\nFiles are saved to `~/.pilot/received/`.\n\n### 6.2 View Received Files\n\n```bash\n~/.pilot/bin/pilotctl --json received\n```\n\n### 6.3 Use Cases\n\n- Transfer context snapshot files\n- Transfer code diffs\n- Transfer analysis reports\n- Share configuration across agents\n\n---\n\n## Capability 7: Network Diagnostics\n\n### 7.1 Health Checks\n\n```bash\n# Daemon status\n~/.pilot/bin/pilotctl --json daemon status\n\n# Agent info\n~/.pilot/bin/pilotctl --json info\n\n# Connection list\n~/.pilot/bin/pilotctl --json connections\n\n# Peer list\n~/.pilot/bin/pilotctl --json peers\n```\n\n### 7.2 Performance Testing\n\n```bash\n# Ping latency\n~/.pilot/bin/pilotctl --json ping keke-agent --count 3\n\n# Throughput benchmark\n~/.pilot/bin/pilotctl --json bench keke-agent 1\n```\n\n---\n\n## Capability 8: Gateway IP Bridging\n\n### 8.1 Map Agent to Local IP\n\n```bash\n# Gateway bridging on user-space ports (>1024) does NOT require root/sudo.\n~/.pilot/bin/pilotctl gateway start --ports 1234,8080 0:0000.0000.0001\n```\n\nOnce mapped, standard HTTP tools can be used:\n```bash\ncurl http://10.4.0.1:1234/v1/chat/completions  # Like calling LM Studio directly\n```\n\n### 8.2 Use Cases\n\n- Expose LM Studio through Gateway as a Pilot address\n- Unify all model endpoints under one entry point\n- Access agent services with standard HTTP tools\n\n---\n\n## Capability 9: Webhook Real-time Monitoring\n\n### 9.1 Set Up Webhook\n\n```bash\n~/.pilot/bin/pilotctl --json set-webhook http://localhost:8080/pilot-events\n```\n\n### 9.2 Event Types\n\nAll native daemon events are pushed to the webhook:\n- `node.registered` / `node.reregistered`\n- `conn.established` / `conn.fin` / `conn.rst`\n- `handshake.received` / `handshake.approved`\n- `message.received` / `file.received`\n- `pubsub.published` / `pubsub.subscribed`\n- `security.syn_rate_limited` / `security.nonce_replay`\n\n---\n\n## Standing Orders (Automation Rules)\n\n### Rule 1: Snapshot Before Session End\nAutomatically execute a context snapshot (Capability 1.1) before every session ends.\n\n### Rule 2: Critical Events Must Be Published\nThe following events must always be published to the Event Stream:\n- Model switches\n- Intelligence ingestion completions\n- Task completions/failures\n- Context compactions\n- Error alerts\n\n### Rule 3: Auto-Restore on New Session\nOn every new session start, check `pilotctl inbox` for the latest snapshot and restore context.\n\n### Rule 4: Daemon Heartbeat\nCheck daemon status every 30 minutes. Auto-restart on failure.\n\n---\n\n## Troubleshooting\n\n| Problem | Diagnostic Command | Solution |\n|---------|--------------------|----------|\n| Daemon not running | `pilotctl daemon status` | `~/.pilot/start-local.sh` |\n| Registry unreachable | `pilotctl info` (check peers) | Verify rendezvous server is running |\n| Messages not sending | `pilotctl connections` | Check trust state with target |\n| Inbox overflowing | `pilotctl inbox` | `pilotctl inbox --clear` |\n","tags":{"agent-coordination":"1.0.6","communication":"1.0.6","context-management":"1.0.6","latest":"1.0.6","p2p":"1.0.6"},"stats":{"comments":0,"downloads":955,"installsAllTime":36,"installsCurrent":1,"stars":0,"versions":7},"createdAt":1772119429394,"updatedAt":1779077356825},"latestVersion":{"version":"1.0.6","createdAt":1772160972564,"changelog":"Registry language fix: Removed all references to \"upstream registry operated by TeoSlayer\" across manifest.json, SKILL.md, README.md, and index.html. All text now states the registry defaults to localhost (127.0.0.1:9000) with zero external exposure.\nDependencies structure fix: Moved pilotctl and go into dependencies.binaries (the field ClawHub's parser actually reads). Removed orphaned required_binaries top-level key. This resolves the \"Required binaries: none\" mismatch.\nSupply chain: Source-only build instructions retained. No curl|bash anywhere.\nSnapshots: Data-at-Rest Vulnerability warning and chmod 700 mandate retained.","license":null},"metadata":null,"owner":{"handle":"sarahmirrand001-oss","userId":"s17eapcgn3tsvbsbk5ks616j75884v7n","displayName":"KELIHAO","image":"https://avatars.githubusercontent.com/u/259751141?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779962702335}}