Worker Skill
When to use
Use only when the session was started as an OMX Team worker. Read AGENTS.md#durable-runtime-invariants-canonical-ssot before acting; it defines the durable ownership and coordination boundaries.
Inputs and preconditions
- Require
OMX_TEAM_WORKER=<team-name>/worker-<n>.
- Resolve this skill from the first existing path:
${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md, ~/.codex/skills/worker/SKILL.md, <leader_cwd>/.codex/skills/worker/SKILL.md, then <leader_cwd>/skills/worker/SKILL.md.
- Resolve the Team state root in this order:
OMX_TEAM_STATE_ROOT, worker identity team_state_root, config/manifest team_state_root, local .omx/state.
Operational steps
- Split the environment into
teamName and workerName; Send a startup ACK before task work:omx team api send-message --input '{"team_name":"<teamName>","from_worker":"<workerName>","to_worker":"leader-fixed","body":"ACK: <workerName> initialized"}' --json
- Read
<team_state_root>/team/<teamName>/workers/<workerName>/inbox.md and take the first unblocked assignment.
- Read
<team_state_root>/team/<teamName>/tasks/task-<id>.json; APIs use the bare numeric task_id (for example "1").
- Claim before editing:
omx team api claim-task --input '{"team_name":"<teamName>","task_id":"<id>","worker":"<workerName>"}' --json
- Do the assigned work. Do not write task lifecycle fields directly.
- Complete or fail through the lifecycle API, from
in_progress to completed or failed:omx team api transition-task-status --input '{"team_name":"<teamName>","task_id":"<id>","from":"in_progress","to":"completed","claim_token":"<token>","result":"<evidence>"}' --json
Use release-task-claim only to requeue a blocked task to pending.
- Check and acknowledge mailbox messages:
omx team api mailbox-list --input '{"team_name":"<teamName>","worker":"<workerName>"}' --json
omx team api mailbox-mark-delivered --input '{"team_name":"<teamName>","worker":"<workerName>","message_id":"<MESSAGE_ID>"}' --json
- Write idle status after the transition:
<team_state_root>/team/<teamName>/workers/<workerName>/status.json with {"state":"idle","updated_at":"<ISO timestamp>"}.
Exit and evidence
Completion evidence names the task id, changed artifacts, verification performed, and any blocker. ACKs, task transitions, mailbox acknowledgements, and status writes must be observable through the Team API/state files. On shutdown, follow the lead's inbox instructions and write the required shutdown acknowledgement before exiting.
1---2name: worker3description: Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based OMX teams4metadata:5 source: https://skillmd.com/skills/yeachan-heo-oh-my-codex/worker6---78# Worker Skill910## When to use1112Use only when the session was started as an OMX Team worker. Read `AGENTS.md#durable-runtime-invariants-canonical-ssot` before acting; it defines the durable ownership and coordination boundaries.1314## Inputs and preconditions1516- Require `OMX_TEAM_WORKER=<team-name>/worker-<n>`.17- Resolve this skill from the first existing path:18 `${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md`, `~/.codex/skills/worker/SKILL.md`, `<leader_cwd>/.codex/skills/worker/SKILL.md`, then `<leader_cwd>/skills/worker/SKILL.md`.19- Resolve the Team state root in this order: `OMX_TEAM_STATE_ROOT`, worker identity `team_state_root`, config/manifest `team_state_root`, local `.omx/state`.2021## Operational steps22231. Split the environment into `teamName` and `workerName`; Send a startup ACK before task work:24 ```bash25 omx team api send-message --input '{"team_name":"<teamName>","from_worker":"<workerName>","to_worker":"leader-fixed","body":"ACK: <workerName> initialized"}' --json26 ```272. Read `<team_state_root>/team/<teamName>/workers/<workerName>/inbox.md` and take the first unblocked assignment.283. Read `<team_state_root>/team/<teamName>/tasks/task-<id>.json`; APIs use the bare numeric `task_id` (for example `"1"`).294. Claim before editing:30 ```bash31 omx team api claim-task --input '{"team_name":"<teamName>","task_id":"<id>","worker":"<workerName>"}' --json32 ```335. Do the assigned work. Do not write task lifecycle fields directly.346. Complete or fail through the lifecycle API, from `in_progress` to `completed` or `failed`:35 ```bash36 omx team api transition-task-status --input '{"team_name":"<teamName>","task_id":"<id>","from":"in_progress","to":"completed","claim_token":"<token>","result":"<evidence>"}' --json37 ```38 Use `release-task-claim` only to requeue a blocked task to `pending`.397. Check and acknowledge mailbox messages:40 ```bash41 omx team api mailbox-list --input '{"team_name":"<teamName>","worker":"<workerName>"}' --json42 omx team api mailbox-mark-delivered --input '{"team_name":"<teamName>","worker":"<workerName>","message_id":"<MESSAGE_ID>"}' --json43 ```448. Write idle status after the transition:45 `<team_state_root>/team/<teamName>/workers/<workerName>/status.json` with `{"state":"idle","updated_at":"<ISO timestamp>"}`.4647## Exit and evidence4849Completion evidence names the task id, changed artifacts, verification performed, and any blocker. ACKs, task transitions, mailbox acknowledgements, and status writes must be observable through the Team API/state files. On shutdown, follow the lead's inbox instructions and write the required shutdown acknowledgement before exiting.