claudish-integration

What this skill does

# Claudish Integration Skill

**Version:** 1.0.0
**Purpose:** Guide agents on how to query Claudish for OpenRouter model recommendations
**Status:** Production Ready

## Overview

This skill provides **standardized patterns** for Claude Code agents and commands to query Claudish for model recommendations. Instead of maintaining duplicate model lists, agents should query Claudish as the **single source of truth** for OpenRouter model data.

**Key Principle:** Claudish owns the model list, agents query it dynamically.

## When to Use This Skill

Use this skill when:
- ✅ Building commands that need external AI model selection (e.g., `/review`)
- ✅ Creating proxy mode agents that delegate to OpenRouter models
- ✅ Implementing multi-model validation workflows
- ✅ Building tools that need model metadata (pricing, categories, context sizes)

Do NOT use this skill when:
- ❌ Working with embedded Claude models only (Sonnet, Opus, Haiku)
- ❌ Not using external AI models
- ❌ Claudish is not available or required

## Core Patterns

### Pattern 1: Query All Models (JSON)

**Use Case:** Get complete model list for selection UI

**Implementation:**
```typescript
// Execute Claudish to get model list
const { stdout } = await Bash("claudish --top-models --json");

// Parse JSON output
const modelData = JSON.parse(stdout);

// Access models
const models = modelData.models; // Array of model objects

// Example: Extract model IDs
const modelIds = models.map(m => m.id);
// Result: ["x-ai/grok-code-fast-1", "minimax/minimax-m2", ...]
```

**Expected Output:**
```json
{
  "version": "1.1.5",
  "lastUpdated": "2025-11-16",
  "source": "shared/recommended-models.md",
  "models": [
    {
      "id": "x-ai/grok-code-fast-1",
      "name": "Grok Code Fast 1",
      "description": "Ultra-fast agentic coding with visible reasoning traces",
      "provider": "xAI",
      "category": "coding",
      "priority": 1,
      "pricing": {
        "input": "$0.20/1M",
        "output": "$1.50/1M",
        "average": "$0.85/1M"
      },
      "context": "256K",
      "recommended": true
    }
    // ... more models
  ]
}
```

### Pattern 2: Filter by Category

**Use Case:** Get models for specific use case (coding, reasoning, vision, budget)

**Categories:**
- `coding` - Fast coding models (Grok, MiniMax)
- `reasoning` - Advanced reasoning models (GPT-5, Gemini)
- `vision` - Multimodal models (Qwen)
- `budget` - Free or low-cost models (Polaris)
- `all` - All models (default)

**Implementation:**
```typescript
// Get coding models only
const { stdout } = await Bash("claudish --models coding --json");
const modelData = JSON.parse(stdout);

// Models are pre-filtered by Claudish
const codingModels = modelData.models;
// Result: Only models with category === "coding"
```

**Example: Get Best Coding Model**
```typescript
const { stdout } = await Bash("claudish --models coding --json");
const modelData = JSON.parse(stdout);

// First model is highest priority (sorted by priority field)
const bestCodingModel = modelData.models[0];
console.log(`Best coding model: ${bestCodingModel.id}`);
// Output: Best coding model: x-ai/grok-code-fast-1
```

### Pattern 3: User Overrides from CLAUDE.md

**Use Case:** Allow users to specify preferred models in project configuration

**CLAUDE.md Format:**
```markdown
## Claudish Configuration

**Recommended Models for Code Review:**
- x-ai/grok-code-fast-1
- google/gemini-2.5-flash
- openai/gpt-5.1-codex

**Model Categories:**
- coding: grok, minimax
- reasoning: gpt-5, gemini
```

**Implementation:**
```typescript
async function getRecommendedModels() {
  // 1. Check for user override in CLAUDE.md
  const userModels = await readUserOverrideFromClaudeMd();
  if (userModels) {
    console.log("Using models from CLAUDE.md");
    return userModels;
  }

  // 2. Query Claudish for defaults
  const { stdout } = await Bash("claudish --models coding --json");
  const modelData = JSON.parse(stdout);
  return modelData.models;
}

async function readUserOverrideFromClaudeMd(): Promise<Model[] | null> {
  try {
    const claudeMd = await Read({ file_path: "/full/path/to/CLAUDE.md" });

    // Look for "Recommended Models for Code Review:" section
    const match = claudeMd.match(/Recommended Models for Code Review:(.*?)(?=\n\n|$)/s);
    if (!match) return null;

    // Extract model IDs
    const modelIds = match[1]
      .split("\n")
      .filter(line => line.trim().startsWith("-"))
      .map(line => line.replace(/^-\s*/, "").trim());

    if (modelIds.length === 0) return null;

    // Query Claudish for details on these specific models
    const { stdout } = await Bash("claudish --top-models --json");
    const modelData = JSON.parse(stdout);

    // Filter to user-specified models
    return modelData.models.filter(m => modelIds.includes(m.id));
  } catch (error) {
    console.warn("Could not read CLAUDE.md:", error.message);
    return null;
  }
}
```

### Pattern 4: Graceful Fallback to Embedded Defaults

**Use Case:** Handle errors when Claudish is not available

**Implementation:**
```typescript
// Define embedded defaults as fallback
const EMBEDDED_DEFAULT_MODELS = [
  {
    id: "x-ai/grok-code-fast-1",
    name: "Grok Code Fast 1",
    description: "Ultra-fast agentic coding",
    category: "coding",
    priority: 1
  },
  {
    id: "google/gemini-2.5-flash",
    name: "Gemini 2.5 Flash",
    description: "State-of-the-art reasoning and coding",
    category: "reasoning",
    priority: 2
  },
  {
    id: "openai/gpt-5.1-codex",
    name: "GPT-5.1 Codex",
    description: "Specialized for software engineering",
    category: "reasoning",
    priority: 3
  }
];

async function getRecommendedModels() {
  // 1. Check for user override
  const userModels = await readUserOverrideFromClaudeMd();
  if (userModels) return userModels;

  // 2. Try querying Claudish
  try {
    const { stdout } = await Bash("claudish --top-models --json");
    const modelData = JSON.parse(stdout);
    return modelData.models;
  } catch (error) {
    // 3. Graceful fallback
    console.warn("Could not query Claudish, using embedded defaults");
    console.warn(`Reason: ${error.message}`);
    return EMBEDDED_DEFAULT_MODELS;
  }
}
```

### Pattern 5: Version Detection

**Use Case:** Check if Claudish supports JSON output (v1.2.0+)

**Implementation:**
```typescript
async function checkClaudishVersion(): Promise<{ major: number; minor: number; patch: number } | null> {
  try {
    const { stdout } = await Bash("claudish --version");
    const match = stdout.match(/(\d+)\.(\d+)\.(\d+)/);
    if (!match) return null;

    return {
      major: parseInt(match[1]),
      minor: parseInt(match[2]),
      patch: parseInt(match[3])
    };
  } catch {
    return null;
  }
}

async function isClaudishJsonSupported(): Promise<boolean> {
  const version = await checkClaudishVersion();
  if (!version) {
    console.warn("Claudish not found");
    return false;
  }

  // JSON support added in 1.2.0
  const isSupported = version.major >= 1 && version.minor >= 2;

  if (!isSupported) {
    console.warn(`Claudish v${version.major}.${version.minor}.${version.patch} detected`);
    console.warn("JSON output requires Claudish v1.2.0+");
    console.warn("Upgrade: npm install -g claudish@latest");
  }

  return isSupported;
}

async function getRecommendedModels() {
  // Check Claudish version before querying
  const jsonSupported = await isClaudishJsonSupported();

  if (!jsonSupported) {
    console.warn("Falling back to embedded defaults");
    return EMBEDDED_DEFAULT_MODELS;
  }

  // Proceed with JSON query
  const { stdout } = await Bash("claudish --top-models --json");
  return JSON.parse(stdout).models;
}
```

## Complete Example: Multi-Model Selection

**Use Case:** `/review` command selects multiple models for parallel code review

**Implementation:**
```typescript
async function selectModelsForReview() {
  // Step 1: Get available models
  const availableModels = await getRecommendedModels(); // U