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(); // Uses patterns above
// Step 2: Filter to coding/reasoning models
const suitableModels = availableModels.filter(m =>
m.category === "coding" || m.category === "reasoning"
);
// Step 3: Present selection UI to user (example)
console.log("\nAvailable models for code review:\n");
suitableModels.forEach((model, index) => {
console.log(`${index + 1}. ${model.name}`);
console.log(` ${model.description}`);
console.log(` Category: ${model.category} | Cost: ${model.pricing.average}\n`);
});
// Step 4: User selects models (implementation depends on command)
const selectedIndices = await promptUserForSelection();
// Step 5: Return selected models
return selectedIndices.map(i => suitableModels[i]);
}
async function getRecommendedModels() {
// 1. User override
const userModels = await readUserOverrideFromClaudeMd();
if (userModels) return userModels;
// 2. Claudish query (with version check)
const jsonSupported = await isClaudishJsonSupported();
if (jsonSupported) {
try {
const { stdout } = await Bash("claudish --top-models --json");
return JSON.parse(stdout).models;
} catch (error) {
console.warn("Claudish query failed:", error.message);
}
}
// 3. Fallback
console.warn("Using embedded default models");
return EMBEDDED_DEFAULT_MODELS;
}
Error Handling
Error 1: Claudish Not Installed
Detection:
typescript
try {
await Bash("which claudish");
} catch {
console.warn("Claudish not installed");
}
Fallback:
typescript
console.warn("Claudish not found. Using embedded default models.");
console.warn("To use dynamic model lists, install: npm install -g claudish");
return EMBEDDED_DEFAULT_MODELS;
Error 2: Claudish Version Too Old
Detection:
typescript
const version = await checkClaudishVersion();
const isOld = version && (version.major < 1 || version.minor < 2);
Fallback:
typescript
console.warn(`Claudish v${version.major}.${version.minor}.${version.patch} detected`);
console.warn("JSON output requires v1.2.0+");
console.warn("Upgrade: npm install -g claudish@latest");
console.warn("Falling back to embedded defaults");
return EMBEDDED_DEFAULT_MODELS;
Error 3: JSON Parse Error
Detection:
typescript
try {
const data = JSON.parse(stdout);
} catch (error) {
console.error("Invalid JSON from Claudish:", error.message);
}
Fallback:
typescript
console.error("Could not parse Claudish output");
console.error("Expected JSON format from: claudish --top-models --json");
console.warn("Falling back to embedded defaults");
return EMBEDDED_DEFAULT_MODELS;
Error 4: Empty Model List
Detection:
typescript
const data = JSON.parse(stdout);
if (!data.models || data.models.length === 0) {
console.warn("No models returned from Claudish");
}
Fallback:
typescript
console.warn("Claudish returned empty model list");
console.warn("Try: claudish --models --force-update");
console.warn("Falling back to embedded defaults");
return EMBEDDED_DEFAULT_MODELS;
Error 5: Command Execution Failure
Detection:
typescript
try {
const { stdout } = await Bash("claudish --top-models --json");
} catch (error) {
console.error("Failed to execute Claudish:", error.message);
}
Fallback:
typescript
console.error("Could not execute: claudish --top-models --json");
console.error(`Error: ${error.message}`);
console.warn("Falling back to embedded defaults");
return EMBEDDED_DEFAULT_MODELS;
Best Practices
1. Always Provide Embedded Defaults
Why: Graceful degradation when Claudish unavailable
How:
typescript
const EMBEDDED_DEFAULT_MODELS = [
// Minimum viable model list
{ id: "x-ai/grok-code-fast-1", name: "Grok", category: "coding" },
{ id: "google/gemini-2.5-flash", name: "Gemini", category: "reasoning" },
{ id: "openai/gpt-5.1-codex", name: "GPT-5 Codex", category: "reasoning" }
];