/zcode-delegate

name: zcode-delegate
description: >-
  Delegate a coding task to the Z.AI ZCode CLI as a background implementer, then review its diff and
  land it yourself. Use this whenever the user wants to hand implementation work to ZCode — phrasings
  like "have ZCode do X", "delegate this to ZCode", "run it through ZCode", or "use ZCode to
  implement/fix/refactor" — or to run a queue of coding tasks through ZCode while staying the
  reviewer. DO NOT USE for tasks small enough to do inline, or when the user wants the code written
  directly without delegating.
license: MIT
compatibility: Requires the `zcode` CLI (Z.AI ZCode) with a configured model provider, Node 18+, and git. ZCode ships its CLI inside the desktop app rather than on PATH or npm — see Prerequisites. The orchestrating agent must be able to run shell commands and read files. Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on Windows).
metadata:
  version: 0.5.0

ZCode Delegate

You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate **implementer** — the Z.AI ZCode CLI — then review what it produced and land it yourself. You write the brief and own the judgment; ZCode does the typing; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell command and read a file. (It is designed for and run on Claude Code; treat other orchestrators as designed-for, not yet proven.)

When NOT to use this

• The task is small enough to just do inline — delegation overhead is not worth it.
• ZCode is not installed, or its CLI has no model provider configured.
• You want to write the code yourself, or you only need a review.

Prerequisites (check once)

1. **ZCode is installed.** The CLI ships **inside the desktop app** — it is not on PATH and not on npm. The relay resolves it in this order: `--zcode-path <file>` or `ZCODE_CLI` first, then PATH, then the installed app bundle. On Linux the app is an AppImage with no fixed install path, so the flag or the environment variable is required there — the relay guesses nothing. 2. **A model provider is configured for the CLI**, with a key it can actually reach. Being signed into the desktop app is *not* enough — see below. 3. You are in (or will point `--cd` at) the target git repository.

The relay records the CLI version and how it was resolved into `result.json`, so a surprising install is visible after the fact.

Authenticating the headless CLI

**Signing into the ZCode desktop app does not authenticate the CLI this relay drives.** The CLI keeps its own config at `~/.zcode/cli/config.json`, separate from the desktop app's, and nothing bridges the two. `zcode login` is the intended path, but where it fails with `OAuth response is not valid JSON` the way in is a Z.AI API key.

Two pieces are needed, and they are separate:

1. **The provider block** must exist in `~/.zcode/cli/config.json`. It defines the provider, its endpoint and its models — the environment cannot supply this:

   {
     "provider": {
       "zai": {
         "kind": "anthropic",
         "options": { "apiKeyRequired": true, "baseURL": "https://api.z.ai/api/anthropic" },
         "models": { "glm-5.1": { "name": "GLM-5.1" } }
       }
     },
     "model": { "main": "zai/glm-5.1" }
   }

2. **The key** can live either in `provider.zai.options.apiKey` in that file, or in the environment as any one of `ZAI_API_KEY`, `ZCODE_API_KEY`, or `ANTHROPIC_API_KEY`. Prefer the environment — it keeps the secret off disk.

If a run fails with `Model provider is missing an API key: <provider>`, the provider block resolved but no key was found: set one of those variables and re-run.

Autonomy — read this before dispatching

ZCode's own term is **mode**. It has four values; only two are usable headlessly.

| mode | Behaviour | | --- | --- | | `yolo` | **Writes.** ZCode's own default for `--prompt`, and this relay's write-capable default. | | `plan` | **Refuses edits.** What `--read-only` selects. | | `build` | **Rejected by this relay.** No permission client exists headlessly, so tools are blocked and the run exits 0 having done nothing. | | `edit` | Rejected for the same reason. |

Two limits stated plainly, because ZCode cannot enforce them:

• **`plan` mode refused edits in testing, but the relay does not treat that as a guarantee.** It

takes a Git fingerprint before the run and reports a tri-state `readOnlyViolation` afterwards. Confirm `touchedFiles` came back empty rather than assuming no edits.

• **ZCode has no `--allowed-tools`.** Only the `--disallowed-tools` denylist exists, and it *is*

genuinely enforced. An explicit allowlisted tool surface is therefore impossible here — do not assume one.

The loop

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

1. Write the brief

ZCode sees **only** what you send — no repo memory, no chat history. Everything the task needs goes in the brief: the goal, the current state, what to change, what to leave untouched, the project's **actual** gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile — do not assume), and a report contract. Tell ZCode it will **not** commit. One task per brief. The relay delivers the brief as an attached file, so the command line no longer bounds its length — the model's context window still does. Full guidance and a template: [references/writing-the-brief.md](references/writing-the-brief.md).

2. Dispatch

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# continue a specific session:              add --session <sess_...>  (from result.json; send only the delta brief)
# continue the latest session for --cd:     add --resume-last
# withhold tools (denylist):                add --disallowed-tools "Write,Edit,Bash"
# point at the CLI expli