amElnagdy/delegate-skills

Create your fleet of lanes. One orchestrator, the right implementer for every job.

Discover the implementer CLIs already installed on your machine, organize them into lanes like feature, tests, and ui, then delegate by lane — or choose one implementer directly. Either way, you keep the review and the commit.

npx skills add amElnagdy/delegate-skills

Then ask your orchestrating agent to create the fleet:

Use $delegate-setup to discover my installed implementer CLIs and create a fleet for feature, tests, and UI work.

Or delegate directly:

Use $codex-delegate to have Codex implement the refactor in services/billing/, then review and commit it.

flowchart LR
  S["$delegate-setup<br/>discover → propose → approve"] --> F["Example fleet"]
  O["Your orchestrator"] --> F
  F -->|"feature"| A["OpenCode"]
  F -->|"tests"| B["Codex"]
  F -->|"ui"| C["Cursor"]
  A --> R["Review the diff<br/>Run the gates"]
  B --> R
  C --> R
  R --> L["You land the commit"]

A fleet is your set of named lanes. Each lane binds a kind of work to one implementer and optional dials such as model, effort, or variant. Setup discovers what is available, proposes a compact fleet, shows you the complete configuration, and writes only after explicit approval.

Configuration can apply globally or to one repository. Once it is ready, dispatch with the matching *-delegate skill and --lane <name>. Explicit flags override lane dials, and the wrong implementer skill for a lane fails loud. Project config is content-bound to explicit setup approval, so cloned or edited project lanes fail closed until re-approved. See the delegate-fleet.v1 schema for paths, supported dials, and overlay behavior.

Skip setup when you want one implementer or one-off dials. Pick the skill for a CLI you have:

Each skill name links to its SKILL.md, which owns that implementer's prerequisites, flags, and caveats. Building one for another CLI? Claim it first, then see CONTRIBUTING.md.

Install codex-background alongside the selected delegate skills when Codex is the orchestrator. It is a separate installation; codex-delegate does not install or configure it automatically. If its MCP tools are missing, Codex runs the skill's scripts/bootstrap.mjs (after telling you it will update $CODEX_HOME/config.toml, with a backup); you can run it yourself with node <skill-dir>/scripts/bootstrap.mjs. It registers the installed *-delegate skills, writes the registry and the MCP server entry, and asks you to restart Codex. One pending MCP request captures logs locally and returns a single completion; the selected skill still owns permissions, results, review and landing. Claude's background Bash workflow stays unchanged. See configuration and recovery. Local protocol fixtures cover the waiting boundary; they do not measure Codex Desktop token usage.

Browse first:

npx skills add amElnagdy/delegate-skills --list

Install the package, the setup skill, or one implementer skill:

npx skills add amElnagdy/delegate-skills
npx skills add amElnagdy/delegate-skills --skill delegate-setup
npx skills add amElnagdy/delegate-skills --skill codex-delegate

To pin an installation, append an existing release tag as @vMAJOR.MINOR.PATCH. The Skills CLI installs by git ref, not by metadata.version in SKILL.md.

Install for a specific agent, or globally:

npx skills add amElnagdy/delegate-skills --skill codex-delegate --agent claude-code
npx skills add amElnagdy/delegate-skills --global

Works with any orchestrating agent the Skills CLI supports.

Whether you choose the implementer directly or through a fleet lane, every dispatch follows the same review-first loop:

1. Write a brief — self-contained task context; the implementer has no orchestrator chat history.
2. Dispatch it with the bundled relay.mjs.
3. Wait for completion — the relay writes a structured result.json.
4. Review the diff — re-run the project's gates yourself; pair with guard skills.
5. Land it — you commit, because committing belongs to the reviewer.

Use $claude-delegate to have a separate Claude Code session implement the parser fix, then review and commit it.
Use $opencode-delegate with --lane feature to implement the billing workflow, then review and commit it.
Use $codex-delegate to run this queue of migration tasks through Codex while I review each one.

Every relay speaks the same delegate-relay.result.v1 contract: status, exitCode, signal (with a host-killed hint when the OOM killer ends a run), the implementer's own final report, touchedFiles, and a session id where the CLI exposes one. Learn the loop once, swap the implementer freely.

You feel it when a bounded task — a migration, a mechanical refactor, a removal sweep — comes back as a clean diff with a structured report, and you land it after re-running the gates yourself instead of typing it all by hand.

Four invariants hold for every *-delegate skill. They are also the bar for a new implementer:

• A separate CLI edits a real working tree, and the diff is the deliverable. Not an API wrapper, not a gateway — an implementer whose work you can read with git diff.
• The relay never commits. Committing belongs to the reviewer, always.
• Node built-ins only. No dependencies, no network calls of its own, no credentials, no telemetry. The relay launches its implementer CLI and git, plus the platform process launcher where a Windows shim or a process-tree kill needs one.
• Autonomy is stated in the CLI's own terms, and whatever it cannot enforce is said plainly — see the two footnotes above.

This is a loop, not a forwarder: a forwarder hands over one task and returns the output. Here you dispatch, poll, review, and land, across one task or a queue. It stays complementary to a vendor's own plugin or subagents — those coordinate inside one agent; this keeps the contract portable across orchestrators, with the commit on the reviewer.

delegate-setup is the setup-skill exception: it discovers CLIs and writes an approved fleet map, but never dispatches coding work.

Full checklist: CONTRIBUTING.md.

• For a *-delegate skill, its implementer CLI authenticated as you would at the terminal. Each implementer skill's SKILL.md carries its own install and login commands.
• delegate-setup requires no implementer CLI; it discovers whichever ones are available.
• Node 18+ and git.
• An orchestrating agent that can run shell commands and read files.
• Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on Windows).

This package is intentionally inspectable:

• All skill content is Markdown, plus small Node scripts. Each *-delegate skill has exactly one scripts/relay.mjs. The delegate-setup utility ships discover.mjs / config.mjs / lane.mjs (and a shared implementer table) instead of a relay — it never dispatches coding work.
• Those scripts make no network calls of their own, read or write no credentials, send no telemetry, and have no dependencies (Node built-ins only). Relays launch an implementer CLI and git, plus the platform process launcher/termination utility where a Windows shim or process-tree kill requires one. The optional codex-background utility adds a local stdio MCP server around registered existing relays, with no npm dependencies or network calls of its own. Its bootstrap.mjs writes $CODEX_HOME/config.toml (a backup is made first) and the registry only when you or Codex run it, and registers just the *-delegate skills found next to it. Its provider-independent ownership supervisor uses a compiled subreaper on Linux and inbox PowerShell plus kernel job APIs on Windows. Linux requires /usr/bin/cc and procfs; other hosts fail setup explicitly. Discover may invoke installed CLIs for --version / model list probes (those CLIs may contact their own services). Read the script before you run it.
• None of the relays ever commit — committing is always the orchestrator's job, after review.

Verification status — claims here are backed by runs, not assumptions.

True of every relay: argument handling, exit codes, result.json shape, supported resume mappings, and signal reporting are verified, along with each implementer-specific guard.

Per skill — platform, CLI version, and what the run exercised:

• aider-delegate — Windows, aider 0.86.2: contract-tested against the shared smoke matrix, plus live headless --message-file runs against a stub OpenAI-compatible endpoint on loopback. Those runs covered: an applied edit left uncommitted, with a pre-existing dirty file still uncommitted, proving --no-auto-commits/--no-dirty-commits; no .gitignore written, proving --no-gitignore; a --read-only (--dry-run) run that left the target file byte-identical; an endpoint returning 401, where aider exits 0 and the relay reports failed with litellm.AuthenticationError; aider_unavailable/127 writing a result file; and usage errors exiting 2 without one. Review follow-ups were re-verified the same way: a successful run whose report says OPENAI_API_KEY three times still reports completed; a reused --out-dir seeded with another run's final.txt and result.json publishes neither; a plain exit 7 carries an error; and a --read-only run over a modified .aider.conf.yml plus generated history and tags-cache warns about exactly the config file. Not run against a hosted provider model or a real local inference server, and not run on macOS or Linux.

• agy-delegate — Windows 10, native, agy 1.1.12: headless --print write run editing one briefed file; --read-only --effort high run whose brief ordered an immediate file write, in a directory the permission rules allowed: agy refused, wrote nothing, and result.json reported effort high, readOnly true, readOnlyViolation false; argument validation for a bad --effort value and for --read-only combined with --dangerously-skip-permissions, both exiting 2; resume by --conversation with a delta brief. macOS, agy 1.0.16: headless edit run, --print= delivery, absolute --add-dir workspace pin. --stall-timeout is contract-tested, live stall pending: a fake whose log keeps growing without streamGenerateContent lines reports stalled, steady generation calls split across writes keep a run alive, and the watchdog is off unless passed; run on native Windows against the compiled fake.

• claude-delegate — macOS, claude 2.1.220: write run under acceptEdits; plan mode refusing an edit, with the Git tripwire true on a violation and false on a clean run; --session/--resume-last resume; claude_unavailable/127 and usage errors exiting 2 without a result file; deny rules and the shell sandbox blocking git commit, git push, git -C <dir> push, a nested claude, and a $HOME write. macOS, claude 2.1.271: --autocompact argument handling only. The installed CLI accepted auto, 400k, 1M, 200, and 200000 and rejected auto2, 50k, 2m, 99, 1000001, and 0 with exit 1, each observed through claude --autocompact <value> --help, which validates the option and exits before any model call; claude 2.1.220 rejects the option itself with unknown option '--autocompact', which is the documented 2.1.221 floor. The relay's pass-through, resume re-pass, and result.json record are contract-tested against the smoke matrix; no delegated run has been dispatched with --autocompact set. Windows 11, native, claude 2.1.274 through the npm claude.cmd shim, launched from Windows PowerShell 5.1 with an --out-dir containing a space: write run under acceptEdits editing one file and creating another, with git status run through the pre-approved PowerShell tool and a git commit attempt denied by the relay's deny rule (permission_denied with decision_reason_type: "rule" in the event stream, HEAD untouched); --session resume whose delta brief referred only to "the notes file you created a moment ago" and was applied correctly; --read-only plan-mode run ordered to write two files over an already-dirty tree, which wrote nothing and reported readOnlyViolation: false with the dirty files byte-identical; a 45s --timeout firing on a run blocked in a foreground ping grandchild, reporting timeout and exit 1 with no ping, cmd, or claude process left behind; claude_unavailable/127 writing a result file, and usage errors exiting 2 without one. The runs used --model haiku. Not run on Windows: a directly spawned claude.exe, the abort path, and a read-only violation. Claude's shell sandbox is unsupported there, so the write profile's PowerShell is not isolated.

• cursor-delegate — Windows, cursor-agent 2026.07.23-e383d2b: write run under --force; plan-mode --read-only touching nothing; --session <id> resume applying a delta brief; usage errors exiting 2. A maintainer-run native macOS plan-mode smoke against the same version captured model, session, and usage with no touched files. --stall-timeout is contract-tested; the live hang it targets was observed on Linux with cursor-agent 2026.10.01-e373342 (two runs silent after thinking completed, never exiting).

• grok-delegate — macOS, grok 0.2.101: streaming-json report capture, file-based brief delivery, resume; read-only is best-effort by measurement, hence the violation flag. Contributor-run native Windows check with grok 1.0.13: a no-edit dispatch using --trust-git-root on a drive rejected by Git's ownership check completed with the pre-existing untracked file reported and readOnlyViolation: false; that run used a real drive path whose spelling did not diverge, and the verdict is claimed for Windows paths whose spelling does not diverge — exact-head CI evidence for spelling-divergent temp paths lands with this repair. Ownership, nested-directory, linked-worktree, dirty-path, submodule, and unavailable-Git cases are covered by the grok-git-trust smoke module.

• kimi-delegate — macOS, kimi 0.24.0: headless -p edit run, stream-json parsing, and both resume paths — the relay's --session/--resume-last, which drive Kimi's own --session and --continue.

• pi-delegate — macOS: stdin brief delivery, explicit provider and model selection, JSON session/provider/model/usage capture, and a --read-only run leaving a clean tree. Write, --session, and --resume-last runs are contributor-reported.

• omp-delegate — contract-tested, live run pending: stdin brief delivery, omp --mode json argv (--yolo, --tools read,grep,glob, --no-extensions --no-skills --no-rules, --thinking), session header / message_end parsing, --approve omitting the project-trust flags, --continue resume, assistant stopReason: error reported as failed, omp_unavailable/127, and bounded --version preflight. Native Windows launch is a native omp.exe (no shell:true); that path is contract-tested via the smoke matrix's compiled fake, not against a live Oh My Pi install.

• qoder-delegate — macOS, qodercli 1.0.47, by the contributor: Lite edit run, accept_edits, explicit model and 32768-token context window, no commit.

• commandcode-delegate — macOS, cmd 1.26.0: live edit run verified. A relay dispatch against a throwaway git repository had Command Code fix a remainder-dropping bug in a money-splitting function and add three tests; the project gate was re-run independently by the orchestrator (2 tests before, 5 passing after), the diff matched the brief with no writes outside the two named files, and HEAD was untouched — the relay does not commit, and the run did not either. A second dispatch with --session <id> verified resume through the relay: a one-line delta brief amended exactly the comment it named, with the session id from the first run. A --read-only dispatch verified the other direction, returning readOnlyViolation: false on a clean tree. Also verified negatively: separate live runs confirmed --tools-all and --permission-mode auto-accept leave the headless write gate closed and only --yolo opens it.

  Live running surfaced a CLI limitation the relay now handles. cmd ends a run with a run_end event embedding the whole conversation, then exits with process.exit, discarding whatever is still queued in its stdout pipe: both write runs lost their result line entirely (one cut ~8 KB into run_end, the other losing its last ~780 events). So nothing load-bearing is read from that tail — sessionId comes from run_start, the first line of the stream, and the report from the last message_end or its streamed deltas — the event log is written in batches so the relay drains the pipe as fast as it can, resultLine reports complete/truncated/absent so a consumer knows which fields are trustworthy. A complete non-success result converts a zero child exit to relay exit 1, while a lost result line falls back to the process exit code. Smoke cases pin that contract. On a long run the report itself can land in the discarded region. The diff is the deliverable, and a thin report means missing information, not a failed run.

  Native Windows launch is contract-tested against the installed cmdc.cmd shape, including stdin brief delivery and the cmd.exe collision guard. A live native Windows Command Code run remains unverified; upstream recommends WSL for stable Windows use.

• warp-delegate — macOS, oz 0.2026.05.27.15.44.stable_01: live edit run verified. A relay dispatch against a throwaway git repository had Warp add a function plus four assertions across two files; both project gates were re-run independently by the orchestrator, the diff matched the brief, and HEAD was untouched. Verified end to end: version preflight, launch, ndjson parsing (run_started → runId/runUrl, conversation_started → conversationId), report extraction from {"type":"agent","text":…} events with agent_reasoning excluded, touchedFiles, and status: "completed" / exit 0. A second dispatch with --conversation verified resume: a delta brief saying only "the function you just added" — never naming it — produced exactly the right edit, with resumed: true and the conversation id preserved. Also observed on a prior run: touchedFiles: [] on a clean tree and exit 1 → status: "failed". Two caveats are documented in the skill rather than fixed, because they are Warp's behaviour and not the relay's: finalMessage is the agent's full narration rather than a distinct final-message event, and --cwd governed shell commands while the agent's file tool resolved bare relative paths against $HOME. --no-snapshot, --profile, --skill, and --mcp are contract-tested only.

• zcode-delegate — Windows, zcode 0.16.1: read-only (plan) run leaving a clean tree with the Git tripwire false; write run under yolo creating the briefed file and reporting it in touchedFiles; --session resume with an attached delta brief, which recalled the earlier turn; single-document --json parsing; --version preflight; discovery resolving the CLI from the app bundle rather than PATH; and environment-variable auth under all three names ZCode accepts — against an isolated home whose config carried no apiKey, a keyless run failed first, then ZAI_API_KEY, ZCODE_API_KEY, and ANTHROPIC_API_KEY each completed the same read-only dispatch. Contract-tested: build/edit rejection, the missing-CLI path, tolerance of the AI SDK banner that ZCode can print on stdout ahead of the JSON (observed in direct CLI probes; exercised in the suite by the fake), and the timeout matrix. The abort matrix is POSIX-only — Windows delivers no catchable SIGTERM — so for this relay it first runs in CI. zcode-delegate is also absent from the shared read-only tripwire scenario matrix, which runs claude and grok only — its tripwire helpers are parity-enforced byte-identical, but no zcode-specific worktree-state run is recorded. No macOS or Linux run is recorded.

• codex-delegate — macOS, codex codex-cli 0.150.1: fresh workspace-write dispatch against a throwaway repo created the briefed file and reported it in touchedFiles, with status: "completed" and exit 0; a --read-only dispatch left the tree clean (touchedFiles: []) and returned a threadId; a follow-up --session <id> resume against that thread was asked to recall a word from the first turn without it being named again — the delta brief said only "the word you picked a moment ago" — and it answered correctly, confirming the resumed turn saw prior context, not just that the id was accepted. Contract-tested: argument validation, bounded version preflight, missing binary, result parsing, and whole-process-tree timeout/abort cleanup. Windows 11, codex codex-cli 0.153.4, native (Git Bash launch, no pwsh installed): a workspace-write dispatch against a throwaway repo created the briefed file and reported it in touchedFiles with status: "completed", exit 0, and a threadId; the brief had Codex run shell commands and report its shell, which came back as System32 powershell.exe 5.1 with zero WindowsApps entries on its PATH while the parent process carried one — the relay's PATH filter reaching the sandbox, not just the child's argv. The denial the filter exists for was reproduced through the unpatched relay on the same machine: a workspace-write dispatch asked Codex to run winget, which lives only under WindowsApps, and both the PATH lookup and the absolute path failed inside the sandbox with "The file cannot be accessed by the system" while the same binary ran normally outside it. No Store pwsh is installed here, so the shell-launch form of that denial (0xC0070005 on every command) rests on the report in issue #116. No Linux run is recorded.

• muse-delegate — macOS, Muse Code 1.4.7: a fresh write dispatch against a throwaway repo created only the briefed file (touchedFiles reported exactly it, status: "completed", exit 0, a sessionId captured); a --session <id> continuation in that same session appended the briefed line; a --read-only dispatch answered from the tree and left it byte-identical; and an --provider echo dispatch completed end to end. Contract-tested: argv exactness (muse exec with --disable-approval / --disable-write / --disable-shell, no --yolo, --session-id, --resume-last rejected), exit 0 without run.terminal.completed reported failed, bounded version preflight, missing binary, the bounded stderrTail over a flooded stderr, and whole-process-tree timeout/abort cleanup. Upstream's launcher is UNIX-only. No Windows or Linux run is recorded.

• opencode-delegate, vibe-delegate — contract-tested only: argument validation, bounded version preflight, missing binary, result parsing, and whole-process-tree timeout/abort cleanup. No end-to-end run is recorded here.

• cline-delegate — macOS, cline 3.0.52: current-binary unauthenticated plan probe reached run_start with the fixed positional instruction plus the real brief on stdin, accepted a provider-local model id, parsed the failing run_result, and left the tree clean. Contract-tested: plan mode forcing --auto-approve false, the unsafe true conflict, argument validation, nullable sessionId/finalPath, bounded version preflight, missing binary, result parsing, and whole-process-tree timeout/abort cleanup. The contributor also reported a native Windows 3.0.51 edit run against the earlier positional-brief commit; that does not verify this exact stdin-based head on Windows.

• copilot-delegate — Windows, copilot 1.0.78: --read-only plan-mode run completed with a clean tree and captured session id; --allow-all-tools edit run created the requested file; the headless auto-deny path was exercised live (denial detected from the data-wrapped event shape, run reported failed with the --allow-all-tools hint); --session <id> and --resume-last resume runs executed their delta briefs via the directive-wrapped -p @<file> prompt. Contract-tested: argv exactness (including the resume directive), denial shape, --read-only/--allow-all-tools conflict validation, bounded version preflight, missing binary, result parsing, and whole-process-tree timeout/abort cleanup.

• delegate-setup — contract-tested: discover JSON shape, config validate/write/load, whole-lane project overlay, global write without creating .delegate/, and --lane resolve / wrong-skill / flag-override against relays. The smoke suite runs live discovery against installed CLIs (versions vary by machine). Native Windows discover smoke not yet claimed.

Not yet verified: native Windows launches for a directly spawned claude.exe (the npm claude.cmd shim path has a run above), exact-head cline, grok, kimi, muse, pi, qoder, vibe, and omp (codex/opencode/grok/commandcode have contract-tested .cmd shim handling; Cursor serializes a pre-joined, quoted command; Qoder and Vibe target their documented native executables). Claude's own shell sandbox is unsupported on native Windows regardless of launch mechanics, upstream Vibe officially targets UNIX, and Muse's upstream launcher is UNIX-only. A native Linux cursor-agent run is unverified. The full delegate → review → commit loop is designed for and run on Claude Code; other orchestrators (Cursor, …) are designed-for but unproven.

Implementer skills share one shape; the utilities have different ones:

skills/
├── <name>-delegate/
│   ├── SKILL.md
│   ├── scripts/relay.mjs
│   └── references/
│       ├── writing-the-brief.md
│       ├── dispatch-and-poll.md
│       ├── review-and-land.md
│       └── multi-task-queues.md
├── codex-background/
│   ├── SKILL.md
│   ├── scripts/
│   │   ├── bootstrap.mjs
│   │   ├── bootstrap.test.mjs
│   │   ├── server.mjs
│   │   ├── server.test.mjs
│   │   ├── supervisor.mjs
│   │   ├── linux-owner.c
│   │   ├── windows-job.ps1
│   │   └── windows-job.cs
│   └── references/configuration.md
└── delegate-setup/
    ├── SKILL.md
    ├── scripts/
    │   ├── discover.mjs
    │   ├── config.mjs
    │   ├── lane.mjs
    │   └── implementers.mjs
    └── references/
        ├── schema.md
        └── setup-dialogue.md

Adding an implementer is a new directory plus two lines here: a table row, and a verification line once a run backs it.

Contributing? House rules, the controlled vocabulary, and the pre-publish checklist live in AGENTS.md — read it before opening a pull request, and point your agent at it too.

MIT — see LICENSE.