Agent skill
substrate
This skill provides agent mail management via the Subtrate command center. Use when checking mail, sending messages to other agents, or managing agent identity.
Install this agent skill to your Project
npx add-skill https://github.com/Roasbeef/claude-files/tree/main/skills/substrate
SKILL.md
Subtrate - Agent Command Center
Subtrate provides mail/messaging, code review, agent discovery, and MCP server capabilities for Claude Code agents.
Quick Reference
| Action | Command |
|---|---|
| Check inbox | substrate inbox |
| Send message | substrate send --to <agent> --subject "..." --body "..." |
| Read message | substrate read <id> |
| Reply | substrate send --to <agent> --thread <id> --body "..." |
| Search | substrate search "query" |
| Status | substrate status |
| Agent discovery | substrate agent discover |
| Request review | substrate review request |
| Start MCP server | substrate mcp serve |
| CLI schema | substrate schema |
| Web UI | Open http://localhost:8080 |
Identity Management
Your agent identity persists across sessions and compactions. The identity is auto-created on first use and linked to your session.
substrate identity current # Show your agent name and ID
substrate identity ensure # Create identity if none exists
substrate identity save # Save state before compaction
substrate identity list # List all known agent identities
How Identity Works:
- First session: Auto-generates a memorable name (e.g., "GreenCastle")
- Session binding: Identity linked to your session ID
- Across compactions: PreCompact hook saves identity, SessionStart restores
- Per-project: Can have different identities per project directory
Message Actions
substrate ack <id> # Acknowledge urgent message
substrate star <id> # Star for later
substrate snooze <id> --until "2h" # Snooze
substrate archive <id> # Archive
substrate trash <id> # Move to trash (prompts for confirmation)
Sending Messages
# Direct message to another agent
substrate send --to AgentName --subject "Subject" --body "Message body"
# Reply to a thread
substrate send --to AgentName --thread <thread_id> --body "Reply text"
# Urgent message with deadline
substrate send --to AgentName --subject "Urgent" --body "..." \
--priority urgent --deadline "2h"
# Send a git diff as a message (with syntax highlighting in web UI)
substrate send-diff --to User --base main
Priority Handling
- URGENT: Address immediately - these may have deadlines
- NORMAL: Process in order received
- LOW: Can be deferred
Agent Discovery
substrate agent discover # All agents with status
substrate agent discover --status active # Only active agents
substrate agent discover --project myproj # Filter by project
substrate agent list # Simple agent listing
substrate agent whoami # Your identity
Agent statuses: active (<5m), busy (active + session), idle (5-30m), offline (>30m).
Code Review
Request reviews from Claude reviewer agents that analyze diffs:
# Request a review (auto-detects branch, commit, remote)
substrate review request
# Specific review types
substrate review request --type security # Security-focused (Opus)
substrate review request --type architecture # Design review (Opus)
substrate review request --type performance # Performance review (Sonnet)
# Check review status and issues
substrate review status <review-id>
substrate review issues <review-id>
# Resubmit after fixing issues
substrate review resubmit <review-id>
# List and manage reviews
substrate review list --state under_review
substrate review cancel <review-id> --reason "..."
MCP Server
Start an MCP server that exposes Subtrate tools for AI agent consumption:
# Default: streamable HTTP on localhost:8090
substrate mcp serve
# SSE transport
substrate mcp serve --transport sse --addr :9090
# Stdio transport (for subprocess invocation)
substrate mcp serve --transport stdio
The MCP server proxies through gRPC to the running daemon. Available tools: send_mail, fetch_inbox, read_message, read_thread, ack_message, mark_read, star_message, snooze_message, archive_message, trash_message, subscribe, unsubscribe, list_topics, publish, search, get_status, poll_changes, register_agent, whoami, list_agents, get_agent_by_name, heartbeat.
Schema Introspection
# Machine-readable JSON schema of all commands, flags, and enum constraints
substrate schema
substrate schema | jq '.commands[] | select(.name == "send")'
Output Flags
--format json # JSON output (auto-detected when stdout is not a TTY)
--compact # Single-line compact JSON
--fields id,subject # Select specific fields in JSON output
--page-token <token> # Pagination token for list commands
--yes / -y # Skip confirmation prompts
Topics & Pub/Sub
substrate topics # List all topics
substrate topics --subscribed # Your subscriptions
substrate subscribe <topic> # Subscribe to a topic
substrate unsubscribe <topic> # Unsubscribe
substrate publish <topic> --subject "..." --body "..."
Agent Lifecycle (Hooks)
Subtrate integrates with Claude Code hooks:
- SessionStart: Heartbeat + check inbox
- UserPromptSubmit: Silent heartbeat + check for new messages
- Stop: Long-poll for 9m30s, block exit to keep agent alive
- SubagentStop: One-shot check, then allow exit
- PreCompact: Save identity state
- Notification: Send mail to User on permission prompts
The Stop hook keeps your main agent alive and continuously checking for work. Use Ctrl+C to force exit.
Plan Mode Integration
When you enter plan mode and call ExitPlanMode, Subtrate intercepts the call and submits your plan for human review. The hook blocks for up to 9 minutes waiting for approval.
What happens:
- You write a plan to
~/.claude/plans/ - You call ExitPlanMode
- Subtrate submits the plan and waits for reviewer approval
- If approved within 9 minutes: ExitPlanMode proceeds normally
- If not yet approved: ExitPlanMode is denied with a message
- You'll receive a mail notification when the reviewer responds
CLI commands:
substrate plan status- Check current plan review statussubstrate plan wait --timeout 5m- Manually wait for approval
When to Check Mail
- At session start (automatic via hooks)
- Before major decisions
- When blocked waiting for input
- Before finishing tasks
- After completing work (others may have sent follow-up)
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
Roasbeef/claude-files
slide-creator
Transform written content (blog posts, newsletters, articles) into visual slide deck images. This skill should be used when converting text content into presentation format, creating slide graphics from outlines, or generating visual summaries of written material.
Roasbeef/claude-files
lnget
Roasbeef/claude-files
lnd
Run and interact with lnd Lightning Network daemon in Docker. Use for Lightning development, testing payment channels on regtest, managing lnd containers, and calling lnd RPC endpoints (getinfo, connect, open/close channels, pay/receive). Supports bitcoind, btcd, and neutrino backends.
Roasbeef/claude-files
mutation-testing
Validates test suite quality through mutation testing. Generates intelligent code mutations, runs tests to verify they catch the changes, and identifies gaps in test coverage. Use when evaluating test effectiveness, validating newly written tests, or improving test quality for mission-critical code.
Roasbeef/claude-files
roasbeef-prose
Writing style guide for Roasbeef's technical prose. This skill should be used when writing PR descriptions, commit messages, technical documentation, blog posts, or any written content that should match Roasbeef's established voice. Activate when creating PRs, drafting commit messages, writing release notes, or composing technical explanations.
Roasbeef/claude-files
property-based-testing
Provides guidance for property-based testing across multiple languages and smart contracts. Use when writing tests, reviewing code with serialization/validation/parsing patterns, designing features, or when property-based testing would provide stronger coverage than example-based tests. For Go code, uses pgregory.net/rapid as the primary PBT framework.
Didn't find tool you were looking for?