ai-workflow-skill/skills/inbox/SKILL.md

name, description

name	description
inbox	Durable agent-to-agent coordination through a bundled inbox CLI. Use when an agent needs to fetch work, claim a thread, report progress, ask blocked questions, wait for replies, inspect thread history, or return done/fail results through a SQLite-backed inbox instead of ad hoc chat.

Inbox

Use the bundled ./assets/inbox CLI to communicate through a durable SQLite-backed inbox.

Quick Start

• Invoke ./assets/inbox relative to this skill directory.
• Pass --db explicitly for every command.
• Prefer --json whenever another agent or script will read the output.
• Run init before first use on a new database path.

Rules

• Treat fetch as discovery only; only claim grants ownership.
• Do not start work without a valid lease.
• Use update --status in_progress for progress and update --status blocked for precise questions.
• Prefer wait-reply over manual sleep loops when blocked.
• Use done for terminal success and fail for terminal failure.
• Keep scheduling and dependency decisions out of this layer; those belong to orch.

Typical Commands

./assets/inbox --db ./coord.db --json init
./assets/inbox --db ./coord.db --json fetch --agent backend-worker --status pending
./assets/inbox --db ./coord.db --json claim --agent backend-worker --thread thr_123 --lease-seconds 900
./assets/inbox --db ./coord.db --json update --agent backend-worker --thread thr_123 --status in_progress --summary "Implementing post CRUD routes"
./assets/inbox --db ./coord.db --json update --agent backend-worker --thread thr_123 --status blocked --summary "Need auth decision" --payload-json '{"question":"Should admin auth use email/password in MVP?"}'
./assets/inbox --db ./coord.db --json wait-reply --agent backend-worker --thread thr_123 --after-event 51 --timeout-seconds 1800
./assets/inbox --db ./coord.db --json reply --from leader --to backend-worker --thread thr_123 --summary "Use email/password for MVP" --body "Use a simple credential flow for the first iteration."
./assets/inbox --db ./coord.db --json done --agent backend-worker --thread thr_123 --summary "Post CRUD implemented" --body-file result.md

Command Map

• init: initialize schema and pragmas on a database path
• send: create a new thread or append a message
• fetch: list candidate threads for an agent without claiming them
• claim: acquire a lease on a thread
• renew: extend an active lease
• update: send progress or blocked updates
• reply: send an answer, control message, or follow-up inside a thread
• done: mark a thread complete with final result data
• fail: mark a thread failed with failure details
• cancel: cancel a thread
• list: list threads by filters
• show: inspect thread state and message history
• watch: block until matching thread activity arrives
• wait-reply: block until a reply arrives for a specific thread

Notes

• body-file and artifact-heavy flows are supported; prefer them over long inline strings when sending reports or patches.
• fetch --unread and show --mark-read depend on per-agent read cursors.
• If the bundled binary cannot execute on the current host, stop and report the compatibility issue instead of guessing a replacement path or workflow.