amElnagdy/delegate-skills instruction manual

1. Purpose, operating model, and Claude Code classification

`delegate-skills` is an MIT-licensed Skills CLI package for delegating bounded coding work to a separate coding-agent CLI. The agent that loads the skill is the **orchestrator**; the external CLI is the **implementer**. The orchestrator writes a self-contained **brief**, the implementer edits a real Git working tree, and the resulting diff—not the implementer’s narration—is the deliverable. The orchestrator then reruns the project’s test, lint, and build **gates**, reviews the diff, and **lands** the work by committing it. Every relay deliberately avoids committing.

**Claude Code classification:** this is a **Claude extension using context injection and orchestration, backed by external CLI scripts**. The evidence is direct: the package installs Agent Skills, can target `--agent claude-code`, and its skill instructions tell Claude Code how to launch bundled Node relays and supervise separate implementer processes. It is not a Claude Code hook, MCP server, model provider, or standalone coding environment. It can also work with other orchestrators supported by Skills CLI, but the repository says the complete delegate → review → commit loop is designed for and run on Claude Code; other orchestrators are designed-for but unproven.

Use delegation for bounded work such as migrations, mechanical refactors, removal sweeps, tests, or isolated features. Do not use it when the task is quicker to complete inline, when the requested implementer is unavailable or unauthenticated, or when the user wants the orchestrator to write the code directly. A special utility, `delegate-setup`, configures fleets and never dispatches coding work.

2. Requirements, inspection, installation, and pinning

The common requirements are Node.js 18 or newer, Git, and an orchestrating agent that can execute shell commands and read files. Each `*-delegate` skill additionally needs its named implementer CLI installed and authenticated. Shell examples assume bash or zsh on macOS/Linux, or Git Bash/WSL on Windows.

Inspect the available package contents before installation:

npx skills add amElnagdy/delegate-skills --list

Install the complete package, only fleet setup, 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

Target Claude Code specifically or install globally:

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

To pin an installation, append an existing release tag, for example:

npx skills add amElnagdy/delegate-skills@v0.2.0

Pinning uses the Git tag, not the informational `metadata.version` inside each `SKILL.md`.

After installing, you can ask Claude Code or another supported orchestrator to invoke a skill directly:

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

The repository also contains a Cursor Cloud Agent provisioning script. Its documented purpose is narrowly developmental: it uses an existing nvm installation to select Node 22 and place `node`, `npm`, `npx`, and `corepack` symlinks in `/usr/local/cargo/bin`, refusing to overwrite non-symlinks. It is not presented as the normal package-install route.

3. Fleet setup, lanes, overlays, and direct selection

A **fleet** is a set of named **lanes**. Each lane binds a kind of work—such as `feature`, `tests`, or `ui`—to one implementer and may carry supported dials such as model, provider, effort, thinking level, or variant. `delegate-setup` discovers installed CLIs, proposes a compact fleet, displays the complete configuration, and writes it only after explicit approval. It requires no implementer to be preselected and never dispatches work.

Start the setup dialogue with:

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

Configuration may be global or limited to one repository. Project configuration overlays a whole lane rather than partially merging arbitrary lane fields. Project lanes are content-bound to the configuration that was explicitly approved: cloned or edited project configuration fails closed until it is approved again. At dispatch time, use the delegate skill corresponding to the lane’s implementer and add `--lane <name>`. Explicit command flags override lane dials. Calling the wrong implementer skill for a lane fails loudly rather than silently switching CLIs.

A documented lane-driven request is:

Use $opencode-delegate with --lane feature to implement the billing workflow, then review and commit it.

Fleet setup is optional. For one-off work, invoke the desired implementer skill directly and supply any supported dials on that dispatch. This avoids creating configuration when only one run is needed. The setup utility uses `discover.mjs`, `config.mjs`, `lane.mjs`, and a shared implementer table; unlike implementer skills, it has no `relay.mjs`.

4. The five-step delegation workflow

Every implementer follows the same review-first loop.

1. **Write the brief.** The implementer does not receive the orchestrator’s chat history. Include the goal, current state, exact scope, files or behavior that must remain untouched, the repository’s actual gate commands, and the expected final report. State that the implementer must not commit. Keep one bounded task per brief.
2. **Dispatch.** Run the selected skill’s bundled `scripts/relay.mjs`, supplying the brief and target repository. The documented generic shape is:

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

1. **Wait.** The relay blocks until the implementer exits, so use the orchestrator’s background-command facility for long work. Relays normally write artifacts under the system temporary directory. Completion means the process has exited and `result.json` exists—not merely that a progress display says finished.
2. **Review.** Treat `finalMessage` and claimed gate results as untrusted claims. Start with `touchedFiles`, inspect the complete Git diff against the brief, rerun the project’s gates yourself, and perform task-specific validation. For migrations, test round trips; for removals or renames, search for dangling references. Optional guard skills can supplement, not replace, review.
3. **Land.** The orchestrator commits only after the diff is correct and independently rerun gates pass. If rework is needed, resume where supported and send only a delta brief describing the correction.

The same pattern supports sequential queues: dispatch one task, review and land it, carry forward constraints and decisions, then run the next task. Finish a queue with a coherence review across all landed changes.

5. Implementer catalog and default autonomy

The package documents 17 implementer skills:

• `aider-delegate`: Aider; write mode auto-confirms but disables suggested shell commands and force-disables Aider’s auto/dirty commits. `--read-only` maps to `--dry-run`; resume uses per-worktree chat history.
• `agy-delegate`: Google Antigravity; uses its permission system, optional sandbox, plan-mode read-only, and conversation resume.
• `claude-delegate`: a separate Claude Code session; defaults to `acceptEdits` with an explicit tool surface, supports plan-mode read-only and session resume.
• `cline-delegate`: Cline; act mode uses auto-approval, while read-only forces the documented `--plan`/approval-disabled pair. Headless JSON resume is unsupported.
• `codex-delegate`: OpenAI Codex; defaults to `workspace-write`, supports read-only and thread/session resume.
• `commandcode-delegate`: Command Code; headless writes require unrestricted `--yolo`; its read-only path withholds write, edit, and shell tools.
• `cursor-delegate`: Cursor Agent; write mode uses `--force`; read-only uses plan mode; sessions can resume.
• `grok-delegate`: Grok Build; defaults to workspace sandboxing, offers unrestricted opt-in, and has only best-effort read-only detection.
• `kimi-delegate`: Kimi Code; headless mode always uses auto permission mode and has no read-only option.
• `opencode-delegate`: OpenCode; uses `build` for writes and `plan` for read-only; `--model` is required.
• `pi-delegate`: Pi; full local tools without a sandbox; read-only limits tools; session resume is supported.
• `omp-delegate`: Oh My Pi; write runs use `--yolo`; read-only limits tools; project extras are disabled unless approved.
• `qoder-delegate`: Qoder; defaults to `auto`, supports plan permission mode and resume.
• `vibe-delegate`: Mistral Vibe; defaults to `accept-edits`, supports plan-only and explicit full access.
• `copilot-delegate`: GitHub Copilot CLI; writes require opt-in `--allow-all-tools`; otherwise headless tools auto-deny; plan mode is read-only.
• `warp-delegate`: Warp Agent CLI binary `oz`; no sandbox, permission mode, or read-only run; resume uses a conversation id.
• `zcode-delegate`: ZCode; only `plan` and `yolo` work headlessly; `build` and `edit` are rejected.

6. Documented provider-specific setup and controls

Use each implementer’s own skill for its prerequisites and exact flags. The supplied first-party files document these representative setups:

**Pi:** install and inspect with:

npm install -g @earendil-works/pi-coding-agent
pi --version
pi --list-models

Authenticate with `/login` inside Pi or the provider’s API-key mechanism. Pi supports `--model`, `--provider`, `--read-only`, `--approve`, `--resume-last`, and `--session` through its relay.

**Oh My Pi:** install with `bun install -g @oh-my-pi/pi-coding-agent`; authenticate with `/login` or a provider key. Model discovery uses the subcommand—not the removed `--list-models` flag:

omp models
omp models --json
omp models find sonnet

Its relay accepts model/provider selection, `--thinking`, read-only tools, explicit project-resource approval, and session resume.

**Aider:** install with:

python -m pip install aider-chat

A hosted model needs its provider key. A local OpenAI-compatible endpoint uses a non-empty `OPENAI_API_KEY`, an `openai/` model prefix, and `--api-base`:

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo \
  --model openai/<served-model-name> --api-base http://127.0.0.1:<port>/v1

Aider also supports repeatable `--file`, context-only `--read`, and `--edit-format whole` for models that struggle with diff formatting.

**Grok:** install with `npm i -g @xai-official/grok`, then use `grok login`, device authentication, or `XAI_API_KEY`. **Kimi:** install with `brew install kimi-code` where supported and authenticate using `kimi login`. **Vibe:** install with `uv tool install mistral-vibe`, then use `vibe --setup` or `MISTRAL_API_KEY`. **Warp:** authenticate `oz` with `oz login` or `WARP_API_KEY`; `oz model list` supplies model ids.

7. Results, failures, resume behavior, and security boundaries

Every relay targets the `delegate-relay.result.v1` contract. Its common data includes `status`, `exitCode`, `signal`, the implementer’s final report, `touchedFiles`, and a session or conversation identifier when the upstream CLI exposes one. A host-killed hint may accompany signal reporting when the OOM killer ends a run. `touchedFiles` is `null` when Git cannot report and `[]` when the tree is clean. Usage errors exit 2 before writing a result; a missing implementer exits 127 and does write a provider-specific unavailable status. Some relays also report timeouts, aborts, read-only violations, version information, event logs, or provider-specific stream completeness.

Resume is not uniform. Claude, Codex, Cursor, Kimi, Pi, Oh My Pi, Qoder, Vibe, Copilot, and ZCode support recent or identified sessions; Antigravity resumes conversations; Warp takes `--conversation`; Aider restores a repository chat-history file; Cline’s headless JSON path has no documented resume. Resume briefs should contain only the correction or next step.

Do not mistake reporting for containment. Git status cannot reveal ignored files, reverted edits, or writes outside the repository. A worktree isolates checkout history but is not an operating-system sandbox. Kimi and Warp have no relay-enforced read-only mode. Grok’s read-only mode is explicitly best-effort. Pi, Oh My Pi, Aider, Warp, and Command Code lack a general sandbox; Command Code write mode is full trust. Aider file selection controls context, not filesystem reach. Warp may upload an end-of-run workspace snapshot unless `--no-snapshot` is passed, and its brief appears in the process list because it is sent through `--prompt`. Use containers or other OS-enforced isolation when host-level confinement is required.

8. Trust model, verification limits, development, and release process

The package is intentionally inspectable: skill content is Markdown; each implementer has one small `relay.mjs`; setup has four small Node scripts. The repository states that these scripts use Node built-ins only, make no network calls of their own, read or write no credentials, send no telemetry, and never commit. They do launch the selected implementer, Git, and platform process helpers. Discovery may call installed CLIs for version or model probes, and those CLIs may contact their own services.

Verification is uneven and should guide risk decisions. The README reports live runs for several relays—including Claude, Codex, Aider, Antigravity, Grok, Kimi, Command Code, Warp, ZCode, Cursor, Copilot, and contributor-reported cases—while OpenCode and Vibe are contract-tested only, and Oh My Pi has a live run pending. Platform coverage varies; several native Windows and Linux paths remain unverified. These are repository-reported tests, not an independent audit.

Contributors must claim a new implementer before building it. A valid implementer skill needs `SKILL.md`, exactly four standard references, one dependency-free relay, registration, smoke coverage, the common result contract, and an honest verification line. Documented project checks are:

node test/relay-smoke.mjs
npx skills add . --list
node test/relay-smoke.mjs --only codex
node test/relay-parity.mjs

Release pinning requires synchronized informational skill versions and an annotated Git tag. The documented example is:

git tag -a v0.2.0 -m "v0.2.0"
git push origin v0.2.0

The repository’s license is MIT. Before using a relay on valuable work, inspect its skill and script, begin from a clean working tree, choose the least-permissive supported mode, and preserve the core rule: review and verify before committing.