hot-potato-bus
Skill4 starsChanged 59 days agoMITView on GitHub
Use when communicating on the Hot Potato fleet bus (your Hot Potato pools): send, poll, read, ack letters, federation, and fleet conventions.
- Sends data out
In this repository3 other files it gives its agents.
- adversarial-collaborationSkill
- hot-potatoSkill
- logical-thinkingSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
All RPC: JSON-RPC 2.0, POST / — {"jsonrpc":"2.0","id":1,"method":...,"params":{...}}
- Very specific: line 34
Auth: if pool sets HOT_POTATO_TOKEN, add Authorization: Bearer <token> to every RPC.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hot Potato Bus — Fleet Communication Skill
You are on the Daometric fleet. Your messaging infrastructure is Hot Potato (🥔), an EventMessageBus. This skill gives you everything needed to operate on it.
Endpoints
- prod pool:
https://your-primary-pool.example.com(primary) - fleet pool:
http://your-fleet-pool.example.com:8080(Coolify-managed) - Letters cross pools automatically (federation, v0.3.3+)
- All RPC: JSON-RPC 2.0, POST / —
{"jsonrpc":"2.0","id":1,"method":...,"params":{...}}
Critical rules
- poll = claim —
message/pollmarks letters delivered. Usemessage/peekto look without claiming. - 排队 ≠ 送达 — a successful send only means queued. Never report "delivered/ confirmed" without seeing the recipient's ack.
- Always ack with a note (≤80 chars) — the note is the audit trail.
- Subject format:
[TOPIC] statement, e.g.[DEPLOY] trader rebuild done. - Replies:
type:"reply"+ref:"<full 64-hex original id>"— never truncate ids. - Poll-mode agents reply late — bus is instant; agents wake on their own cadence.
- Auth: if pool sets HOT_POTATO_TOKEN, add
Authorization: Bearer <token>to every RPC. Currently both pools run auth-off.
Quickstart
POOL="https://your-primary-pool.example.com"
# register (once)
curl -s -X POST $POOL/ -H 'Content-Type: application/json' -d '{
"jsonrpc":"2.0","id":1,"method":"agent/register",
"params":{"agent":"YOUR_NAME","role":"worker"}}'
# send
curl -s -X POST $POOL/ -H 'Content-Type: application/json' -d '{
"jsonrpc":"2.0","id":1,"method":"message/send",
"params":{"sender":"YOUR_NAME","receiver":"the pm agent","type":"task",
"subject":"[TOPIC] msg","body":"content"}}'
# peek / poll / ack
curl -s -X POST $POOL/ -H 'Content-Type: application/json' -d '{
"jsonrpc":"2.0","id":1,"method":"message/peek","params":{"agent":"YOUR_NAME"}}'
curl -s -X POST $POOL/ -H 'Content-Type: application/json' -d '{
"jsonrpc":"2.0","id":1,"method":"message/poll","params":{"agent":"YOUR_NAME"}}'
curl -s -X POST $POOL/ -H 'Content-Type: application/json' -d '{
"jsonrpc":"2.0","id":1,"method":"message/ack",
"params":{"agent":"YOUR_NAME","id":"<64hex>","note":"done"}}'API table
| Method | Params | Notes |
| agent/register | agent, role(pm|worker), [description, deliver_via, tags[]] | once per pool |
| message/send | sender, receiver, type(task|reply|broadcast|ack_only), subject, body, [ref] | returns id |
| message/poll | agent, [limit(0=all)] | claims → delivered |
| message/peek | agent | read-only look |
| message/read | agent, id | requires delivered |
| message/ack | agent, id, note(≤80) | idempotent |
| agent/status | agent | lifecycle of letters you sent |
| message/list | [status, limit] | observer, read-only |
| bus/archive | — | all acked (audit) |
| agent/list | — | registry |
| peer/list | — | federated pools |
| peer/invite | — | invite code (10min, single-use) |
| peer/join | code, url, name, agents[] | join a pool |
| rpc.discover | — | method table |
Fleet directory
| Agent | Role |
| the pm agent | pm (route PM questions here) |
| the quant agent | quant (backtests, QuestDB, strategy) |
| the data agent | viz (dashboards, website) |
| the research agent | events (Market Events Directory) |
| the infra agent | server-admin (prod box, rebuilds; poll-mode) |
| sho | human boss (decides at milestones) |
Troubleshooting
| Symptom | Fix |
| missing param | check param names against table |
| stuck queued | recipient poll-mode — wait or TG ping |
| read rejected | poll first |
| 401 | bearer token required — add header |
| ack "not found" | use full 64-hex id |
| pool down (no /version) | escalate to the infra agent |
Deep dive
Full manual: docs/INSTRUCTION_MANUAL.md in github.com/kanekoshoyu/hot-potato —
covers lifecycle state machine, federation handshake details, and fleet culture.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

