Troubleshooting

Installation Issues

Skills Not Showing in Claude Code

Symptoms:

• Claude doesn't recognize SkillBoss skills
• Skills not listed in /skills command

Solutions:

Quick setup for AI agents: Tell your agent set up skillboss.co/skill.md to auto-configure everything.

# Verify skills are in the correct location
ls -la ~/.claude/skills/skillboss/

# Should show multiple .md files

# Fix permissions if needed
chmod -R 755 ~/.claude/skills/skillboss/

---
name: skillboss_ai_complete
description: Call AI models
---

Cursor Not Using SkillBoss

Issue: Cursor ignores SkillBoss configuration

Solutions:

1. Check .cursorrules location:

   # Should be in project root
   ls -la .cursorrules
   

2. Verify environment variable:

   # Check .env file
   cat .env | grep SKILLBOSS
   

3. Restart Cursor completely:

   • Quit Cursor
   • Reopen your project
   • Try again

Windsurf Can't Find Skills

Issue: Windsurf doesn't recognize skill files

Solutions:

1. Check Windsurf Rules path:

   • Open Windsurf Settings
   • Verify rules point to correct directory
   • Use absolute paths, not relative

2. Reload rules:

   • Open Command Palette (Cmd+Shift+P)
   • Run "Windsurf: Reload Rules"

API Authentication Issues

"Invalid API Key" Error

{
  "error": {
    "message": "Invalid API key",
    "code": "invalid_api_key"
  }
}

Common Causes & Fixes:

# ❌ Wrong
curl https://api.skillboss.co/v1/chat/completions

# ✅ Correct
curl https://api.skillboss.co/v1/chat/completions \
  -H "Authorization: Bearer sk-abc123..."

# ❌ Wrong
-H "Authorization: sk-abc123..."

# ✅ Correct (include "Bearer")
-H "Authorization: Bearer sk-abc123..."

# Clean the key
export SKILLBOSS_KEY=$(echo "sk-abc123..." | tr -d '[:space:]')

"Unauthorized" in Environment Variables

Issue: API key not loading from .env

Check:

# 1. Verify .env file exists
ls -la .env

# 2. Check contents
cat .env | grep SKILLBOSS

# 3. Ensure it's loaded
node -e "console.log(process.env.SKILLBOSS_KEY)"

Fixes:

// For Node.js, use dotenv
require('dotenv').config()

// For Next.js, ensure .env.local is in root
// and keys don't have NEXT_PUBLIC_ prefix (server-only)

// Verify it loads
console.log('Key loaded:', !!process.env.SKILLBOSS_KEY)

API Request Issues

"Insufficient Credits" Error

{
  "error": {
    "message": "Insufficient credits",
    "code": "insufficient_balance"
  }
}

Solutions:

1. Add credits:

   • Go to console
   • Purchase credits via Stripe

2. Check balance:

   curl https://api.skillboss.co/v1/models \
     -H "Authorization: Bearer YOUR_KEY"
   

   Response includes _remaining_credits field

3. Enable auto-recharge:

   • Console → Settings → Auto-Recharge
   • Set threshold and amount

"Model Not Found" Error

{
  "error": {
    "message": "Model 'claude-4-5-sonnet' does not exist",
    "code": "model_not_found"
  }
}

Common Issues:

Get full list:

curl https://api.skillboss.co/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

Rate Limit Errors

{
  "error": {
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "code": "rate_limit_exceeded",
    "retry_after": 45
  }
}

Solutions:

import time
from openai import RateLimitError

def call_with_retry(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if i == max_retries - 1:
                raise
            retry_after = int(e.response.headers.get("Retry-After", 60))
            wait = retry_after * (2 ** i)  # Exponential backoff
            time.sleep(wait)

// Add delay between requests
const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms))

for (const item of items) {
  await processItem(item)
  await delay(1000)  // 1 second between requests
}

Response Issues

Empty or Incomplete Responses

Symptom: Responses are cut off or empty

Common Causes:

1. max_tokens too low:

   // ❌ Too restrictive
   max_tokens: 10  // Can't complete thought
   
   // ✅ Appropriate
   max_tokens: 500  // Enough for full response
   

2. Context limit exceeded:

   • Claude 4.5: 200K tokens
   • GPT-4: 8-128K depending on version
   • Gemini 2.5: 1M tokens

   Check token usage in response:

   {
     "usage": {
       "prompt_tokens": 150000,
       "completion_tokens": 50,
       "total_tokens": 150050
     }
   }
   

3. Content filter triggered:

   • Response contains policy-violating content
   • Try rephrasing prompt
   • Switch to different model

Streaming Not Working

Issue: Stream returns all at once instead of incrementally

Check:

// Ensure stream: true is set
const stream = await client.chat.completions.create({
  model: 'claude-4-5-sonnet',
  messages: [{role: 'user', content: 'Hello'}],
  stream: true  // ← Must be true
})

// Iterate correctly
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || ''
  process.stdout.write(content)
}

Common mistakes:

// ❌ Wrong: Not iterating properly
const response = await stream  // Waits for everything

// ❌ Wrong: Not async iteration
stream.forEach(chunk => {...})  // Won't work

// ✅ Correct: Async iteration
for await (const chunk of stream) {...}

Performance Issues

Slow Response Times

Symptoms: Requests taking 10-30+ seconds

Diagnosis:

const start = Date.now()
const response = await client.chat.completions.create({...})
const duration = Date.now() - start
console.log(`Request took ${duration}ms`)

# Test API reachability
curl -w "@-" -o /dev/null -s \
  "https://api.skillboss.co/v1/models" <<'EOF'
time_namelookup:  %{time_namelookup}\n
time_connect:  %{time_connect}\n
time_total:  %{time_total}\n
EOF

const stream = await client.chat.completions.create({
  ...,
  stream: true
})

High Latency

For time-sensitive applications:

1. Use fastest models:

   • gemini-2.5-flash (500ms average)
   • gpt-4o-mini (800ms average)

2. Reduce max_tokens:

   max_tokens: 100  // Faster than 1000
   

3. Simplify prompts:

   • Shorter prompts = faster processing
   • Remove unnecessary context

4. Consider caching:

   • Cache frequent responses
   • Use DeepSeek with prompt caching

Billing Issues

Credits Deducted But Request Failed

Issue: Balance decreased but got an error

What happened:

• Request reached the model
• Model processed it
• Error occurred after processing (e.g., network issue during response)

Solution:

• Check the error message
• If it was a retryable error (503, network timeout), retry
• Contact dev@skillboss.co if credits were incorrectly charged

Unexpected High Costs

Diagnosis:

1. Check usage dashboard:

   • Console → Usage
   • See per-request costs

2. Common culprits:

   • Using expensive models unnecessarily
   • Large max_tokens values
   • Long conversation histories (many tokens in context)
   • Not setting max_tokens (defaults to 4096)

3. Fix:

   • Switch to cheaper models for simple tasks
   • Set appropriate max_tokens
   • Trim conversation history
   • Use prompt caching (DeepSeek)

Getting Help

Before Contacting Support

Please gather:

1. Error details:

   • Exact error message
   • HTTP status code
   • Request ID (if available)

2. Request details:

   • Model used
   • Approximate request size
   • Timestamp

3. What you've tried:

   • Steps you've already taken
   • Whether it worked before

Contact Options

Include Debug Info

// Helpful debug information to include
const debugInfo = {
  apiVersion: 'v1',
  sdkVersion: 'openai@4.x',
  model: 'claude-4-5-sonnet',
  timestamp: new Date().toISOString(),
  error: error.message,
  statusCode: error.status,
  requestId: error.headers?.['x-request-id']
}

console.error('Debug info:', JSON.stringify(debugInfo, null, 2))

Still Having Issues?