SKILL: ai-cli-orchestrator (Multi AI CLI Orchestrator)

# SKILL: ai-cli-orchestrator (Multi AI CLI Orchestrator)

**Version:** 2.0.0 (2026-03-16)

**Status:** Stable

**Expertise:** CLI Automation, Error Recovery, Tool Chain Management

---

1. Description

`ai-cli-orchestrator` is a meta-skill that integrates multiple AI CLI tools (such as Gemini CLI, Cursor Agent, Claude Code) to build a highly available automation workflow. It intelligently identifies the AI toolchain in the current environment, allocates the optimal tool based on task type, and achieves seamless task context transfer with automatic fallback when the primary tool encounters rate limits, API failures, or logical bottlenecks.

---

2. Trigger Scenarios

---

3. Core Workflow

3.1 Discovery Phase

1. **Auto-Scan:** Scan system PATH to detect installed AI CLI tools (`gemini`, `cursor-agent`, `claude`, etc.).

2. **Availability Check:** Run `tool --version` or simple echo tests to verify API key validity.

3. **Environment Sync:** Read `.ai-config.yaml` or `.env` from project root for permission config.

3.2 User Configuration

#### 1. Auto-Scan Available AI CLI

🤖 AI Assistant Initialization

Detected AI CLI tools:
✅ gemini - Installed
❌ cursor-agent - Not detected
✅ claude - Installed

Select tools to enable (multi-select):
[1] gemini
[2] cursor-agent  
[3] claude
[4] Add custom...

#### 2. Add Custom AI CLI

Enter command name: kimi
Enter test command: kimi --version
Enter description: Moonshot AI

#### 3. Set Priority

Priority (lower number = higher priority):
1. gemini
2. claude

#### 4. Select Strategy

Choose AI response strategy:

[1] AI CLI First
    - When receiving questions, automatically use AI CLI to search for answers first

[2] Direct Response
    - Use model capabilities directly

[3] Hybrid Mode
    - Simple questions answered directly, complex questions use AI CLI

3.3 Task Dispatching Phase

1. **Intent Recognition:** Analyze user input (Research, Code, or Debug?).

2. **Priority Matching:** Select preferred tool based on priority matrix.

3. **Session Management:**

- Check for associated Session ID.

- For continuous tasks, try to inject intermediate outputs (diff or thought chain) as context to the new tool.

3.4 Monitoring & Fallback Phase

1. **Real-time Monitoring:** Monitor CLI stderr and exit codes.

2. **Failure Detection:**

- Non-zero exit code with "rate limit", "overloaded", "auth error".

- Output fails local validation 3 times consecutively.

3. **State Handover:** Start backup tool, automatically retry failed instruction.

---

4. Configuration Example

Create `.ai-cli-orchestrator.yaml` in project root:

version: "2.0"
settings:
  default_strategy: "balanced" # options: speed, quality, economy
  auto_fallback: true
  max_retries: 2

tools:
  gemini:
    priority: 1
    alias: "gemini"
    capabilities: ["long-context", "multimodal", "fast-search"]
  cursor-agent:
    priority: 2
    alias: "cursor"
    capabilities: ["codebase-indexing", "surgical-edit"]
  claude-code:
    priority: 3
    alias: "claude"
    capabilities: ["logic-reasoning", "unit-testing"]

strategies:
  balanced:
    primary: "gemini"
    secondary: "cursor-agent"
    emergency: "claude-code"

---

5. Error Handling

| Error Type | Detection | Response |

| :--- | :--- | :--- |

| **Rate Limit** | `429 Too Many Requests` | Record offset, switch to next tool, delay 30s then reset. |

| **Logic Loop** | Same File Edit 3 times | Force interrupt, output context, request higher-level tool. |

| **Auth Failed** | `401 Unauthorized` | Try local backup `.env`; if failed, skip and notify user. |

| **Network Timeout** | `ETIMEDOUT` | Retry once; if still fails, switch to offline mode or backup CLI. |

| **Command Not Found** | `command not found` | Skip this tool, switch to next available tool. |

| **Stalled > 30s** | Timeout | Force interrupt, switch tool and retry. |

---

6. Session Management

6.1 Task Metadata

Each task associates:

6.2 Session Switching Rules

| Scenario | Action |

|----------|--------|

| Same task | Keep long conversation, don't create new session |

| Different task | Create new session |

| Return to previous task | Switch to corresponding session |

6.3 Context Recovery

When switching back to old task:

1. Read task summary

2. Load key history fragments

3. Quickly restore state

---

7. AI CLI Priority

| Priority | Tool | Purpose | Fallback |

|----------|------|---------|----------|

| 1 | gemini | Primary Q&A/Search | Auto-switch to 2 |

| 2 | cursor-agent | Code tasks | Auto-switch to 3 |

| 3 | claude-code | Emergency fallback | Error and notify user |

---

8. Best Practices

---

9. Available Commands

---

10. Extensibility

Support integrating new AI CLIs by writing simple adapters. Just provide:

1. `detect()`: How to find the tool.

2. `execute(prompt, context)`: How to call and get output.

3. `parse_error()`: How to parse its unique error types.

---

12. Security & Credentials

Why We Need to Read Config Files

This skill requires reading shell and project configuration files to:

Credential Protection

Best Practices

---

11. Version History