Skillzwave

Troubleshooting

This guide covers common Skilz issues, error messages, and their solutions. If you encounter a problem not listed here, please open an issue on GitHub.

Installation Issues

Command Not Found: skilz

Symptom: skilz: command not found

Causes and Solutions:

  1. Skilz not installed: 
    pip install skilz
  2. pip bin directory not in PATH: 
    # Find pip install location
python -m site --user-base

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(python -m site --user-base)/bin"
  3. Using pipx: 
    pipx ensurepath
# Restart your terminal

Python Version Error

Symptom: Python 3.10 or higher required

Solution:

# Check Python version
python --version

# Install Python 3.10+ if needed
# macOS: brew install python@3.11
# Ubuntu: sudo apt install python3.11

# Use specific Python version
python3.11 -m pip install skilz

Skill Installation Issues

Skill Not Found

Symptom: Error: Skill 'owner_repo/skill-name' not found

Causes and Solutions:

  1. Incorrect skill ID format:

    Skill IDs use underscores to separate owner and repo: owner_repo/skill-name

    pip install skilz
    # Wrong
skilz install anthropics-skills/theme-factory

# Correct
skilz install anthropics_skills/theme-factory
  2. Skill doesn't exist on GitHub:

    Verify the repository exists: https://github.com/owner/repo

  3. GitHub fallback disabled: 
    // ~/.config/skilz/config.json
{
  "registry": {
    "fallback_to_github": true
  }
}

Permission Denied

Symptom: Permission denied: ~/.claude/skills/

Solutions:

# Fix directory permissions
chmod 755 ~/.claude/skills

# Or create directory if it doesn't exist
mkdir -p ~/.claude/skills

Git Clone Failed

Symptom: Failed to clone repository

Causes and Solutions:

  1. Git not installed: 
    # Install Git
# macOS: brew install git
# Ubuntu: sudo apt install git

git --version
  2. Network issues:

    Check your internet connection and try again.

  3. Private repository: 
    # Configure SSH key
ssh -T git@github.com

# Use SSH URL in registry
git: git@github.com:owner/repo.git

Skill Loading Issues

Skill Installed but Not Loading

Symptom: Skill installed successfully but agent doesn't recognize it.

Causes and Solutions:

  1. Wrong agent selected:
    pip install skilz
    # Check where skill was installed
skilz list

# Install to correct agent
skilz install anthropics_skills/theme-factory --agent claude
  2. Symlink not followed:

    Some agents don't follow symlinks. Switch to copy mode:

    // ~/.config/skilz/config.json
{
  "agents": {
    "claude": {
      "default_mode": "copy"
    }
  }
}

# Reinstall skill
skilz install anthropics_skills/theme-factory --force
  3. Agent needs restart:

    Close and reopen your AI agent or IDE to reload skills.

  4. Invalid manifest file:
    pip install skilz
    # Check manifest exists and is valid
skilz read theme-factory --raw

Skills Directory Not Found

Symptom: Error: Skills directory does not exist

Solution:

# Create the skills directory
mkdir -p ~/.claude/skills

# Or for project-level
mkdir -p .claude/skills

Configuration Issues

Config File Not Loading

Symptom: Configuration changes not taking effect.

Causes and Solutions:

  1. Wrong config file location: 
    # User config should be at:
~/.config/skilz/config.json

# Verify it exists
cat ~/.config/skilz/config.json
  2. JSON syntax error: 
    # Validate JSON syntax
python -c "import json; json.load(open('~/.config/skilz/config.json'))"
  3. Environment variable override: 
    # Check for overriding env vars
echo $SKILZ_DEFAULT_AGENT
echo $SKILZ_CONFIG_PATH

Invalid Agent Name

Symptom: Error: Unknown agent 'myagent'

Solution:

Use a built-in agent name or define a custom agent:

# Built-in agents (14 total):
# With home support: claude, opencode, codex, universal
# Project-only: gemini, copilot, cursor, windsurf, aider, zed, qwen, kimi, crush, plandex

# Or define custom agent in config:
{
  "agents": {
    "myagent": {
      "display_name": "My Agent",
      "home_dir": "~/.myagent/skills",
      "project_dir": ".myagent/skills",
      "supports_home": true,
      "default_mode": "copy",
      "native_skill_support": "none"
    }
  }
}

Update Issues

Update Command Not Working

Symptom: skilz update reports no updates available.

Causes and Solutions:

  1. Stale cache:
    pip install skilz
    # Clear cache and reinstall
rm -rf ~/.skilz/cache
skilz install anthropics_skills/theme-factory --force
  2. Pinned version:

    If installed with --version, updates are disabled. Reinstall without version pin.

Common Error Messages

Error Cause Solution
JSON syntax error Invalid config file Check JSON syntax, use proper formatting
Connection refused Network issues Check internet, firewall, proxy settings
Repository not found Wrong repo URL or private Verify URL, configure SSH for private repos
Skill already exists Skill previously installed Use --force to reinstall
No such file or directory Missing skills directory Create directory with mkdir -p

Getting Help

Verbose Output

Enable verbose output for detailed debugging:

pip install skilz
skilz install anthropics_skills/theme-factory --verbose

Check Version

pip install skilz
skilz --version

Report Issues

If your issue isn't covered here, please report it on GitHub with:

  • Skilz version (skilz --version)
  • Python version (python --version)
  • Operating system
  • Full error message (with --verbose)
  • Steps to reproduce

Open an Issue on GitHub →

See Also