# Publish

> This skill should be used when the user asks to "send message to agent X", "publish to topic", "broadcast to all agents", "notify other sessions", "tell agent Y that...", or needs to send inter-agent messages, hand off work, or broadcast notifications across hive sessions.

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

---


# Publish - Send Inter-Agent Messages

Send messages to other agents, broadcast to multiple sessions, or publish notifications to topic-based channels.

## When to Use

- Handing off work to another agent
- Notifying other sessions of events or status
- Broadcasting updates to multiple agents
- Sending results or data to waiting agents
- Coordinating distributed work across sessions

## How It Works

Messages are published to named topics. The sender is auto-detected from the current hive session context. Each message includes sender ID, timestamp, content, and topic(s).

Output: JSON confirmation line with status, resolved topics, and sender.

## Commands

### Publish with -m Flag (Recommended)

```bash
hive msg pub --topic <topic> -m "message content"
```

**Examples:**
```bash
# Send to specific agent's inbox
hive msg pub --topic agent.abc123.inbox -m "Task completed, ready for review"

# Send to multiple topics
hive msg pub -t agent.123.inbox -t agent.456.inbox -m "Important update"
```

### Publish from Stdin

```bash
echo "Status update" | hive msg pub --topic notifications
cat report.txt | hive msg pub --topic reports
```

### Publish from File

```bash
hive msg pub --topic agent.abc.inbox -f handoff-context.md
```

### Publish with Positional Argument

```bash
hive msg pub --topic <topic> "message content"
```

Note: Prefer `-m` over positional args to avoid flag collision with single-character messages.

### Broadcast with Wildcards

```bash
# Broadcast to all agent inboxes
hive msg pub -t "agent.*.inbox" -m "System maintenance in 5 minutes"
```

Wildcard `*` matches any characters within a segment. Topics are expanded at publish time.

## Message Sources

Only one source may be used per publish:
- `-m` / `--message` flag (recommended)
- Positional argument
- `-f` / `--file` flag
- Stdin (default when no other source)

An error is returned if multiple sources are provided.

## Topic Patterns

### Standard Inbox Format

Agent inboxes follow: `agent.<session-id>.inbox`

```bash
# Find session IDs
hive ls

# Send to specific agent
hive msg pub --topic agent.abc123.inbox -m "Message"
```

### Custom Topics

Create any topic name for specific use cases:

```bash
hive msg pub --topic deploy.started -m "Deployment initiated"
hive msg pub --topic build.events -m "Test suite running"
```

### Topic Naming Conventions

- `agent.<id>.inbox` - Direct messages to agents
- `<domain>.<event>` - Event notifications (build.started, test.failed)
- `<feature>.<channel>` - Feature-specific channels

Avoid generic names, special characters besides `.`, `-`, `_`.

## Common Workflows

### Hand Off Work

```bash
# Complete work and notify next agent
hive msg pub --topic agent.xyz789.inbox -m "Auth implementation complete. See PR #123. Tests passing."
```

### Notify Multiple Topics

```bash
hive msg pub \
  -t agent.abc.inbox \
  -t agent.xyz.inbox \
  -t coordinator.updates \
  -m "Feature X ready for review"
```

### Send Command Output

```bash
go test -v ./... | hive msg pub --topic test.results
```

### Override Sender ID

```bash
hive msg pub --topic test.channel --sender "custom-agent-id" -m "Test message"
```

## Additional Resources

For troubleshooting, advanced patterns, and coordination workflows, see:
- **`references/troubleshooting.md`** - Common issues and solutions

## Related Skills

- `/hive:inbox` - Check inbox for messages
- `/hive:wait` - Wait for messages with timeout
- `/hive:session-info` - Get session details and inbox topic