Initial commit

2025-11-29 18:48:55 +08:00
commit f28999f19c
127 changed files with 62038 additions and 0 deletions
--- a/skills/llm-router/SKILL.md
+++ b/skills/llm-router/SKILL.md
@@ -0,0 +1,501 @@
+---
+name: llm-router
+description: This skill should be used when users want to route LLM requests to different AI providers (OpenAI, Grok/xAI, Groq, DeepSeek, OpenRouter) using SwiftOpenAI-CLI. Use this skill when users ask to "use grok", "ask grok", "use groq", "ask deepseek", or any similar request to query a specific LLM provider in agent mode.
+---
+
+# LLM Router
+
+## Overview
+
+Route AI requests to different LLM providers using SwiftOpenAI-CLI's agent mode. This skill automatically configures the CLI to use the requested provider (OpenAI, Grok, Groq, DeepSeek, or OpenRouter), ensures the tool is installed and up-to-date, and executes one-shot agentic tasks.
+
+## Core Workflow
+
+When a user requests to use a specific LLM provider (e.g., "use grok to explain quantum computing"), follow this workflow:
+
+### Step 1: Ensure SwiftOpenAI-CLI is Ready
+
+Check if SwiftOpenAI-CLI is installed and up-to-date:
+
+```bash
+scripts/check_install_cli.sh
+```
+
+This script will:
+- Check if `swiftopenai` is installed
+- Verify the version (minimum 1.4.4)
+- Install or update if necessary
+- Report the current installation status
+
+### Step 2: Configure the Provider
+
+Based on the user's request, identify the target provider and configure SwiftOpenAI-CLI:
+
+```bash
+scripts/configure_provider.sh <provider> [model]
+```
+
+**Supported providers:**
+- `openai` - OpenAI (GPT-4, GPT-5, etc.)
+- `grok` - xAI Grok models
+- `groq` - Groq (Llama, Mixtral, etc.)
+- `deepseek` - DeepSeek models
+- `openrouter` - OpenRouter (300+ models)
+
+**Examples:**
+
+```bash
+# Configure for Grok
+scripts/configure_provider.sh grok grok-4-0709
+
+# Configure for Groq with Llama
+scripts/configure_provider.sh groq llama-3.3-70b-versatile
+
+# Configure for DeepSeek Reasoner
+scripts/configure_provider.sh deepseek deepseek-reasoner
+
+# Configure for OpenAI GPT-5
+scripts/configure_provider.sh openai gpt-5
+```
+
+The script automatically:
+- Sets the provider configuration
+- Sets the appropriate base URL
+- Sets the default model
+- Provides guidance on API key configuration
+
+### Step 3: Verify API Key
+
+The configuration script automatically checks if an API key is set and will **stop with clear instructions** if no API key is found.
+
+**If API key is missing:**
+
+The script exits with error code 1 and displays:
+- ⚠️ Warning that API key is not set
+- Instructions for setting via environment variable
+- Instructions for setting via config (persistent)
+
+**Do not proceed to Step 4 if the configuration script fails due to missing API key.**
+
+Instead, inform the user they need to set their API key first:
+
+**Option 1 - Environment variable (session only):**
+```bash
+export XAI_API_KEY=xai-...           # for Grok
+export GROQ_API_KEY=gsk_...          # for Groq
+export DEEPSEEK_API_KEY=sk-...       # for DeepSeek
+export OPENROUTER_API_KEY=sk-or-...  # for OpenRouter
+export OPENAI_API_KEY=sk-...         # for OpenAI
+```
+
+**Option 2 - Config file (persistent):**
+```bash
+swiftopenai config set api-key <api-key-value>
+```
+
+After the user sets their API key, re-run the configuration script to verify.
+
+### Step 4: Execute the Agentic Task
+
+Run the user's request using agent mode:
+
+```bash
+swiftopenai agent "<user's question or task>"
+```
+
+**Agent mode features:**
+- One-shot task execution
+- Built-in tool calling
+- MCP (Model Context Protocol) integration support
+- Conversation memory with session IDs
+- Multiple output formats
+
+**Examples:**
+
+```bash
+# Simple question
+swiftopenai agent "What is quantum entanglement?"
+
+# With specific model override
+swiftopenai agent "Write a Python function" --model grok-3
+
+# With session for conversation continuity
+swiftopenai agent "Remember my name is Alice" --session-id chat-123
+swiftopenai agent "What's my name?" --session-id chat-123
+
+# With MCP tools (filesystem example)
+swiftopenai agent "Read the README.md file" \
+  --mcp-servers filesystem \
+  --allowed-tools "mcp__filesystem__*"
+```
+
+## Usage Patterns
+
+### Pattern 1: Simple Provider Routing
+
+**User Request:** "Use grok to explain quantum computing"
+
+**Execution:**
+
+```bash
+# 1. Check CLI installation
+scripts/check_install_cli.sh
+
+# 2. Configure for Grok
+scripts/configure_provider.sh grok grok-4-0709
+
+# 3. Execute the task
+swiftopenai agent "Explain quantum computing"
+```
+
+### Pattern 2: Specific Model Selection
+
+**User Request:** "Ask DeepSeek Reasoner to solve this math problem step by step"
+
+**Execution:**
+
+```bash
+# 1. Check CLI installation
+scripts/check_install_cli.sh
+
+# 2. Configure for DeepSeek with Reasoner model
+scripts/configure_provider.sh deepseek deepseek-reasoner
+
+# 3. Execute with explicit model
+swiftopenai agent "Solve x^2 + 5x + 6 = 0 step by step" --model deepseek-reasoner
+```
+
+### Pattern 3: Fast Inference with Groq
+
+**User Request:** "Use groq to generate code quickly"
+
+**Execution:**
+
+```bash
+# 1. Check CLI installation
+scripts/check_install_cli.sh
+
+# 2. Configure for Groq (known for fast inference)
+scripts/configure_provider.sh groq llama-3.3-70b-versatile
+
+# 3. Execute the task
+swiftopenai agent "Write a function to calculate fibonacci numbers"
+```
+
+### Pattern 4: Access Multiple Models via OpenRouter
+
+**User Request:** "Use OpenRouter to access Claude"
+
+**Execution:**
+
+```bash
+# 1. Check CLI installation
+scripts/check_install_cli.sh
+
+# 2. Configure for OpenRouter
+scripts/configure_provider.sh openrouter anthropic/claude-3.5-sonnet
+
+# 3. Execute with Claude via OpenRouter
+swiftopenai agent "Explain the benefits of functional programming"
+```
+
+## Provider-Specific Considerations
+
+### OpenAI (GPT-5 Models)
+
+GPT-5 models support advanced parameters:
+
+```bash
+# Minimal reasoning for fast coding tasks
+swiftopenai agent "Write a sort function" \
+  --model gpt-5 \
+  --reasoning minimal \
+  --verbose low
+
+# High reasoning for complex problems
+swiftopenai agent "Explain quantum mechanics" \
+  --model gpt-5 \
+  --reasoning high \
+  --verbose high
+```
+
+**Verbosity levels:** `low`, `medium`, `high`
+**Reasoning effort:** `minimal`, `low`, `medium`, `high`
+
+### Grok (xAI)
+
+Grok models are optimized for real-time information and coding:
+
+- `grok-4-0709` - Latest with enhanced reasoning
+- `grok-3` - General purpose
+- `grok-code-fast-1` - Optimized for code generation
+
+### Groq
+
+Known for ultra-fast inference with open-source models:
+
+- `llama-3.3-70b-versatile` - Best general purpose
+- `mixtral-8x7b-32768` - Mixture of experts
+
+### DeepSeek
+
+Specialized in reasoning and coding:
+
+- `deepseek-reasoner` - Advanced step-by-step reasoning
+- `deepseek-coder` - Coding specialist
+- `deepseek-chat` - General chat
+
+### OpenRouter
+
+Provides access to 300+ models:
+
+- Anthropic Claude models
+- OpenAI models
+- Google Gemini models
+- Meta Llama models
+- And many more
+
+## API Key Management
+
+### Recommended: Use Environment Variables for Multiple Providers
+
+The **best practice** for using multiple providers is to set all API keys as environment variables. This allows seamless switching between providers without reconfiguring keys.
+
+**Add to your shell profile** (`~/.zshrc` or `~/.bashrc`):
+
+```bash
+# API Keys for LLM Providers
+export OPENAI_API_KEY=sk-...
+export XAI_API_KEY=xai-...
+export GROQ_API_KEY=gsk_...
+export DEEPSEEK_API_KEY=sk-...
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+After adding these, reload your shell:
+
+```bash
+source ~/.zshrc  # or source ~/.bashrc
+```
+
+**How it works:**
+- SwiftOpenAI-CLI automatically uses the **correct provider-specific key** based on the configured provider
+- When you switch to Grok, it uses `XAI_API_KEY`
+- When you switch to OpenAI, it uses `OPENAI_API_KEY`
+- No need to reconfigure keys each time
+
+### Alternative: Single API Key via Config (Not Recommended for Multiple Providers)
+
+If you only use **one provider**, you can store the key in the config file:
+
+```bash
+swiftopenai config set api-key <your-key>
+```
+
+**Limitation:** The config file only stores ONE api-key. If you switch providers, you'd need to reconfigure the key each time.
+
+### Checking Current API Key
+
+```bash
+# View current configuration (API key is masked)
+swiftopenai config list
+
+# Get specific API key setting
+swiftopenai config get api-key
+```
+
+**Priority:** Provider-specific environment variables take precedence over config file settings.
+
+## Advanced Features
+
+### Interactive Configuration
+
+For complex setups, use the interactive wizard:
+
+```bash
+swiftopenai config setup
+```
+
+This launches a guided setup that walks through:
+- Provider selection
+- API key entry
+- Model selection
+- Debug mode configuration
+- Base URL setup (if needed)
+
+### Session Management
+
+Maintain conversation context across multiple requests:
+
+```bash
+# Start a session
+swiftopenai agent "My project is a React app" --session-id project-123
+
+# Continue the session
+swiftopenai agent "What framework did I mention?" --session-id project-123
+```
+
+### MCP Tool Integration
+
+Connect to external services via Model Context Protocol:
+
+```bash
+# With GitHub MCP
+swiftopenai agent "List my repos" \
+  --mcp-servers github \
+  --allowed-tools "mcp__github__*"
+
+# With filesystem MCP
+swiftopenai agent "Read package.json and explain dependencies" \
+  --mcp-servers filesystem \
+  --allowed-tools "mcp__filesystem__*"
+
+# Multiple MCP servers
+swiftopenai agent "Complex task" \
+  --mcp-servers github,filesystem,postgres \
+  --allowed-tools "mcp__*"
+```
+
+### Output Formats
+
+Control how results are presented:
+
+```bash
+# Plain text (default)
+swiftopenai agent "Calculate 5 + 3" --output-format plain
+
+# Structured JSON
+swiftopenai agent "List 3 colors" --output-format json
+
+# Streaming JSON events (Claude SDK style)
+swiftopenai agent "Analyze data" --output-format stream-json
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: "swiftopenai: command not found"**
+
+Solution: Run the check_install_cli.sh script, which will install the CLI automatically.
+
+**Issue: Authentication errors**
+
+Solution: Verify the correct API key is set for the provider:
+
+```bash
+# Check current config
+swiftopenai config list
+
+# Set the appropriate API key
+swiftopenai config set api-key <your-key>
+
+# Or use environment variable
+export XAI_API_KEY=xai-...  # for Grok
+```
+
+**Issue: Model not available**
+
+Solution: Verify the model name matches the provider's available models. Check `references/providers.md` for correct model names or run:
+
+```bash
+swiftopenai models
+```
+
+**Issue: Rate limiting or quota errors**
+
+Solution: These are provider-specific limits. Consider:
+- Using a different model tier
+- Switching to a different provider temporarily
+- Checking your API usage dashboard
+
+### Debug Mode
+
+Enable debug mode to see detailed HTTP information:
+
+```bash
+swiftopenai config set debug true
+```
+
+This shows:
+- HTTP status codes and headers
+- API request details
+- Response metadata
+
+## Resources
+
+This skill includes bundled resources to support LLM routing:
+
+### scripts/
+
+- **check_install_cli.sh** - Ensures SwiftOpenAI-CLI is installed and up-to-date
+- **configure_provider.sh** - Configures the CLI for a specific provider
+
+### references/
+
+- **providers.md** - Comprehensive reference on all supported providers, models, configurations, and capabilities
+
+## Best Practices
+
+1. **Always check installation first** - Run `check_install_cli.sh` before routing requests
+2. **Configure provider explicitly** - Use `configure_provider.sh` to ensure correct setup
+3. **Verify API keys** - Check that the appropriate API key is set for the target provider
+4. **Choose the right model** - Match the model to the task (coding, reasoning, general chat)
+5. **Use sessions for continuity** - Leverage `--session-id` for multi-turn conversations
+6. **Enable debug mode for troubleshooting** - When issues arise, debug mode provides valuable insights
+7. **Reference provider documentation** - Consult `references/providers.md` for detailed provider information
+
+## Examples
+
+### Example 1: Routing to Grok for Real-Time Information
+
+```bash
+# User: "Use grok to tell me about recent AI developments"
+
+scripts/check_install_cli.sh
+scripts/configure_provider.sh grok grok-4-0709
+swiftopenai agent "Tell me about recent AI developments"
+```
+
+### Example 2: Using DeepSeek for Step-by-Step Reasoning
+
+```bash
+# User: "Ask deepseek to explain how to solve this algorithm problem"
+
+scripts/check_install_cli.sh
+scripts/configure_provider.sh deepseek deepseek-reasoner
+swiftopenai agent "Explain step by step how to implement quicksort"
+```
+
+### Example 3: Fast Code Generation with Groq
+
+```bash
+# User: "Use groq to quickly generate a REST API"
+
+scripts/check_install_cli.sh
+scripts/configure_provider.sh groq llama-3.3-70b-versatile
+swiftopenai agent "Generate a REST API with authentication in Python"
+```
+
+### Example 4: Accessing Claude via OpenRouter
+
+```bash
+# User: "Use openrouter to access claude and write documentation"
+
+scripts/check_install_cli.sh
+scripts/configure_provider.sh openrouter anthropic/claude-3.5-sonnet
+swiftopenai agent "Write comprehensive documentation for a todo app API"
+```
+
+### Example 5: GPT-5 with Custom Parameters
+
+```bash
+# User: "Use gpt-5 with high reasoning to solve this complex problem"
+
+scripts/check_install_cli.sh
+scripts/configure_provider.sh openai gpt-5
+swiftopenai agent "Design a distributed caching system" \
+  --model gpt-5 \
+  --reasoning high \
+  --verbose high
+```