Worker Skill
This skill is for a Codex session that was started as an OMX Team worker (a tmux pane spawned by
$team
).
Identity
You MUST be running with
OMX_TEAM_WORKER
set. It looks like:
/worker-
Example:
alpha/worker-2
Load Worker Skill Path (Claude/Codex)
When a worker inbox tells you to load this skill, resolve the first existing path:
${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md
~/.codex/skills/worker/SKILL.md
/.codex/skills/worker/SKILL.md
/skills/worker/SKILL.md
(repo fallback)
Startup Protocol (ACK)
Parse
OMX_TEAM_WORKER
into:
teamName
(before the
/
)
workerName
(after the
/
, usually
worker-
)
Send a startup ACK to the lead mailbox
before task work
:
Recipient worker id:
leader-fixed
Body: one short deterministic line (recommended:
ACK: initialized
).
After ACK, proceed to your inbox instructions.
The lead will see your message in:
/team//mailbox/leader-fixed.json
Use CLI interop:
omx team api send-message --input --json
with
{team_name, from_worker, to_worker:"leader-fixed", body}
Copy/paste template:
omx team api send-message
--input
"{
\"
team_name
\"
:
\"
\"
,
\"
from_worker
\"
:
\"
\"
,
\"
to_worker
\"
:
\"
leader-fixed
\"
,
\"
body
\"
:
\"
ACK: initialized
\"
}"
--json
Inbox + Tasks
Resolve canonical team state root in this order:
OMX_TEAM_STATE_ROOT
env
worker identity
team_state_root
team config/manifest
team_state_root
local cwd fallback (
.omx/state
)
Read your inbox:
/team//workers//inbox.md
Pick the first unblocked task assigned to you.
Read the task file:
/team//tasks/task-.json
(example:
task-1.json
)
Task id format:
The MCP/state API uses the numeric id (
"1"
), not
"task-1"
.
Never use legacy
tasks/{id}.json
wording.
Claim the task (do NOT start work without a claim) using claim-safe lifecycle CLI interop (
omx team api claim-task --json
).
Do the work.
Complete/fail the task via lifecycle transition CLI interop (
omx team api transition-task-status --json
) from
in_progress
to
completed
or
failed
.
Do NOT directly write lifecycle fields (
status
,
owner
,
result
,
error
) in task files.
Use
omx team api release-task-claim --json
only for rollback/requeue to
pending
(not for completion).
Update your worker status:
/team//workers//status.json
with
{"state":"idle", ...}
Mailbox
Check your mailbox for messages:
/team//mailbox/.json
When notified, read messages and follow any instructions. Use short ACK replies when appropriate.
Note: leader dispatch is state-first. The durable queue lives at:
/team//dispatch/requests.json
Hooks/watchers may nudge you after mailbox/inbox state is already written.
Use CLI interop:
omx team api mailbox-list --json
to read
omx team api mailbox-mark-delivered --json
to acknowledge delivery
Copy/paste templates:
omx team api mailbox-list
--input
"{
\"
team_name
\"
:
\"
\"
,
\"
worker
\"
:
\"
\"
}"
--json
omx team api mailbox-mark-delivered
--input
"{
\"
team_name
\"
:
\"
\"
,
\"
worker
\"
:
\"
\"
,
\"
message_id
\"
:
\"
\"
}"
--json
Dispatch Discipline (state-first)
Worker sessions should treat team state + CLI interop as the source of truth.
Prefer inbox/mailbox/task state and
omx team api ... --json
operations.
Do
not
rely on ad-hoc tmux keystrokes as a primary delivery channel.
If a manual trigger arrives (for example
tmux send-keys
nudge), treat it only as a prompt to re-check state and continue through the normal claim-safe lifecycle.
Shutdown
If the lead sends a shutdown request, follow the shutdown inbox instructions exactly, write your shutdown ack file, then exit the Codex session.