feat: add managed skills gating

docs/agent.md

@@ -29,6 +29,14 @@ If a file is missing, CLAWDIS injects a single “missing file” marker line (a
 
 Pi’s embedded core tools (read/bash/edit/write and related internals) are defined in code and always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.
 
+## Skills
+
+Clawdis loads skills from two locations (workspace wins on name conflict):
+- Managed: `~/.clawdis/skills`
+- Workspace: `<workspace>/skills`
+
+Managed skills can be gated by config/env (see `skills.*` in `docs/configuration.md`).
+
 ## Sessions
 
 Session transcripts are stored as JSONL at:

docs/configuration.md

@@ -131,6 +131,32 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 }
 ```
 
+### `skills` (managed skills config/env)
+
+Configure **managed** skills (loaded from `~/.clawdis/skills`). Workspace skills always win on name conflicts.
+
+Common fields per skill:
+- `enabled`: set `false` to disable a managed skill even if it’s 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`).
+
+Example:
+
+```json5
+{
+  skills: {
+    "nano-banana-pro": {
+      apiKey: "GEMINI_KEY_HERE",
+      env: {
+        GEMINI_API_KEY: "GEMINI_KEY_HERE"
+      }
+    },
+    peekaboo: { enabled: true },
+    sag: { enabled: false }
+  }
+}
+```
+
 ### `browser` (clawd-managed Chrome)
 
 Clawdis can start a **dedicated, isolated** Chrome/Chromium instance for clawd and expose a small loopback control server.

docs/index.md

@@ -116,6 +116,7 @@ Example:
 - Start here:
   - [Configuration](./configuration.md)
   - [Clawd personal assistant setup](./clawd.md)
+  - [Skills](./skills.md)
   - [Workspace templates](./templates/AGENTS.md)
   - [Gateway runbook](./gateway.md)
   - [Nodes (iOS/Android)](./nodes.md)

docs/skills.md

@@ -0,0 +1,107 @@
+---
+summary: "Skills: managed vs workspace, gating rules, and config/env wiring"
+read_when:
+  - Adding or modifying skills
+  - Changing skill gating or load rules
+---
+<!-- {% raw %} -->
+# Skills (Clawdis)
+
+Clawdis uses **AgentSkills-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Clawdis loads **managed skills** plus **workspace skills**, and filters them at load time based on environment, config, and binary presence.
+
+## Locations and precedence
+
+Skills are loaded from **two** places:
+
+1) **Managed skills**: `~/.clawdis/skills`
+2) **Workspace skills**: `<workspace>/skills`
+
+If a skill name conflicts, the **workspace** version wins (user overrides managed).
+
+## Format (AgentSkills + Pi-compatible)
+
+`SKILL.md` must include at least:
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+---
+```
+
+Notes:
+- We follow the AgentSkills spec for layout/intent.
+- The parser used by the embedded agent supports **single-line** frontmatter keys only.
+- `metadata` should be a **single-line JSON object**.
+- Use `{baseDir}` in instructions to reference the skill folder path.
+
+## Gating (load-time filters)
+
+Clawdis **filters skills at load time** using `metadata` (single-line JSON):
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+metadata: {"clawdis":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
+---
+```
+
+Fields under `metadata.clawdis`:
+- `always: true` — always include the skill (skip other gates).
+- `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`.
+
+If no `metadata.clawdis` is present, the skill is always eligible (unless disabled in config).
+
+## Config overrides (`~/.clawdis/clawdis.json`)
+
+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 }
+  }
+}
+```
+
+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`.
+
+Rules:
+- `enabled: false` disables the managed skill even if installed.
+- `env`: injected **only if** the variable isn’t already set in the process.
+- `apiKey`: convenience for skills that declare `metadata.clawdis.primaryEnv`.
+
+## 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`.
+3) Builds the system prompt with **eligible** skills.
+4) Restores the original environment after the run ends.
+
+This is **scoped to the agent run**, not a global shell environment.
+
+## Session snapshot (performance)
+
+Clawdis snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
+
+## Managed skills lifecycle
+
+Managed skills are owned by Clawdis (not user-editable). Workspace skills are user-owned and override managed ones by name. The macOS app or installer should copy bundled skills into `~/.clawdis/skills` on install/update.
+
+---
+<!-- {% endraw %} -->