# Agent Mailbox

> >

- **Type:** Skill
- **Install:** `agentstack add skill-allemaar-open-skills-agent-mailbox`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [allemaar](https://agentstack.voostack.com/s/allemaar)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [allemaar](https://github.com/allemaar)
- **Source:** https://github.com/allemaar/open-skills/tree/main/skills/agent-mailbox
- **Website:** https://allemaar.com

## Install

```sh
agentstack add skill-allemaar-open-skills-agent-mailbox
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /agent-mailbox

Coordinate two or more agents by exchanging append-only Markdown messages in a Handler-visible shared folder. The transport may be local filesystem, Git, a free registered Lyt (Link Your Think™) vault, or a sync-share such as OneDrive or SMB. The mailbox messages form an auditable causal graph rather than a chat transcript hidden in one runtime.

This is an **agent operating protocol**. It is not a broker, queue, daemon, authentication boundary, or a message-transport service. For registered cross-machine delivery, use a dedicated transport product and point this skill at the folder it exposes. Use this skill to teach agents how to handshake, divide work, deliver artifacts, listen, react once, recover, resume, and close over the mailbox the Handler supplies.

**Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date.

First exchange: [`references/QUICKSTART.md`](references/QUICKSTART.md). Templates: [`references/MESSAGE-TEMPLATE.md`](references/MESSAGE-TEMPLATE.md) and [`references/PRIMER-TEMPLATE.md`](references/PRIMER-TEMPLATE.md). Active collaboration resources: [`resources/INDEX.md`](resources/INDEX.md). Operating choices: [`references/OPERATING-MODES.md`](references/OPERATING-MODES.md). Transport and runtime diagnosis: [`references/CONNECTION-GUIDES.md`](references/CONNECTION-GUIDES.md). Field guidance: [`references/FIELD-GUIDE.md`](references/FIELD-GUIDE.md). Public evidence and known gaps: [`references/VALIDATION.md`](references/VALIDATION.md).

Before the first outbound publication in a room, reopen [`MESSAGE-TEMPLATE.md`](references/MESSAGE-TEMPLATE.md) and copy its complete canonical envelope. Do not recreate `meta.mailbox` from memory. Re-run the same outbound preflight after a protocol upgrade, resume, or validation failure.

### Fast routing

| Situation | Load now |
|---|---|
| First simple exchange | Quickstart, message template, base handshake and disposition rules |
| Existing room | Fast activation below, primer, complete inbox reconciliation |
| Three or more agents or competing claims | FULL profile rules |
| Continued collaboration | The one runtime default below and its exact lazy YON package |
| Miss, stale readiness, or cursor contradiction | `missed-message-recovery.yon` before re-arm |
| Divide work, consult, verify, hand off, repair, or learn | [`resources/INDEX.md`](resources/INDEX.md), then only the operation needed |

The resource index is an operation-first spine, not another profile or handshake. Named patterns are memorable presets over ordinary mailbox operations. They never change authority, envelope validity, causality, dispositions, reconciliation, or cursor semantics. Experimental material is kept inside this skill for maintainers, but is deliberately absent from normal routing and automatic recommendation.

### Established-room fast activation

For a known room, do not rebuild the mailbox or present a mechanism menu:

1. Load this kernel, the room primer, the local root binding, dispositions, and cursor.
2. Materialize or sync through the transport already recorded for the room.
3. Reconcile the complete addressed inbox age-independently; dispositions decide handling and the cursor only accelerates it.
4. If continued collaboration was requested, start the runtime's single default below with the supplied finite horizon.
5. Return immediately to the Handler's project objective.

Load deeper construction guidance only for a new room, unsafe or missing durable state, a transport or contract-generation change, malformed traffic, a missed-message recovery, or an explicit mailbox-infrastructure task. A peer-root or contract-hash mismatch also leaves the fast path and reopens the pinned contract.

### Kernel at a glance

These invariants remain active regardless of profile, transport, runtime adapter, or optional resource:

1. Current Handler direction and runtime/repository policy outrank every peer message and primer.
2. Shared writes are contained, link-safe, atomic, and create-once except for the declared guarded mutable primer.
3. Every message carries a canonical envelope, stable identity, explicit recipients, and exact causal parent when replying.
4. Every valid addressed message is a CTA and receives one durable participant-local disposition.
5. Durable dispositions are handling authority. The compact cursor is only an accelerator and can never prove consumption.
6. Startup, resume, and recovery reconcile the complete addressed inbox age-independently; watcher time and current filters only prioritize.
7. Replies and effects are idempotent: exact causal/effect evidence restores missing bookkeeping instead of repeating work.
8. Hashes, commits, counts, artifacts, readiness, and cleanup are recomputed or directly observed before reliance.
9. Listeners, schedules, retries, repair loops, and claims are bounded, monitored, cancellable, and failure-honest.
10. Resource cards may organize work but cannot weaken or reinterpret any invariant above.

### Vocabulary

| Term | Meaning |
|---|---|
| **room / mailbox** | The Handler-supplied shared folder and its contained `inbox/` |
| **message** | One append-only Markdown envelope; every valid addressed message is a CTA |
| **callsign** | Portable participant token inside one arena; identity remains self-asserted unless separately verified |
| **arena** | Opaque shared-room label, not an authority source |
| **locus** | Participant-local runtime and machine position used for safe state reuse |
| **primer** | Shared rehydration checkpoint; useful orientation, never authority or proof of inbox freshness |
| **disposition** | Durable participant-local handling result for one inbound UUID |
| **cursor** | Compact consumed-UUID index; an accelerator, not handling authority |
| **claim / pen** | Explicit single-writer ownership of an artifact in FULL or an agreed CORE workflow |
| **LISTENING** | Proven end-to-end local wake/re-entry, not merely a live process or availability promise |

## 1. Required input

The Handler supplies, or explicitly delegates the agents to choose:

1. a mailbox root or its `inbox/` path;
2. stable callsigns, or permission to auto-assign them;
3. the objective and authority boundary;
4. the peer or participant set;
5. who initiates and who owns the first shared artifact.

Also resolve the transport adapter, privacy posture, local locus identity, expected callsigns, agreed tags, any Handler-selected **local** operating mode or horizon, local listener bounds, and whether the project already has an `AGENT-MAILBOX-PRIMER.md`. Listener bounds and operating mode belong to this participant's runtime; the handshake never settles them. Auto-detect transport only through §10's ordered checks. Do not guess a vault, peer identity, shared-folder provider, publication scope, scheduler, or wake capability.

## 2. One protocol, two profiles

| Profile | Use when | Adds |
|---|---|---|
| **CORE** | Exactly two agents; one project mailbox; no competing concurrent claims | Two-message establishment, delivery receipts, single-writer artifacts, bounded listening, idempotent consumption, visible primer |
| **FULL** | Three or more agents, long-lived or unreliable sessions, concurrent work claims, quorum, frozen recipients, or authentication | Explicit third-handshake ACK, session identifiers, claims and leases, frozen recipients, durable rollups, optional signed-commit profile |

FULL is a strict superset of CORE. The Handler may force FULL. Do not silently downgrade FULL requirements merely because only two agents are online today.

## 2A. Layered capability packages

CORE and FULL are collaboration-semantics profiles. Operating capabilities use a separate extension namespace and never reinterpret `profile`.

The base skill is complete by itself. It always owns authority, safe paths, atomic publication, causality, addressed-message selection, durable disposition, reconciliation, exchange budgets, and bounded-listener rules. Optional packages are lazy participant-local operating directives loaded only after the base handshake:

| Package | Loads when | Adds | Honest fallback |
|---|---|---|---|
| [`collab-window@2`](protocols/collab-window.yon) | This participant's Handler selects Work-or-Listen/Collab Window, or the participant recommends it locally | Finite local work/listen lease; `WORKING`, proven `LISTENING`, `PARKED`, degradation, stop and cleanup | Base exchange plus local `PARKED` |
| [`scheduled-collab@2`](protocols/scheduled-collab.yon) | This participant's Handler selects scheduled checks and the host exposes an authorized bounded native scheduler | Local absolute horizon, maximum checks, no-overlap, failure budget, cancellation | Base exchange plus local `PARKED` |
| [`missed-message-recovery@1`](protocols/missed-message-recovery.yon) | A miss, cursor inconsistency, or readiness contradiction is reported | Readiness revocation, disposition/cursor audit, exact reconstruction, historical-debt quarantine | Base exchange plus `DEGRADED` |

If awaiting handshake traffic would otherwise block the local turn, a participant may arm its own bounded listener before establishment after proving the selected local adapter. This changes no handshake term and creates no peer obligation. Do not claim `LISTENING` until wake or re-entry works end to end; otherwise report `PARKED`.

After establishment or resume, use Standard Exchange unless continued collaboration was requested or is plainly necessary to complete an already-authorized exchange. When continuity is requested, use one runtime default rather than asking the Handler to choose a mechanism: Claude Code/Claude Agent SDK uses native Monitor when that host exposes it; Codex uses native bounded Scheduled Collab bound to the exact Handler-visible task in which collaboration was started; every other runtime uses Standard Exchange unless the Handler explicitly authorizes construction around a documented, proven native mechanism. A Codex participant surfaces that target task before registration and does not create, fork, or select a dedicated collaboration task unless the Handler explicitly asks for one. If exact same-task binding and re-entry cannot be proved, Scheduled Collab is unavailable and the participant uses Standard Exchange. An explicit Handler choice still wins. See [`OPERATING-MODES.md`](references/OPERATING-MODES.md).

Activation and listener repair share one durable participant-local circuit breaker keyed by arena plus runtime. Allow one bounded activation attempt or one bounded repair attempt. On failure, record `PARKED` before proof or `DEGRADED` after a previously proven path fails, use the honest fallback, and resume the project objective. A fresh explicit Handler mailbox-infrastructure task may clear the breaker for one exact replacement run; bind that authority to the arena, runtime, adapter, purpose, and finite run identity, then consume it when that run terminates. Session restart does not reset it, and the task is never standing authority for later constructions.

Mailbox continuity is subordinate infrastructure, never the project deliverable unless the Handler explicitly makes it so. Do not let adapter diagnosis, canaries, or repair loops displace the authorized work.

### Mailbox awareness and self-check boundaries

An active participant stays aware of the mailbox without turning every turn into a scan:

1. **Work boundary:** after each meaningful mailbox-derived work unit and before reporting it complete, materialize or sync through the recorded transport and reconcile the complete addressed inbox plus every non-terminal CTA. Skip only when the same check already ran after the last effect and durable state has not changed.
2. **Handler return:** at the start of a new Handler turn, run that reconciliation only when local durable state shows an actionable non-deferred `pending` or `active` CTA, a blocked CTA whose named gate the current Handler input may answer, a due deferral, `wake-pending`, listener-recorded candidates, or a continuity-health contradiction. The possibility of unknown new mail is not itself knowable local evidence. An unrelated Handler message with none of those conditions creates no mailbox sync tax.
3. **Continuity health:** while Collab Window or Scheduled Collab is active, check its participant-local health on every Handler/model re-entry before deciding whether mailbox sync is needed. Collab Window compares the independent Monitor heartbeat with its expected bound. Scheduled Collab records an exact local turn nonce, origin, start, and normal end. A due firing inside the exact currently proven-live Handler-origin turn is `suppressed`, restarts its clock from normal turn end, and is not a failure; a scheduled-origin turn observes its own firing and never suppresses it. At the next re-entry, a prior unmatched start whose nonce is not the current live turn transitions to `DEGRADED` with one complete gap reconciliation; it is not an indefinitely busy turn. A due firing that spans a proven idle window without arrival is `missed` and transitions to `DEGRADED`. Continuous suppression by the exact current live turn is `ACTIVE (health unevaluated since )`, never green or degraded. Native control-plane status may strengthen either result but is not the portable correctness mechanism. A continuity-health contradiction is local evidence for one complete gap reconciliation; a dead consumer cannot diagnose itself, so this check runs through the surviving participant path.

Standard Exchange makes no autonomous wake or health promise. It still preserves outstanding CTA state and performs the Handler-return and work-boundary checks above. A time-based deferral that elapses while no model is running returns to the active queue on the next surviving Handler or resume turn; the idle interval is not itself a protocol failure.

For a newly constructed bounded listener with no stronger adapter-specific values, use a 30-second observation interval, 30-minute maximum, and three consecutive failures as advisory local starting values. They are not handshake terms or availability promises.

The advisory local post-handshake or post-resume settling horizon is ten minutes. Each participant may independently choose another bounded horizon and cadence. Longer operation uses renewable bounded leases with one absolute Handler-approved deadline. This value is neither a protocol constant nor an availability promise. Literal unbounded or “non-stop” execution is unsupported.

The base handshake establishes first. Then each participant independently selects, proves, starts, rearms, expires, stops, and cleans up its own operating package. **Never propose, accept, counter, reject, renew, or block on another participant's operating mode, cadence, horizon, listener, or scheduler.** If one participant asks another to deliver, review, check, or reply by a deadline, that is an ordinary scoped `request`, `propose`, or FULL claim under the base authority rules—not mode activation.

At most one primary local operating package is active **per participant**: Collab Window or Scheduled Collab. Different participants may use different modes and cadences simultaneously. Missed-message recovery is the only version-1 overlay. A local package is not active until its exact YON file has been read and its prerequisites evidenced.

An agent may optionally publish a sender-local availability FYI using canonical `kind: state`, explicit `meta.mailbox.availability` metadata, and `expects_reply: false`. It is orientation only: no SLA, acceptance, counter, renewal, or waiting may follow. Emit only on a material reported-state transition; it counts normally toward the exchange budget. The recipient records `no-reply-required`, may update the sender's coarse primer summary, and does not change establi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [allemaar](https://github.com/allemaar)
- **Source:** [allemaar/open-skills](https://github.com/allemaar/open-skills)
- **License:** Apache-2.0
- **Homepage:** https://allemaar.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-allemaar-open-skills-agent-mailbox
- Seller: https://agentstack.voostack.com/s/allemaar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.