multi-ai-consultant

What this skill does

# Multi-AI Consultant

Consult external AIs for second opinions when Claude Code is stuck or making critical decisions.

---

## What This Skill Does

This skill enables **future Claude Code sessions** to consult other AIs when:
- Stuck on a bug after one failed attempt
- Making architectural decisions
- Security concerns need validation
- Fresh perspective needed

**Key innovation**: Uses existing CLI tools (`gemini`, `codex`) instead of building MCP servers - much simpler and more maintainable.

---

## When to Use This Skill

### Automatic Triggers (No User Action Needed)

Claude Code should **automatically suggest** using this skill when:

1. **After 1 failed debugging attempt**
   - Tried one approach to fix a bug
   - Still not working or different error
   - → Suggest: "Should I consult [Gemini|Fresh Claude] for a second opinion?"

2. **Before architectural decisions**
   - Significant design choices (state management, routing, data flow)
   - Framework selection
   - Database schema design
   - → Auto-consult (mention to user): "Consulting Gemini for architectural validation..."

3. **Security changes**
   - Authentication logic
   - Authorization rules
   - Cryptography
   - Input validation
   - → Auto-consult: "Consulting Gemini to verify security approach..."

4. **When uncertain**
   - Multiple valid approaches
   - Trade-offs not clear
   - Conflicting advice in documentation
   - → Suggest: "Would you like me to consult another AI for additional perspective?"

### Manual Invocation (User Commands)

User can explicitly request consultation with:
- `/consult-gemini [question]` - Gemini 2.5 Pro with thinking, search, grounding
- `/consult-codex [question]` - OpenAI GPT-4 via Codex CLI (repo-aware)
- `/consult-claude [question]` - Fresh Claude subagent (free, fast)
- `/consult-ai [question]` - Router that asks which AI to use

---

## The Three AIs

| AI | Tool | When to Use | Special Features | Cost |
|----|------|-------------|------------------|------|
| **Gemini 2.5 Pro** | `gemini` CLI | Web research, latest docs, thinking | Google Search, extended reasoning, grounding | ~$0.10-0.50 |
| **OpenAI GPT-4** | `codex` CLI | Repo-aware analysis, code review | Auto-scans directory, OpenAI reasoning | ~$0.05-0.30 |
| **Fresh Claude** | Task tool | Quick second opinion, budget-friendly | Same capabilities, fresh perspective | Free |

**For detailed AI comparison**: Load `references/ai-strengths.md` when choosing which AI to consult for specific use cases.

---

## How It Works

### Architecture

```
Claude Code encounters bug/decision
        ↓
Suggests consultation (or user requests)
        ↓
User approves
        ↓
Execute appropriate slash command
        ↓
CLI command calls external AI
        ↓
Parse response
        ↓
Synthesize: Claude's analysis + External AI's analysis
        ↓
Present 5-part comparison
        ↓
Ask permission to implement
```

### The 5-Part Synthesis Format

Every consultation must follow this format (prevents parroting):

1. **🤖 My Analysis** - Claude's original reasoning and attempts
2. **💎/🔷/🔄 Other AI's Analysis** - External AI's complete response
3. **🔍 Key Differences** - Agreement, divergence, what each AI caught/missed
4. **⚡ Synthesis** - Combined perspective, root cause, trade-offs
5. **✅ Recommended Action** - Specific next steps with file paths/line numbers

**End with**: "Should I proceed with this approach?"

---

## Setup

**For complete installation guide**: Load `references/setup-guide.md` when installing CLIs, configuring API keys, or setting up templates.

**Quick setup**:
1. **Install CLIs**: `bun add -g @google/generative-ai-cli` (Gemini), `bun add -g codex` (Codex, optional)
2. **Set API keys**: `export GEMINI_API_KEY="..."`, `export OPENAI_API_KEY="..."`
3. **Install skill**: Symlink to `~/.claude/skills/multi-ai-consultant`
4. **Copy templates**: `GEMINI.md`, `codex.md`, `.geminiignore` to project root
5. **Verify**: `gemini -p "test"`, `codex exec - --yolo`

Get API keys:
- Gemini: https://aistudio.google.com/apikey
- OpenAI: https://platform.openai.com/api-keys

---

## Usage

**For detailed examples**: Load `references/usage-examples.md` when learning consultation workflows or seeing real-world scenarios.

**Quick examples**:
- **Bug**: After 1 failed attempt → `/consult-gemini` for web-researched solution
- **Architecture**: Design decision → `/consult-gemini` for latest best practices
- **Code review**: Refactoring validation → `/consult-codex` for repo-aware consistency check
- **Quick opinion**: Sanity check → `/consult-claude` for free fresh perspective

**5 detailed examples available**:
1. JWT authentication bug (saved ~30 min, found platform-specific issue)
2. State management choice (informed decision with 2025 patterns)
3. Refactoring review (found 3 consistency issues)
4. Security validation (found 2 critical issues via OWASP 2025)
5. Multi-AI workflow (high-stakes database choice)

---

## Slash Commands

**For complete command reference**: Load `references/commands-reference.md` when needing detailed syntax, options, or cost tracking information.

**Quick command overview**:

### /consult-gemini [question]
- **Use**: Web research, latest docs, extended thinking
- **Features**: Google Search, grounding, thinking mode
- **Cost**: ~$0.10-0.50
- **Example**: `/consult-gemini Is this JWT secure by 2025 standards?`

### /consult-codex [question]
- **Use**: Repo-aware analysis, code review
- **Features**: Auto-scans directory, consistency checks
- **Cost**: ~$0.05-0.30
- **Example**: `/consult-codex Review for performance bottlenecks`

### /consult-claude [question]
- **Use**: Quick second opinion, budget-friendly
- **Features**: Free, fast, fresh perspective
- **Cost**: Free
- **Example**: `/consult-claude Am I missing something obvious?`

### /consult-ai [question]
- **Use**: Router (recommends which AI to use)
- **Features**: Analyzes question, suggests best AI
- **Cost**: Varies by chosen AI
- **Example**: `/consult-ai How should we structure this architecture?`

---

## Templates

Templates customize AI behavior for consultations (auto-loaded from project root):

1. **GEMINI.md** - System instructions for Gemini (enforces 5-part format, web search)
2. **codex.md** - System instructions for Codex (enforces repo-aware analysis)
3. **.geminiignore** - Privacy exclusions beyond `.gitignore`
4. **consultation-log-parser.sh** - View consultation history (optional)

**Installation**: Copy from `~/.claude/skills/multi-ai-consultant/templates/` to project root

---

## Privacy & Security

**Automatic protection**:
- Both CLIs respect `.gitignore` automatically
- Create `.geminiignore` for extra exclusions (`.env*`, `*secret*`, `*credentials*`)
- Pre-consultation check warns if sensitive patterns detected

**Privacy best practices**:
- Always configure `.gitignore` properly
- Create `.geminiignore` for extra safety
- Use smart context selection (specific files, not entire repo)
- Verify what will be sent: `git status --ignored`

**For detailed privacy configuration**: Load `references/setup-guide.md` when setting up `.geminiignore` or privacy exclusions.

---

## Cost Tracking

Every consultation logged to `~/.claude/ai-consultations/consultations.log`

**Log format**: `timestamp,ai,model,input_tokens,output_tokens,cost,project_path`

**View logs**: `consultation-log-parser.sh --summary`

**Example output**:
```
Total consultations: 47
Gemini: 23 ($4.25), Codex: 12 ($1.85), Fresh Claude: 12 ($0.00)
Total cost: $6.10
```

**For detailed cost tracking**: Load `references/commands-reference.md` when viewing logs, calculating costs, or managing budgets.

---

## Common Issues

**For complete troubleshooting**: Load `references/troubleshooting.md` when encountering errors or setup issues.

**Top 5 issues**:

1. **CLI not installed**: `gemini: command not found` → Fix: `bun add -g @google/generative-ai-cli`
2. **API key invalid**: Authentication failed → Fix: `export GEMINI_API_KEY="