CLI Agent Orchestrator

Use this skill when a high-cost model should do architecture, judgment, and validation while a cheaper or separate local CLI agent performs token-heavy execution: filling in designed outlines, expanding many sections, generating boilerplate files, drafting repetitive documents, or completing batch prompts. Prefer a CLI that is not the current running agent when available, because the point is to delegate work to a separate agent runtime.

Trigger And Announcement

This skill should trigger when the user asks for any of these patterns:

• "让其他 AI/agent/CLI 去生成/补全/执行"
• "用便宜模型补内容"
• "高费用模型做好设计，低费用模型批量填充"
• "调用 qwen/opencode/claude/claudecode/gemini/codex"
• "批量生成很多文件，同时控制并发/模型/CLI"

When the skill is triggered, immediately tell the user one short line before running work:

我会使用 cli-agent-orchestrator，把批量生成交给 <cli>，模型为 <model 或 CLI default configured model>，并发数 <n>。

If CLI or model has not been chosen yet, say the planned default:

我会使用 cli-agent-orchestrator，先检测可用外部 CLI；未指定模型时使用该 CLI 的默认配置模型，并在报告里写明。

Do not silently delegate. The user should be able to see that this skill was used, which CLI was selected, which model was requested, and why this saves expensive-model tokens.

Core Workflow

1. Confirm the requested CLI name, or choose the locally configured default when the user does not specify one.
2. Check the CLI is installed before running work:
   • Use command -v <cli>.
   • If missing, stop and tell the user exactly which CLI was not found.
3. Decide model behavior:
   • If the user specifies a model, pass it using the CLI's model flag.
   • If the user does not specify a model, omit the model flag and call this CLI default configured model in the final report.
   • Always report the actual requested model string or that the CLI default was used.
4. Announce the skill, CLI, model, and concurrency before starting execution.
5. Split large work into independent tasks. Prefer one output file per task.
6. Run tasks with bounded concurrency. Start with 2 or 3; increase only when the CLI is stable.
7. Validate outputs before accepting them. At minimum check non-empty content, expected headings or markers, and no obvious CLI error text.
8. Save a run report with CLI path, model, concurrency, succeeded tasks, failed tasks, and failure reasons.
9. Tell the user where the outputs and report are.

Script

Use scripts/run_cli_agents.mjs for repeatable orchestration. The script has presets for common CLIs and a generic mode for anything else.

Basic example:

node /path/to/cli-agent-orchestrator/scripts/run_cli_agents.mjs \
  --cli qwen \
  --preset qwen \
  --model deepseek-v4-flash \
  --concurrency 3 \
  --tasks ./tasks.json \
  --out-dir ./generated \
  --use-pty

Use the CLI default configured model:

node /path/to/cli-agent-orchestrator/scripts/run_cli_agents.mjs \
  --cli qwen \
  --preset qwen \
  --concurrency 2 \
  --tasks ./tasks.json \
  --out-dir ./generated \
  --use-pty

For Qwen Code and Gemini CLI, --use-pty is often more reliable on macOS because some CLIs expect a terminal. Preset auto enables it for those CLIs.

Other common examples:

# OpenCode: prompt is positional after `opencode run`
node scripts/run_cli_agents.mjs \
  --cli opencode \
  --preset opencode \
  --model provider/model-name \
  --concurrency 2 \
  --tasks ./tasks.json \
  --out-dir ./generated

# Claude Code / claudecode: non-interactive print mode
node scripts/run_cli_agents.mjs \
  --cli claude \
  --preset claude \
  --model sonnet \
  --concurrency 2 \
  --tasks ./tasks.json \
  --out-dir ./generated

# Codex CLI: non-interactive exec mode
node scripts/run_cli_agents.mjs \
  --cli codex \
  --preset codex \
  --model gpt-5-codex \
  --concurrency 2 \
  --tasks ./tasks.json \
  --out-dir ./generated

Task File Format

Create a JSON file containing an array of tasks:

[
  {
    "id": "01-intro",
    "output": "01-intro.md",
    "prompt": "Write a Markdown learning note about ...",
    "minChars": 800,
    "required": ["## 本节目标", "## 自测题"]
  }
]

Fields:

• id: stable task identifier for logs.
• output: path relative to --out-dir.
• prompt: full prompt sent to the CLI.
• minChars: optional minimum cleaned output length.
• required: optional array of strings that must appear in output.

CLI Argument Mapping

Use --preset auto by default. It infers behavior from the CLI executable name:

| Preset | Command Shape | Model Flag | Prompt Style | Notes | | --- | --- | --- | --- | --- | | qwen | qwen ... -p <prompt> | --model | flag | Adds --approval-mode yolo; enables PTY | | gemini | gemini ... -p <prompt> | --model | flag | Adds --approval-mode yolo; enables PTY | | claude | claude -p ... <prompt> | --model | positional | Also covers claudecode / claude-code aliases when executable exists | | opencode | opencode run ... <prompt> | --model | positional | Model often uses provider/model format | | codex | codex exec --skip-git-repo-check ... <prompt> | --model | positional | Avoid using this preset when it would recurse into the same current agent | | generic | configurable | configurable | configurable | Use for unknown CLIs |

Override defaults when using another CLI:

node scripts/run_cli_agents.mjs \
  --cli some-cli \
  --preset generic \
  --model cheap-model \
  --model-arg --model \
  --prompt-mode flag \
  --prompt-arg --prompt \
  --extra-arg --non-interactive \
  --tasks ./tasks.json \
  --out-dir ./out

Use repeated --base-arg entries for arguments before model/prompt, such as subcommands. Use repeated --extra-arg entries for other flags.

Validation Guidance

Do not trust delegated output blindly. After the script finishes:

• Inspect run-report.json.
• Re-run failed tasks with lower concurrency or shorter prompts.
• Spot-check representative files for factual fit, structure, and user-specific requirements.
• Remove temporary scripts or task files if they were only created for a one-off job.

Reporting To The User

Final responses should include:

• CLI name and resolved path.
• Model: explicit model string, or CLI default configured model.
• Concurrency and timeout.
• Number of successful and failed tasks.
• Output directory and run report path.