Discovery Provider Configuration¶

SkillMeat's artifact discovery system (Enhanced and Agent modes) supports three LLM providers: Claude, OpenAI, and Ollama. This guide covers setup, authentication, cost estimation, and troubleshooting for each provider.

For general discovery usage, see Artifact Discovery Guide.

Quick Reference¶

Provider	Best For	Setup Time	Cost	Agent Mode
Claude	Best accuracy, native agent support, subscription OAuth	5 min	~$0.05–0.15/1k calls	Yes (native)
OpenAI	Familiar API, GPT-4 models	5 min	~$0.08–0.25/1k calls	No (tool-calling emulation)
Ollama	Offline, self-hosted, free	10 min (model pull)	Free	No

Claude (Anthropic)¶

Claude is the recommended provider for discovery, especially for Agent mode. Two authentication options are available:

Option 1: API Key (Direct Authentication)¶

When to use: Quick setup, testing, or if you don't have a subscription.

Requirements: - Anthropic API account - Claude API key from console.anthropic.com/keys

Setup:

# Get your API key from console.anthropic.com/keys
export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude
export SKILLMEAT_DISCOVERY_LLM_MODEL=claude-sonnet-4-6
export ANTHROPIC_API_KEY=sk-ant-...

Verify:

# Test enhanced mode
skillmeat discover "test query" --mode enhanced

# Test agent mode (if enabled)
export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true
skillmeat discover "test query" --mode agent

Cost Estimate:

Using claude-sonnet-4-6: - Input: $3 per 1M tokens - Output: $15 per 1M tokens - Per discovery call: ~100–500 tokens input, ~200–1000 tokens output - Rough per 1k calls: $0.05–0.15 (assuming mixed enrichment/reranking)

Models Available: - claude-opus-4-1 (most capable, higher cost) - claude-sonnet-4-6 (recommended balance) - claude-haiku-4-5 (fastest, lower cost)

Override model:

export SKILLMEAT_DISCOVERY_LLM_MODEL=claude-haiku-4-5

Option 2: Subscription OAuth (Recommended for Agent Mode)¶

When to use: Agent mode, higher rate limits, cost efficiency with Claude subscription.

Requirements: - Claude subscription active in Claude Code - System keychain configured

Setup (automatic):

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude
export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true
# CLAUDE_CODE_OAUTH_TOKEN is read automatically from system keychain

No manual token export needed — the system keychain is checked automatically.

Verify:

# Test agent mode
skillmeat discover "complex multi-step workflow" --mode agent

Cost Estimate:

With Claude subscription: - Typically 20–30% lower cost than API key usage - Automatically managed rate limits - No explicit token per-call pricing; tied to subscription

Fallback Behavior:

If subscription token is unavailable or expired, the system automatically falls back to ANTHROPIC_API_KEY if present. If neither is available, agent mode returns an error with guidance.

Keychain Integration:

The system automatically resolves Claude subscription tokens from the OS keychain. No manual configuration is required — just ensure your Claude Code environment has subscription active.

Troubleshooting OAuth:

Token not found: Ensure Claude Code subscription is active and the keychain is unlocked
Token expired: Refresh subscription in Claude Code settings
Fallback to API key: If keychain fails, make sure ANTHROPIC_API_KEY is set

OpenAI¶

OpenAI models work well for enhanced discovery (keyword enrichment + reranking) but do not support native agent mode.

Setup¶

Requirements: - OpenAI account - API key from platform.openai.com/keys

Configuration:

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=openai
export SKILLMEAT_DISCOVERY_LLM_MODEL=gpt-4o
export OPENAI_API_KEY=sk-...

Or discovery-specific key:

export SKILLMEAT_DISCOVERY_LLM_API_KEY=sk-...
# Falls back to OPENAI_API_KEY if SKILLMEAT_DISCOVERY_LLM_API_KEY is not set

Verify:

# Test enhanced mode
skillmeat discover "pdf processing tool" --mode enhanced

# Agent mode will fail with helpful error
skillmeat discover "test" --mode agent
# Error: Tier 3 (agentic discovery) requires a provider with agent_mode='native'...

Models¶

Recommended: - gpt-4o (latest, good balance) - gpt-4-turbo (default if SKILLMEAT_DISCOVERY_LLM_MODEL unset) - gpt-3.5-turbo (fastest, lower cost)

Override:

export SKILLMEAT_DISCOVERY_LLM_MODEL=gpt-4

Cost Estimate¶

Using gpt-4o: - Input: $2.50 per 1M tokens - Output: $10 per 1M tokens - Per discovery call: ~100–500 tokens input, ~200–1000 tokens output - Rough per 1k calls: $0.08–0.25

Using gpt-3.5-turbo (budget option): - Input: $0.50 per 1M tokens - Output: $1.50 per 1M tokens - Rough per 1k calls: $0.02–0.05

Custom Endpoints (Azure OpenAI, Proxies)¶

For Azure OpenAI or custom deployments, use LiteLLM environment variables:

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=openai
export SKILLMEAT_DISCOVERY_LLM_MODEL=gpt-4o
# LiteLLM proxy URL
export OPENAI_API_BASE=https://your-instance.openai.azure.com
export OPENAI_API_VERSION=2023-05-15
export OPENAI_API_KEY=your-azure-key

Ollama (Local / Self-Hosted)¶

Use Ollama for offline discovery or to avoid API costs. Ollama does not support agent mode.

Setup¶

Requirements: - Ollama running locally (or on network) - Model pulled locally (see "Model Selection" below)

Install Ollama:

# macOS / Linux / Windows
# Download from https://ollama.ai

Start Ollama server:

ollama serve
# Listens on http://localhost:11434 by default

Configuration:

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=ollama
export SKILLMEAT_DISCOVERY_LLM_MODEL=llama2
# Optional: custom base URL
# export SKILLMEAT_DISCOVERY_LLM_BASE_URL=http://custom-host:11434

Model Selection¶

Pull a model first:

# Recommended: llama2 (default, balanced)
ollama pull llama2

# Other options
ollama pull mistral      # Faster, fewer params
ollama pull neural-chat  # Optimized for chat
ollama pull phi3         # Small, efficient
ollama pull openchat     # Community-focused

List available models:

ollama list

Use a specific model:

export SKILLMEAT_DISCOVERY_LLM_MODEL=mistral
skillmeat discover "test query" --mode enhanced

Verify¶

# Test ollama connectivity
curl http://localhost:11434/api/generate \
  -d '{"model":"llama2","prompt":"hello","stream":false}'

# Test discovery
skillmeat discover "artifact search" --mode enhanced

Cost Estimate¶

Offline, completely free (once models are downloaded locally).

Hardware: Typical Ollama models (7B–13B params) require: - 8–16 GB RAM - CPU-friendly (runs on CPU, but slower; GPU accelerated if available) - Latency: 5–30 seconds per call (model-dependent)

Custom Base URL¶

For Ollama on a different host:

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=ollama
export SKILLMEAT_DISCOVERY_LLM_BASE_URL=http://llm-server:11434
export SKILLMEAT_DISCOVERY_LLM_MODEL=llama2

Configuration Keys Reference¶

Environment Variable	Required	Applies To	Description
`SKILLMEAT_DISCOVERY_LLM_PROVIDER`	Yes (discovery)	All	Provider name: `claude`, `openai`, or `ollama`
`SKILLMEAT_DISCOVERY_LLM_MODEL`	No	All	Override model name (uses provider default if unset)
`ANTHROPIC_API_KEY`	Yes (Claude API key)	Claude	API key for direct authentication
`CLAUDE_CODE_OAUTH_TOKEN`	No (auto-resolved)	Claude agent	Subscription OAuth token (read from keychain automatically)
`OPENAI_API_KEY`	Yes (OpenAI)	OpenAI	OpenAI API key
`SKILLMEAT_DISCOVERY_LLM_API_KEY`	No (OpenAI)	OpenAI	Override key for OpenAI (higher priority)
`SKILLMEAT_DISCOVERY_LLM_BASE_URL`	No (Ollama)	Ollama	Ollama server base URL (default: `http://localhost:11434`)
`SKILLMEAT_DISCOVERY_AGENT_ENABLED`	No	Agent mode	Enable Tier 3 agentic discovery (`true`/`false`)
`SKILLMEAT_DISCOVERY_AGENT_MAX_TURNS`	No	Agent mode	Max agent reasoning turns: 1–10 (default: 5)
`SKILLMEAT_DISCOVERY_LLM_RERANK_ENABLED`	No	Enhanced mode	Enable LLM reranking in enhanced mode (default: `true`)

Troubleshooting¶

"Provider 'claude' not found"¶

Cause: SKILLMEAT_DISCOVERY_LLM_PROVIDER is misspelled or missing.

Fix:

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude
# Verify
echo $SKILLMEAT_DISCOVERY_LLM_PROVIDER

"AuthenticationError" or "Unauthorized"¶

Cause: Invalid or missing API key.

Fix: 1. Verify the key is correct:

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

2. Test the provider directly: - Claude: curl https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" ... - OpenAI: curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY" - Ollama: curl http://localhost:11434/api/generate ...

"LLM provider unreachable"¶

Cause: Network connectivity or provider is down.

Fix: - Claude/OpenAI: Check internet connection; check provider status pages - Ollama: Ensure ollama serve is running and accessible

curl http://localhost:11434
# Should return HTML error or JSON response, not connection refused

"Tier 3 (agentic discovery) requires a provider with agent_mode='native'"¶

Cause: Using OpenAI or Ollama with agent mode enabled.

Fix: Agent mode only works with Claude:

# Switch to Claude
export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude
export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true

# Or disable agent mode
unset SKILLMEAT_DISCOVERY_AGENT_ENABLED

High token usage or slow responses¶

Claude API key: Tokens-in/out are charged per call. Normal usage: - Enhanced mode: ~100–300 tokens input, ~200–500 output per call - Agent mode: ~500–2000 tokens per turn (6 turns default)

Reduce cost: - Switch to subscription OAuth (Claude) for better rates - Use cheaper model: export SKILLMEAT_DISCOVERY_LLM_MODEL=claude-haiku-4-5 - Reduce agent turns: export SKILLMEAT_DISCOVERY_AGENT_MAX_TURNS=3 - Disable reranking: export SKILLMEAT_DISCOVERY_LLM_RERANK_ENABLED=false

OpenAI: Use gpt-3.5-turbo instead of gpt-4o to reduce costs.

Ollama: No cost, but ensure hardware is adequate (8+ GB RAM for smooth operation).

"Model not found" or "Unknown model" (Ollama)¶

Cause: Model is not pulled locally.

Fix:

ollama pull llama2
# Or pull the model you want
ollama pull mistral
ollama list  # Verify it's available

"Connection refused" or "ECONNREFUSED" (Ollama)¶

Cause: Ollama server is not running or on the wrong host.

Fix:

# Start Ollama (if using default localhost)
ollama serve

# Or check custom host
export SKILLMEAT_DISCOVERY_LLM_BASE_URL=http://your-server:11434
curl http://your-server:11434  # Should respond

"SKILLMEAT_DISCOVERY_LLM_MODEL is set but empty"¶

Cause: Environment variable is set to empty string.

Fix:

unset SKILLMEAT_DISCOVERY_LLM_MODEL
# Or set to a valid model
export SKILLMEAT_DISCOVERY_LLM_MODEL=claude-sonnet-4-6

Environment Variable Priority (Authentication)¶

Claude¶

OS Keychain → CLAUDE_CODE_OAUTH_TOKEN (agent mode, automatic)
Environment variable → ANTHROPIC_API_KEY

If using agent mode, the keychain is checked first. Set ANTHROPIC_API_KEY as fallback for API key auth.

OpenAI¶

SKILLMEAT_DISCOVERY_LLM_API_KEY (discovery-specific)
OPENAI_API_KEY (standard fallback)

At least one must be set; missing keys raise ConfigError.

Ollama¶

No API key required. Uses SKILLMEAT_DISCOVERY_LLM_BASE_URL to locate server (default: http://localhost:11434).

Switching Providers¶

To change providers mid-session:

# From Claude to OpenAI
export SKILLMEAT_DISCOVERY_LLM_PROVIDER=openai
export SKILLMEAT_DISCOVERY_LLM_MODEL=gpt-4o
export OPENAI_API_KEY=sk-...
unset SKILLMEAT_DISCOVERY_AGENT_ENABLED  # Agent mode won't work

# Verify
skillmeat discover "test" --mode enhanced

Performance Notes¶

Provider	Latency	Streaming	Concurrent Calls	Best Use
Claude	1–3s	Yes	High	Production, agent mode
OpenAI	1–3s	Yes	High	Production (enhanced only)
Ollama	5–30s	Yes	Limited by hardware	Offline, testing, free

Discovery Provider Configuration¶

Quick Reference¶

Claude (Anthropic)¶

Option 1: API Key (Direct Authentication)¶

Option 2: Subscription OAuth (Recommended for Agent Mode)¶

OpenAI¶

Setup¶

Models¶

Cost Estimate¶

Custom Endpoints (Azure OpenAI, Proxies)¶

Ollama (Local / Self-Hosted)¶

Setup¶

Model Selection¶

Verify¶

Cost Estimate¶

Custom Base URL¶

Configuration Keys Reference¶

Troubleshooting¶

"Provider 'claude' not found"¶

"AuthenticationError" or "Unauthorized"¶

"LLM provider unreachable"¶

"Tier 3 (agentic discovery) requires a provider with agent_mode='native'"¶

High token usage or slow responses¶

"Model not found" or "Unknown model" (Ollama)¶

"Connection refused" or "ECONNREFUSED" (Ollama)¶

"SKILLMEAT_DISCOVERY_LLM_MODEL is set but empty"¶

Environment Variable Priority (Authentication)¶

Claude¶

OpenAI¶

Ollama¶

Switching Providers¶

Performance Notes¶

See Also¶