check-collaborators

name	check-collaborators
description	Verify that Gemini CLI and Claude Code CLI are installed, authenticated, and API-reachable before starting collaboration workflows.
metadata	{"short-description":"Collaborator CLI health check"}

Collaborator CLI Health Check

When to use

• Before starting any collaboration workflow that depends on Gemini or Claude Code.
• When diagnosing CLI connectivity or authentication issues.
• After installing or reconfiguring either CLI.

When not to use

• Both CLIs are already confirmed working in the current session.
• The task does not involve cross-agent collaboration.

Inputs

• Current OS environment (auto-detected).

Outputs

• Summary table: Collaborator x CLI / Version / Auth / API / Status.
• Actionable remediation advice for any failed step.

Workflow

Run the Gemini and Claude detection chains in parallel where possible. For each collaborator, execute steps sequentially and short-circuit on the first failure — skip subsequent steps and mark the failure reason.

Step 0: Detect OS

Determine the platform to choose the correct binary-lookup command:

• Windows (win32): use where
• Unix/macOS: use which

Detect via uname -s 2>/dev/null (returns nothing or errors on Windows) or check $OSTYPE.

---

Gemini Detection Chain

1. CLI Exists

# Unix
which gemini
# Windows
where gemini

Pass: command exits 0 and outputs a path. Fail: command not found — suggest: npm install -g @anthropic-ai/gemini-cli or see https://github.com/google-gemini/gemini-cli

2. Version

timeout 15 bash -c 'GEMINI_CLI_NO_RELAUNCH=true gemini --version'

On Windows (no timeout command), run directly:

GEMINI_CLI_NO_RELAUNCH=true gemini --version

GEMINI_CLI_NO_RELAUNCH=true is required to prevent the CLI from hanging.

Pass: output contains a version string (e.g., 0.32.1). Fail: timeout or no version output.

3. Auth

Check for any of the following (any one is sufficient):

1. Environment variable GEMINI_API_KEY is set and non-empty.
2. Environment variable GOOGLE_API_KEY is set and non-empty.
3. File ~/.gemini/oauth_creds.json exists.

[[ -n "$GEMINI_API_KEY" ]] || [[ -n "$GOOGLE_API_KEY" ]]
test -f "$HOME/.gemini/oauth_creds.json"

Pass: any one condition is true. Fail: none found — suggest: export GEMINI_API_KEY=<key> or run gemini interactively to complete OAuth.

4. API Connectivity

timeout 30 gemini --prompt "Reply with exactly: HEALTH_OK"

Pass: stdout contains HEALTH_OK. Fail: timeout or no HEALTH_OK in output — suggest checking network, API key validity, or quota.

Note: Gemini CLI may emit warnings (e.g., skill conflict notices) in its output. These are benign and do not affect the health check. The pass/fail criterion is solely whether HEALTH_OK appears in stdout.

---

Claude Code Detection Chain

1. CLI Exists

# Unix
which claude
# Windows
where claude

Pass: command exits 0 and outputs a path. Fail: command not found — suggest: npm install -g @anthropic-ai/claude-code or see https://docs.anthropic.com/en/docs/claude-code

2. Version

timeout 15 claude --version

Pass: output contains a version string (e.g., 2.1.74). Fail: timeout or no version output.

3. Auth

claude auth status

Pass: output contains Logged in or JSON field loggedIn: true. Fail: not logged in — suggest: run claude interactively and use /login.

4. API Connectivity

timeout 30 claude --print "Reply with exactly: HEALTH_OK" --output-format text --no-session-persistence --max-budget-usd 0.50

Pass: stdout contains HEALTH_OK. Fail: timeout or no HEALTH_OK — suggest checking API key, network, or account quota.

Note: --max-budget-usd must be at least 0.50. Lower values (e.g., 0.01, 0.05) cause immediate Exceeded budget errors because model inference has a minimum cost floor.

---

Output Format

Present a summary table after all checks:

| Collaborator | CLI | Version | Auth | API | Status    |
|--------------|-----|---------|------|-----|-----------|
| Gemini       | ✓/✗ | x.y.z   | ✓/✗  | ✓/✗ | Available / Failed |
| Claude Code  | ✓/✗ | x.y.z   | ✓/✗  | ✓/✗ | Available / Failed |

• Use ✓ for passed steps, ✗ for failed steps, — for skipped steps (due to short-circuit).
• Status is Available only if all 4 steps pass; otherwise Failed.
• Version column shows the detected version string, or — if not reached.

For any failed step, append actionable remediation advice below the table:

### Issues Found

**Gemini — Auth failed**
No API key or OAuth credentials detected.
→ Set `GEMINI_API_KEY` environment variable, or run `gemini` to complete OAuth login.

**Claude Code — CLI not found**
Claude Code CLI is not installed.
→ Install: `npm install -g @anthropic-ai/claude-code`
→ Docs: https://docs.anthropic.com/en/docs/claude-code

If both collaborators pass all checks:

Both collaborators are available and ready for collaboration workflows.

Verification

• Run this skill and confirm the summary table appears with correct status for each collaborator.

Safety and guardrails

• Read-only checks only; no configuration files are modified.
• API connectivity tests consume minimal tokens (~$0.01 per check).
• Steps 2-4 spawn external CLI processes; run them outside sandbox (escalated permissions) to avoid hangs or EPERM errors.
• On Windows, timeout may not be available; run commands directly and watch for hangs.
• Gemini --version must use GEMINI_CLI_NO_RELAUNCH=true to prevent the CLI from relaunching itself.