feat: unify skills config

2026-01-01 10:07:31 +01:00
parent 0a9f06d60f
commit fbcbc60e85
12 changed files with 287 additions and 98 deletions
--- a/docs/agent.md
+++ b/docs/agent.md
@@ -39,7 +39,7 @@ Clawdis loads skills from three locations (workspace wins on name conflict):
 - Managed/local: `~/.clawdis/skills`
 - Workspace: `<workspace>/skills`

-Skills can be gated by config/env (see `skills.*` in `docs/configuration.md`).
+Skills can be gated by config/env (see `skills` in `docs/configuration.md`).

 ## p-mono integration

--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -390,11 +390,21 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 }
 ```

-### `skills` (skill config/env)
+### `skills` (skills config)

-Configure skill toggles and env injection. Applies to **bundled** skills and `~/.clawdis/skills` (workspace skills still win on name conflicts).
+Controls bundled allowlist, install preferences, extra skill folders, and per-skill
+overrides. Applies to **bundled** skills and `~/.clawdis/skills` (workspace skills
+still win on name conflicts).

-Common fields per skill:
+Fields:
+- `allowBundled`: optional allowlist for **bundled** skills only. If set, only those
+  bundled skills are eligible (managed/workspace skills unaffected).
+- `load.extraDirs`: additional skill directories to scan (lowest precedence).
+- `install.preferBrew`: prefer brew installers when available (default: true).
+- `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn`, default: npm).
+- `entries.<skillKey>`: per-skill config overrides.
+
+Per-skill fields:
 - `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.
-
-```json5
-{
-  skillsLoad: {
-    extraDirs: [
-      "~/Projects/agent-scripts/skills",
-      "~/Projects/oss/some-skill-pack/skills"
-    ]
+    install: {
+      preferBrew: true,
+      nodeManager: "npm"
+    },
+    entries: {
+      "nano-banana-pro": {
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        }
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false }
+    }
  }
 }
 ```
--- a/docs/index.md
+++ b/docs/index.md
@@ -119,6 +119,7 @@ Example:
  - [Nix mode](./nix.md)
  - [Clawd personal assistant setup](./clawd.md)
  - [Skills](./skills.md)
+  - [Skills config](./skills-config.md)
  - [Workspace templates](./templates/AGENTS.md)
  - [Gateway runbook](./gateway.md)
  - [Nodes (iOS/Android)](./nodes.md)
--- a/docs/mac/skills.md
+++ b/docs/mac/skills.md
@@ -9,16 +9,18 @@ read_when:
 The macOS app surfaces Clawdis skills via the gateway; it does not parse skills locally.

 ## Data source
- `skills.status` (gateway) returns all skills plus eligibility and missing requirements.
+- `skills.status` (gateway) returns all skills plus eligibility and missing requirements
+  (including allowlist blocks for bundled skills).
 - Requirements are derived from `metadata.clawdis.requires` in each `SKILL.md`.

 ## Install actions
 - `metadata.clawdis.install` defines install options (brew/node/go/uv).
 - 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`.

 ## Remote mode
--- a/docs/skills-config.md
+++ b/docs/skills-config.md
@@ -0,0 +1,58 @@
+---
+summary: "Skills config schema and examples"
+read_when:
+  - Adding or modifying skills config
+  - Adjusting bundled allowlist or install behavior
+---
+# Skills Config
+
+All skills-related configuration lives under `skills` in `~/.clawdis/clawdis.json`.
+
+```json5
+{
+  skills: {
+    allowBundled: ["brave-search", "gemini"],
+    load: {
+      extraDirs: [
+        "~/Projects/agent-scripts/skills",
+        "~/Projects/oss/some-skill-pack/skills"
+      ]
+    },
+    install: {
+      preferBrew: true,
+      nodeManager: "npm" // npm | pnpm | yarn
+    },
+    entries: {
+      "nano-banana-pro": {
+        enabled: true,
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        }
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false }
+    }
+  }
+}
+```
+
+## Fields
+
+- `allowBundled`: optional allowlist for **bundled** skills only. When set, only
+  bundled skills in the list are eligible (managed/workspace skills unaffected).
+- `load.extraDirs`: additional skill directories to scan (lowest precedence).
+- `install.preferBrew`: prefer brew installers when available (default: true).
+- `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn`, default: npm).
+- `entries.<skillKey>`: per-skill overrides.
+
+Per-skill fields:
+- `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.
+
+## Notes
+
+- Keys under `entries` map to the skill name by default. If a skill defines
+  `metadata.clawdis.skillKey`, use that key instead.
+- Changes to skills are picked up on the next new session.
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -21,7 +21,8 @@ If a skill name conflicts, precedence is:

 `<workspace>/skills` (highest) → `~/.clawdis/skills` → bundled skills (lowest)

-Additionally, you can configure extra skill folders (lowest precedence) via `skillsLoad.extraDirs` in `~/.clawdis/clawdis.json`.
+Additionally, you can configure extra skill folders (lowest precedence) via
+`skills.load.extraDirs` in `~/.clawdis/clawdis.json`.

 ## Format (AgentSkills + Pi-compatible)

@@ -61,7 +62,7 @@ Fields under `metadata.clawdis`:
 - `requires.bins` — list; each must exist on `PATH`.
 - `requires.env` — list; env var must exist **or** be provided in config.
 - `requires.config` — list of `clawdis.json` paths that must be truthy.
- `primaryEnv` — env var name associated with `skills.<name>.apiKey`.
+- `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.
 - `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv).

 Installer example:
@@ -76,9 +77,10 @@ metadata: {"clawdis":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":

 Notes:
 - If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).
- Node installs honor `skillsInstall.nodeManager` in `clawdis.json` (default: npm; options: npm/pnpm/yarn).
+- Node installs honor `skills.install.nodeManager` in `clawdis.json` (default: npm; options: npm/pnpm/yarn).

-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.

 ---
 <!-- {% endraw %} -->