SuperAPI AI Directory

oil-delegate

Coding & development

View repository

Updated 11-13 15:33

About this skill

oil-delegate

SKILL_DIR refers to the absolute directory of the current Skill;<python> refers to Python 3.10+ (usually python3on macOS/Linux, usually py -3);DELEGATE is shorthand for <python> "$SKILL_DIR"/scripts/delegate.py .

Core rules

  • The user only speaks natural language; the current Agent runs the wrapper, and the user is not required to open a separate terminal.
  • Delegate only one well-scoped task at a time; a runner named by the user takes priority, role-based delegation uses the choice saved for that role, and all other cases use the default — never switch runners automatically.
  • Reuse each CLI's model, provider, and login; do not pass or save keys, and do not write keys into prompts.
  • The caller is responsible for scope, permissions, and final acceptance; an external Agent's self-reported results cannot replace workspace checks and real tests.

Choose the mode first

Mode When it applies Path Default stopping point
First-time Onboarding When --runner is not specified and run returns NEEDS_ONBOARDING, or the user asks to reconfigure Silent scan → user confirms the enabled pool and defaults → save Existing tasks continue; stop only when reconfiguring
New task Hand one analysis, review, or modification to an external Agent Assemble the delegation contract → run → read results and accept Report conclusions and verification evidence
Continuation task Follow up on or rework the previous round's result for the same CLI Verify runner and session ID → run --session Report this round's changes
Role-based delegation Another Skill delegates review, plan critique, consultation, or implementation run --role → handle by returned status Report conclusions and verification evidence
Configuration and diagnostics View the environment, preview permissions, or handle failures onboard --scan、config、run --dry-run Give a clear next step

Delegation contract

The prompt should concisely cover:

  1. Goal and boundaries: what to find out or change, and the scope that must not be touched.
  2. Completion criteria: expected behavior, edge cases, and the results that must ultimately be delivered.
  3. Entry-point clues: use --file to provide 1–4 confirmed files, and let the external Agent explore the rest on its own.
  4. Verification: confirm the real test, check, or build commands from the repository configuration; do not write vague "run the tests".
  5. Final report: changes and reasons, files involved, verification commands and results, and unfinished items.

When repository facts are missing, look them up first; do not guess. Diagnostics and reviews must cite files and line numbers, and distinguish facts from inferences.

Workflow

1. Onboarding and runner selection

When onboarding is not complete, explicitly passing --runner <已安装名称或别名> directly runs that CLI (without writing config.jsonand without blocking on the first-time guide); only the first default delegation that omits --runner returns NEEDS_ONBOARDINGAfter onboarding is complete, explicitly naming a runner that is not enabled will still cause an error and refusal; it will not be silently substituted.

Received NEEDS_ONBOARDING or when the user asks to configure the enabled pool and default item:

  1. The first time --runner is omitted, run automatically completes a silent scan and returns detected/installed runners; the user does not need to run any command. To refresh, run DELEGATE onboard --scan. The scan does not write configuration, read credentials, call models, install, or log in.
  2. Show installed runners, versions, sources, capabilities, and aliases, and explain that "installed does not mean authenticated". Before the first configuration, read Runner adapter reference, and explain clearly the difference between read/write permissions, external service fees, and that task text will be handed to the corresponding provider.
  3. Ask which runners to enable, and whether to use one by default or ask each time. Save only after receiving an answer:
    DELEGATE onboard --enable <claude,workbuddy,antigravity,codex,opencode,dsh,grok,kimi> --default-runner <runner|ask>
    

Names are case-insensitive; enabling, default items, delegation, and binary path configuration all go through the same alias resolution, and are uniformly converted to the official Runner name when saved; for the complete mapping, see Runner adapter reference。

If there is already a pending task this time, after saving, return to step 2 and continue without asking the user to resend; stop only if the user is merely reconfiguring.

When no runner is specified and there is no default value,run returns NEEDS_RUNNER_CHOICE. Ask for the choice this time; only if the user agrees to persist the preference, run DELEGATE config --set-default-runner <runner>。

To view configuration or specify a non-standard binary path:

DELEGATE config
DELEGATE config --set-bin <runner>=<可执行文件绝对路径>

2. Dispatch a new task

  • By default omit --mode, use write and the highest permissions of each CLI; analysis, exploration, and review are also not automatically downgraded.
  • Use --mode readonly when the user explicitly requests read-only, plan, or restricted permissions; when delegating by read-type role, the role automatically enforces read-only. Kimi's non-interactive mode has built-in auto permissions and cannot guarantee read-only, so it refuses read and does not pretend to support it.
  • By default use the current working directory; for cross-project cases, explicitly specify --workspace。
  • Call:
DELEGATE run --runner <名称> \
  --workspace "<项目绝对路径>" \
  --file "<相对入口文件>" \
  --prompt "<目标、边界、完成标准与真实验证命令>"

Omit --runnerwhen a default runner is configured. Append --dry-runif you need to verify the parameters before starting; preview does not start an external Agent.

Delegate by role

oil-plan、oil-code-review、oil-govern When delegating by purpose, use --role, and the user-saved preference determines who it is handed to:

Role Purpose Permission
review Independent code review Read-only
critique Critique the plan before starting work Read-only
diagnose Dual-model consultation for difficult problems: save two different choices, call them separately with --role-slot 1 and --role-slot 2 Call separately Read-only
implement Implement according to the confirmed plan Write
DELEGATE run --role review --workspace "<项目绝对路径>" --prompt "<审查范围与要求>"
  • Read-type roles automatically enforce read-only; do not pass --modeagain; Kimi cannot guarantee read-only and cannot be assigned to read-type roles.
  • Return NEEDS_ROLE_CHOICE(exit code 12): no Agent has been selected for this role yet. Show candidates to the user and ask once (host means the current Agent starts a brand-new sub-Agent to do it). If the user wants to remember it, save DELEGATE config --set-role review=<选择>(diagnose write two, separated by commas); to use it only this once, pass --runner。
  • Return USE_HOST(exit code 13): The user prefers the current Agent to do it itself. Instead, use a brand-new sub-Agent from the host, complete it according to role permissions, and do not call an external CLI.
  • Explicitly pass --runner ; when present, it takes precedence, but permissions are still determined by the role.
  • When the user says things like "from now on, use codex for all reviews", directly use config --set-role to save;--set-role review=ask to clear. Whenreview or critique and implement select the same runner, the configuration result will include warnings; tell the user to switch to one that better guarantees an independent perspective.
  • Role preferences are personal configuration, stored in oil-delegate's own configuration directory, and are not written into project files.

3. Resume the original session

Read the previous round's output session_id, and resume only with the same runner:

DELEGATE run --runner <原 runner> \
  --workspace "<原工作区>" \
  --mode <read|write> \
  --session <session_id> \
  --prompt "<本轮新发现、追问或修正要求>"

Resuming sends only the new information for this round, not the entire task again. Session IDs cannot be reused across runners; when a second opinion is needed, start a new task and add the necessary background. DSH resumption must use the original cwd; if its ownership, preset, or cwd validation fails, report it truthfully and do not bypass it.

Find an existing session by title

Used by oil-superagent when taking over an existing topic; no onboarding or runner enablement is required:

DELEGATE sessions --query "标题关键词" --limit 20 --json
DELEGATE sessions --runner anti --query "标题关键词" --json

Omit --runner to search all connected sources; names and aliases follow the unified resolution, with the newly added anti → antigravity. Keywords match only titles, ignoring case; exactly equal titles take priority, and the rest are sorted by update time in descending order;--limit is a positive integer, default 20.

The list reads only session metadata; it does not read conversation content, call models, access the network, or write configuration or run artifacts. JSON is output via emit() , andcontract_version remains 1:status: OK、sessions、unsupported、errors、skipped. Each session includes runner、session_id、title、workspace、updated_at、resumable、resume_command、source; times are uniformly UTC ISO 8601, and missing directories or times are null, and unnamed titles are empty strings.resumable=false When resume_command=null, do not attempt to resume directly. Bad lines are skipped line by line, and the count is recorded in skipped[runner]; only source read failures are recorded in errors, other sources' results are retained, and the exit code remains 0.

Connected: Kimi official list, Codex local index, Antigravity IDE/CLI local database, and macOS Claude desktop metadata.source=desktop-store indicates a desktop source: Antigravity IDE sessions cannot be resumed by agy; Claude uses cliSessionId, and can be resumed when the corresponding JSONL exists. For source restrictions and data root environment variables, see Runner Adaptation Reference。

Export a session for handoff to a new CLI session

When direct resumption is not possible, first export a handoff file:

DELEGATE sessions export --runner <名称> --session-id <ID> --out "<交接文件.md>" --json

Currently supports Antigravity IDE/CLI and Claude (including desktop sources); other runners return status: ERROR. Export only reads the specified session offline, writing Markdown with the title, directory, time, and user/Agent text in chronological order, skipping thinking, tools, images, and binaries.--max-turns N defaults to 30; one user message or one Agent reply counts as one round; the most recent N rounds are kept, with the number of omitted rounds noted at the beginning. Antigravity reads only checkpointed snapshots; for internal fields and the basis and limitations, see Runner Adaptation Reference。

The output parent directory must exist; an existing file errors by default, and only an explicit --force overwrites it; writing output into the CLI data directory is prohibited. JSON returns status、path、title、workspace、turns、omitted_turns、runner、session_id, additionally with contract_version: 1. On error, returns status: ERROR and exits non-zero.

Use the handoff file as the --file input for the new task, and state in the prompt that it contains the historical context, the goals to be completed, and the current workspace; if the file is outside the workspace, copy it into the workspace first. When creating a new run , omit --sessionand use the returned new session_id to track subsequent tasks.

4. Acceptance and failure recovery

  1. Read the summary of output_path ; when you need the exit code, session ID, or error structure, read result_path; only read events_path。
  2. for raw protocol diagnostics. Check whether workspace changes are out of scope, check whether tests were deleted, skipped, or weakened, then rerun the real verification commands.
  3. When rework is needed, resume the original session and send only the new findings and correction requirements.
  4. After a non-zero exit, protocol error, or timeout, do not retry blindly. First correct the configuration, login state, task scope, or permissions based on the error, then decide whether to start a new task or resume.
  5. If the CLI or login is missing, stop and provide the corresponding official entry point; installation and login must be separately authorized by the user.

Output and stop conditions

On success, the script outputs status、session_id、runner、output_path、result_path、events_path and elapsed. Each run has an independent directory containing the prompt, condensed Markdown, structured result, raw stdout/stderr, and event log. The resume_command in the result is the command for the user to resume that session directly in the terminal.

When calling from other programs, append --json: stdout outputs only a single JSON object with contract_version(currently 1). Success, failure,NEEDS_ONBOARDING、NEEDS_RUNNER_CHOICE、NEEDS_ROLE_CHOICE、USE_HOST、DRY_RUN , and argument errors (status: ERROR) all use this format, and the exit codes match those of normal mode.

The final reply keeps only the conclusions the user needs, the actual changes, the verification evidence, the unfinished items, and the necessary session ID. Stop after completing the current delegation and acceptance; do not expand into multi-topic management, and do not automatically generate a dashboard.

Resource navigation

  • references/runners.md: Read the relevant Runner section only during initial configuration, explicit read-only access, troubleshooting a specific CLI, or maintaining an adapter; daily highest-privilege delegation does not require reading it.
  • scripts/delegate.py: Deterministic tools for scanning, configuration, invocation, parsing, and run artifacts; you do not need to read the source code when using the Skill.
  • tests/test_delegate.py: Regression tests for the eight Runners; read the relevant parts only during development or remediation.