Configuration Reference

Complete reference for all Skilz configuration options. This documents every field, type, and validation rule in the configuration schema.

Configuration file location: ~/.config/skilz/config.json. See Configuration Guide for working examples.

Schema Overview

{
  "default_skills_dir": "string (path)",
  "agents": {
    "<agent_id>": {
      "display_name": "string",
      "home_dir": "string | null",
      "project_dir": "string",
      "config_files": ["array of strings"],
      "supports_home": "boolean",
      "default_mode": "copy | symlink",
      "native_skill_support": "all | home | none"
    }
  }
}

Root Fields

default_skills_dir

Type	string
Default	`~/.claude/skills`
Required	No

Default directory used as symlink source for project-level installs.

Built-in Agents

Skilz includes 22+ built-in agents. You can override their configuration or add new agents.

Agents with Home Support

These agents support both user-level and project-level installation:

claude | opencode | codex | universal

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

Project-Only Agents

These agents only support project-level installation (home_dir is null):

gemini | copilot | cursor | windsurf | aider | zed | qwen | kimi | crush | plandex

Agent	Project Dir
`gemini`	`.skilz/skills`
`copilot`	`.github/copilot/skills`
`cursor`	`.skills/skills`
`windsurf`	`.skills/skills`
`aider`	`.skills/skills`
`zed`	`.skills/skills`
`qwen`	`.skills/skills`
`kimi`	`.skills/skills`
`crush`	`.skills/skills`
`plandex`	`.skills/skills`

agents (Custom/Override)

Define custom AI agents or override built-in agent configuration.

Type	object
Required	No

Agent Config Schema

{
  "agents": {
    "<agent_id>": {
      "display_name": "string",       // Required - Human-readable name
      "home_dir": "string | null",    // User-level path (null for project-only)
      "project_dir": "string",        // Required - Project-level path
      "config_files": ["strings"],    // Files to sync metadata
      "supports_home": boolean,       // Whether home install is supported
      "default_mode": "copy|symlink", // Required - Installation mode
      "native_skill_support": "all|home|none", // Native support level
      "uses_folder_rules": boolean,   // Uses folder-based rules (like Cursor)
      "invocation": "string"          // How skills are invoked (docs only)
    }
  }
}

Field Details

Field	Type	Required	Default
`display_name`	string	Yes	—
`home_dir`	string \| null	No	`null`
`project_dir`	string	Yes	—
`config_files`	array	No	`[]`
`supports_home`	boolean	No	`false`
`default_mode`	enum	Yes	—
`native_skill_support`	enum	No	`"none"`
`uses_folder_rules`	boolean	No	`false`
`invocation`	string	No	`null`

default_mode Values

"copy" — Copy files to destination (default, most compatible)
"symlink" — Create symbolic links (saves space, auto-updates)

native_skill_support Values

"all" — Agent natively supports skills at all levels (e.g., Claude Code)
"home" — Agent natively supports skills at user level only
"none" — Agent doesn't natively support skills (default)

Custom Agent Example

{
  "agents": {
    "my_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"
    },
    "enterprise_agent": {
      "display_name": "Enterprise AI",
      "home_dir": null,
      "project_dir": ".enterprise/skills",
      "config_files": [],
      "supports_home": false,
      "default_mode": "copy",
      "native_skill_support": "none"
    }
  }
}

Complete Example

// ~/.config/skilz/config.json - Complete configuration example
{
  "default_skills_dir": "~/.claude/skills",
  "agents": {
    "internal_agent": {
      "display_name": "Internal AI Tool",
      "home_dir": "~/.internal/skills",
      "project_dir": ".internal/skills",
      "config_files": ["INTERNAL.md"],
      "supports_home": true,
      "default_mode": "copy",
      "native_skill_support": "none"
    }
  }
}

Validation Rules

All paths must be valid filesystem paths
Home paths support ~ expansion
Agent IDs must be lowercase alphanumeric with underscores
default_mode must be "copy" or "symlink"
native_skill_support must be "all", "home", or "none"
If home_dir is null, supports_home must be false

Environment Variables

These environment variables override configuration:

Variable	Description	Example
`AGENT_DEFAULT`	Override default agent	`claude` or `opencode`
`CLAUDE_CODE_HOME`	Override Claude Code home directory	`/custom/path/.claude`
`OPEN_CODE_HOME`	Override OpenCode home directory	`/custom/path/opencode`