- `enabled`: set `false` to disable a skill even if it’s bundled/installed.
- `env`: environment variables injected for the agent run (only if not already set).
- `apiKey`: optional convenience for skills that declare a primary env var (e.g. `nano-banana-pro` → `GEMINI_API_KEY`).
@ -404,44 +414,27 @@ Example:
```json5
{
skills: {
"nano-banana-pro": {
apiKey: "GEMINI_KEY_HERE",
env: {
GEMINI_API_KEY: "GEMINI_KEY_HERE"
}
allowBundled: ["brave-search", "gemini"],
load: {
extraDirs: [
"~/Projects/agent-scripts/skills",
"~/Projects/oss/some-skill-pack/skills"
]
},
peekaboo: { enabled: true },
sag: { enabled: false }
}
}
```
### `skillsInstall` (installer preference)
Controls which installer is surfaced by the macOS Skills UI when a skill offers
multiple install options. Defaults to **brew when available** and **npm** for
node installs.
```json5
{
skillsInstall: {
preferBrew: true,
nodeManager: "npm" // npm | pnpm | yarn
}
}
```
### `skillsLoad`
Additional skill directories to scan (lowest precedence). This is useful if you keep skills in a separate repo but want Clawdis to pick them up without copying them into the workspace.
- The app calls `skills.install` to run installers on the gateway host.
- The gateway surfaces only one preferred installer when multiple are provided (brew when available, otherwise node manager from `skillsInstall`, default npm).
- The gateway surfaces only one preferred installer when multiple are provided
(brew when available, otherwise node manager from `skills.install`, default npm).
## Env/API keys
- The app stores keys in `~/.clawdis/clawdis.json` under `skills.<skillKey>`.
- The app stores keys in `~/.clawdis/clawdis.json` under `skills.entries.<skillKey>`.
- `skills.update` patches `enabled`, `apiKey`, and `env`.
If no `metadata.clawdis` is present, the skill is always eligible (unless disabled in config).
If no `metadata.clawdis` is present, the skill is always eligible (unless
disabled in config or blocked by `skills.allowBundled` for bundled skills).
## Config overrides (`~/.clawdis/clawdis.json`)
@ -87,33 +89,39 @@ Bundled/managed skills can be toggled and supplied with env values:
```json5
{
skills: {
"nano-banana-pro": {
enabled: true,
apiKey: "GEMINI_KEY_HERE",
env: {
GEMINI_API_KEY: "GEMINI_KEY_HERE"
}
},
peekaboo: { enabled: true },
sag: { enabled: false }
entries: {
"nano-banana-pro": {
enabled: true,
apiKey: "GEMINI_KEY_HERE",
env: {
GEMINI_API_KEY: "GEMINI_KEY_HERE"
}
},
peekaboo: { enabled: true },
sag: { enabled: false }
}
}
}
```
Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).
Config keys match the **skill name**. We don’t require a custom `skillKey`.
Config keys match the **skill name** by default. If a skill defines
`metadata.clawdis.skillKey`, use that key under `skills.entries`.
Rules:
- `enabled: false` disables the skill even if it’s bundled/installed.
- `env`: injected **only if** the variable isn’t already set in the process.
- `apiKey`: convenience for skills that declare `metadata.clawdis.primaryEnv`.
- `allowBundled`: optional allowlist for **bundled** skills only. If set, only
bundled skills in the list are eligible (managed/workspace skills unaffected).
## Environment injection (per agent run)
When an agent run starts, Clawdis:
1) Reads skill metadata.
2) Applies any `skills.<key>.env` or `skills.<key>.apiKey` to `process.env`.
2) Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to
`process.env`.
3) Builds the system prompt with **eligible** skills.
4) Restores the original environment after the run ends.
@ -125,7 +133,14 @@ Clawdis snapshots the eligible skills **when a session starts** and reuses that
## Managed skills lifecycle
Clawdis ships a baseline set of skills as **bundled skills** as part of the install (npm package or Clawdis.app). `~/.clawdis/skills` exists for local overrides (for example, pinning/patching a skill without changing the bundled copy). Workspace skills are user-owned and override both on name conflicts.
Clawdis ships a baseline set of skills as **bundled skills** as part of the
install (npm package or Clawdis.app). `~/.clawdis/skills` exists for local
overrides (for example, pinning/patching a skill without changing the bundled
copy). Workspace skills are user-owned and override both on name conflicts.
## Config reference
See `docs/skills-config.md` for the full configuration schema.