xskill.schema.json — Tool configuration
For ~/.xskill/settings.json. Defines the full configuration structure.
Top-level fields:
| Field | Type | Required | Description |
|---|---|---|---|
$schema | string | No | JSON Schema URL for editor validation. Auto-generated by config --init |
platforms | object<string, Platform> | No | Platform configurations keyed by platform identifier (e.g. "claude", "codex") |
sources | Source[] | No | Skill source repositories |
recommended | RecommendedSource[] | No | Recommended skill sets grouped by source |
cache | CacheConfig | No | Cache settings for skills list caching |
registry | RegistryConfig | No | Registry settings for skill discovery |
proxy | string | No | Proxy URL for network access (e.g. http://127.0.0.1:7890, socks5h://127.0.0.1:1080). When set, HTTP_PROXY/HTTPS_PROXY/ALL_PROXY are exported so git clone and curl/wget use the proxy. Scheme may be http, https, socks5, socks5h, socks4, socks4a. Note: socks5h/socks4a resolve DNS at the proxy. |
Platform (platforms.*):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | — | Tool config directory (relative, absolute, or ~/... path). Minimum 1 character |
skills | string | No | "" | Skills subdirectory name relative to path. Empty string skips skill installation |
agents | string | No | "" | Agents config file name relative to path. Empty string skips agents installation |
source | string | No | "AGENTS.md" | Source file name under the fixed .agents/ directory. <path>/<agents> is symlinked to .agents/<source> |
agents_compat | boolean | No | false | Whether this platform can reuse .agents/ resources. When true, reads directly from canonical directory — symlink operations are skipped |
Source (sources[]):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | No | "" | Unique source identifier. Pattern: ^[a-zA-Z0-9_/-]+$ (supports user/repo format). When empty or invalid, the url is used as the name |
type | string | No | "git" | Source type. Enum: "git", "api" |
url | string | Yes | — | Source repository URL. Must be a valid URI starting with http:// or https:// |
RecommendedSource (recommended[]):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | No | "" | Source name referencing a sources entry, or custom label |
url | string | No | "" | Direct source URL (overrides name reference when name not found in sources) |
skills | string[] | Yes | — | List of recommended skill names. Minimum 1 item |
CacheConfig (cache):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | No | false | Enable skills list caching. When enabled, query and find read from local cache |
ttl | integer | No | 86400 | Cache time-to-live in seconds (default 24 hours). Applies to both main cache (skills.json) and URL cache (source_<md5>.json). Minimum: 0 |
RegistryConfig (registry):
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | No | false | Enable registry lookup. When enabled, query and find also query the registry |
url | string | No | "https://xskill.gcli.cn/skills.json" | Registry URL. Supports bare domain, directory path, or full file path |