worker
Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based OMX teams
How do I install this agent skill?
npx skills add https://github.com/yeachan-heo/oh-my-codex --skill workerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill defines a coordination protocol for a multi-agent system. It is generally safe but carries a low risk of indirect prompt injection because the agent is instructed to read and execute tasks from external state files.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 1 issue
- Runlayerwarn
1/1 file flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
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 identityteam_state_root, config/manifestteam_state_root, local.omx/state.
Operational steps
- Split the environment into
teamNameandworkerName; 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.mdand take the first unblocked assignment. - Read
<team_state_root>/team/<teamName>/tasks/task-<id>.json; APIs use the bare numerictask_id(for example"1"). - Claim an unclaimed task before editing:
If the leader already claimed the task for you, do not re-claim it. Use the inbox handoff's current claim token, version, and lease; verify they match the task file. If they differ or the lease has expired, stop and ask the leader for a current assignment. Save the currentomx team api claim-task --input '{"team_name":"<teamName>","task_id":"<id>","worker":"<workerName>"}' --jsonclaimTokenand write{"state":"working","current_task_id":"<id>","current_claim_token":"<claimToken>","updated_at":"<ISO timestamp>"}to your workerstatus.json. Notify/PostToolUse heartbeats renew that unexpired token automatically. Renew at least every 5 minutes while working:
For commands/tool waits over 5 minutes, use the executableomx team api renew-task-claim --input '{"team_name":"<teamName>","task_id":"<id>","worker":"<workerName>","claim_token":"<claimToken>"}' --jsonwith_task_leaseBash wrapper in your generated inbox instructions: it renews before starting and periodically while the command runs, validates both API success layers, propagates renewal failure, and cleans up its own direct children. Commands spawning grandchildren must manage their own descendants. If renewal fails, stop editing and contact the leader; expired claims cannot be revived. - Do the assigned work. Do not write task lifecycle fields directly.
- Complete or fail through the lifecycle API, from
in_progresstocompletedorfailed:
Useomx team api transition-task-status --input '{"team_name":"<teamName>","task_id":"<id>","from":"in_progress","to":"completed","claim_token":"<token>","result":"<evidence>"}' --jsonrelease-task-claimonly to requeue a blocked task topending. - 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.jsonwith{"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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/yeachan-heo/oh-my-codex/worker">View worker on skillZs</a>