Skillzwave Logo
Skillzwave

Configuration

Skilz can be configured to customize agent paths, installation behavior, and default settings. This guide covers common configuration scenarios with working examples.

Remember: Install Skilz first with pip install skilz before configuring.

Configuration File

Skilz looks for configuration at:

~/.config/skilz/config.json

Create the directory if it doesn't exist:

mkdir -p ~/.config/skilz

Basic Configuration Example

Create a config file at ~/.config/skilz/config.json:

{
  "default_skills_dir": "~/.claude/skills"
}

Adding Custom Agents

Skilz supports 22+ agents out of the box, but you can add custom agents by defining their configuration: 

{
  "agents": {
    "my_custom_agent": {
      "display_name": "My Custom Agent",
      "home_dir": "~/.my-agent/skills",
      "project_dir": ".my-agent/skills",
      "config_files": ["AGENT.md"],
      "supports_home": true,
      "default_mode": "copy",
      "native_skill_support": "none"
    }
  }
}

Then use it:

pip install skilz
skilz install anthropics_skills/theme-factory --agent my_custom_agent

Built-in Agent Paths

Here are the default paths for agents with home support:

Agent Home Path Project Path
claude ~/.claude/skills .claude/skills
opencode ~/.config/opencode/skills .skilz/skills
codex ~/.codex/skills .codex/skills
universal ~/.skilz/skills .skilz/skills

See Supported Agents for all 22+ agents including project-only agents.

Custom Agent Configuration Schema

When defining a custom agent, these fields are available:

Field Type Description
display_name string Human-readable name (required)
home_dir string | null User-level skills path (null for project-only)
project_dir string Project-level skills path (required)
config_files array Files to sync skill metadata
supports_home boolean Whether home installation is supported
default_mode "copy" | "symlink" Installation mode (required)
native_skill_support "all" | "home" | "none" Native skill support level

Installation Mode

Agents can install skills by copying files or creating symlinks:

{
  "agents": {
    "my_agent": {
      "display_name": "My Agent",
      "project_dir": ".my-agent/skills",
      "default_mode": "copy",
      "supports_home": false,
      "native_skill_support": "none"
    }
  }
}
  • "copy" — Copies skill files (default, more reliable)
  • "symlink" — Creates symbolic links (saves space, updates automatically)

Note: Symlinks may not work in all environments (e.g., some sandboxed setups). Use copy mode if you encounter issues.

Project-Only Agent Example

For agents that don't support user-level installation:

{
  "agents": {
    "project_only_agent": {
      "display_name": "Project Only Agent",
      "home_dir": null,
      "project_dir": ".project-agent/skills",
      "config_files": [],
      "supports_home": false,
      "default_mode": "copy",
      "native_skill_support": "none"
    }
  }
}

Environment Variables

Some settings can be overridden with environment variables:

Variable Description
AGENT_DEFAULT Override default agent (claude or opencode)
CLAUDE_CODE_HOME Override Claude Code home directory
OPEN_CODE_HOME Override OpenCode home directory
pip install skilz
# Use environment variables
export AGENT_DEFAULT=opencode
skilz install anthropics_skills/theme-factory

Next Steps