feat(skills): load bundled skills

docs/agent.md

@@ -31,11 +31,12 @@ Pi’s embedded core tools (read/bash/edit/write and related internals) are defi
 
 ## Skills
 
-Clawdis loads skills from two locations (workspace wins on name conflict):
-- Managed: `~/.clawdis/skills`
+Clawdis loads skills from three locations (workspace wins on name conflict):
+- Bundled (shipped with the install)
+- Managed/local: `~/.clawdis/skills`
 - Workspace: `<workspace>/skills`
 
-Managed 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`).
 
 ## Sessions
 

docs/configuration.md

@@ -131,12 +131,12 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 }
 ```
 
-### `skills` (managed skills config/env)
+### `skills` (skill config/env)
 
-Configure **managed** skills (loaded from `~/.clawdis/skills`). Workspace skills always win on name conflicts.
+Configure skill toggles and env injection. Applies to **bundled** skills and `~/.clawdis/skills` (workspace skills still win on name conflicts).
 
 Common fields per skill:
-- `enabled`: set `false` to disable a managed skill even if it’s installed.
+- `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`).
 

docs/skills.md

@@ -7,16 +7,19 @@ read_when:
 <!-- {% 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.
+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 **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
 
 ## Locations and precedence
 
-Skills are loaded from **two** places:
+Skills are loaded from **three** places:
 
-1) **Managed skills**: `~/.clawdis/skills`
-2) **Workspace skills**: `<workspace>/skills`
+1) **Bundled skills**: shipped with the install (npm package or Clawdis.app)
+2) **Managed/local skills**: `~/.clawdis/skills`
+3) **Workspace skills**: `<workspace>/skills`
 
-If a skill name conflicts, the **workspace** version wins (user overrides managed).
+If a skill name conflicts, precedence is:
+
+`<workspace>/skills` (highest) → `~/.clawdis/skills` → bundled skills (lowest)
 
 ## Format (AgentSkills + Pi-compatible)
 
@@ -58,7 +61,7 @@ If no `metadata.clawdis` is present, the skill is always eligible (unless disabl
 
 ## Config overrides (`~/.clawdis/clawdis.json`)
 
-Managed skills can be toggled and supplied with env values:
+Bundled/managed skills can be toggled and supplied with env values:
 
 ```json5
 {
@@ -81,7 +84,7 @@ Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted key
 Config keys match the **skill name**. We don’t require a custom `skillKey`.
 
 Rules:
-- `enabled: false` disables the managed skill even if installed.
+- `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`.
 
@@ -101,7 +104,7 @@ Clawdis snapshots the eligible skills **when a session starts** and reuses that
 
 ## 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.
+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.
 
 ---
 <!-- {% endraw %} -->

scripts/package-mac-app.sh

@@ -160,6 +160,10 @@ if [[ "${SKIP_GATEWAY_PACKAGE:-0}" != "1" ]]; then
   rm -rf "$RELAY_DIR/a2ui"
   cp -R "$ROOT_DIR/src/canvas-host/a2ui" "$RELAY_DIR/a2ui"
 
+  echo "🧠 Copying bundled skills"
+  rm -rf "$RELAY_DIR/skills"
+  cp -R "$ROOT_DIR/skills" "$RELAY_DIR/skills"
+
   echo "📄 Writing embedded runtime package.json (Pi compatibility)"
   cat > "$RELAY_DIR/package.json" <<JSON
 {

src/agents/skills.test.ts

@@ -40,11 +40,33 @@ describe("buildWorkspaceSkillsPrompt", () => {
 
     const prompt = buildWorkspaceSkillsPrompt(workspaceDir, {
       managedSkillsDir: path.join(workspaceDir, ".managed"),
+      bundledSkillsDir: path.join(workspaceDir, ".bundled"),
     });
 
     expect(prompt).toBe("");
   });
 
+  it("loads bundled skills when present", async () => {
+    const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdis-"));
+    const bundledDir = path.join(workspaceDir, ".bundled");
+    const bundledSkillDir = path.join(bundledDir, "peekaboo");
+
+    await writeSkill({
+      dir: bundledSkillDir,
+      name: "peekaboo",
+      description: "Capture UI",
+      body: "# Peekaboo\n",
+    });
+
+    const prompt = buildWorkspaceSkillsPrompt(workspaceDir, {
+      managedSkillsDir: path.join(workspaceDir, ".managed"),
+      bundledSkillsDir: bundledDir,
+    });
+    expect(prompt).toContain("peekaboo");
+    expect(prompt).toContain("Capture UI");
+    expect(prompt).toContain(path.join(bundledSkillDir, "SKILL.md"));
+  });
+
   it("loads skills from workspace skills/", async () => {
     const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdis-"));
     const skillDir = path.join(workspaceDir, "skills", "demo-skill");
@@ -100,9 +122,17 @@ describe("buildWorkspaceSkillsPrompt", () => {
   it("prefers workspace skills over managed skills", async () => {
     const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdis-"));
     const managedDir = path.join(workspaceDir, ".managed");
+    const bundledDir = path.join(workspaceDir, ".bundled");
     const managedSkillDir = path.join(managedDir, "demo-skill");
+    const bundledSkillDir = path.join(bundledDir, "demo-skill");
     const workspaceSkillDir = path.join(workspaceDir, "skills", "demo-skill");
 
+    await writeSkill({
+      dir: bundledSkillDir,
+      name: "demo-skill",
+      description: "Bundled version",
+      body: "# Bundled\n",
+    });
     await writeSkill({
       dir: managedSkillDir,
       name: "demo-skill",
@@ -118,11 +148,13 @@ describe("buildWorkspaceSkillsPrompt", () => {
 
     const prompt = buildWorkspaceSkillsPrompt(workspaceDir, {
       managedSkillsDir: managedDir,
+      bundledSkillsDir: bundledDir,
     });
 
     expect(prompt).toContain("Workspace version");
     expect(prompt).toContain(path.join(workspaceSkillDir, "SKILL.md"));
     expect(prompt).not.toContain(path.join(managedSkillDir, "SKILL.md"));
+    expect(prompt).not.toContain(path.join(bundledSkillDir, "SKILL.md"));
   });
 
   it("gates by bins, config, and always", async () => {
@@ -212,6 +244,7 @@ describe("buildWorkspaceSkillSnapshot", () => {
 
     const snapshot = buildWorkspaceSkillSnapshot(workspaceDir, {
       managedSkillsDir: path.join(workspaceDir, ".managed"),
+      bundledSkillsDir: path.join(workspaceDir, ".bundled"),
     });
 
     expect(snapshot.prompt).toBe("");

src/agents/skills.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   formatSkillsForPrompt,
@@ -50,6 +51,32 @@ export type SkillSnapshot = {
   skills: Array<{ name: string; primaryEnv?: string }>;
 };
 
+function resolveBundledSkillsDir(): string | undefined {
+  const override = process.env.CLAWDIS_BUNDLED_SKILLS_DIR?.trim();
+  if (override) return override;
+
+  // bun --compile: ship a sibling `skills/` next to the executable.
+  try {
+    const execDir = path.dirname(process.execPath);
+    const sibling = path.join(execDir, "skills");
+    if (fs.existsSync(sibling)) return sibling;
+  } catch {
+    // ignore
+  }
+
+  // npm/dev: resolve `<packageRoot>/skills` relative to this module.
+  try {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const root = path.resolve(moduleDir, "..", "..");
+    const candidate = path.join(root, "skills");
+    if (fs.existsSync(candidate)) return candidate;
+  } catch {
+    // ignore
+  }
+
+  return undefined;
+}
+
 function getFrontmatterValue(
   frontmatter: ParsedSkillFrontmatter,
   key: string,
@@ -380,12 +407,20 @@ function loadSkillEntries(
   opts?: {
     config?: ClawdisConfig;
     managedSkillsDir?: string;
+    bundledSkillsDir?: string;
   },
 ): SkillEntry[] {
   const managedSkillsDir =
     opts?.managedSkillsDir ?? path.join(CONFIG_DIR, "skills");
   const workspaceSkillsDir = path.join(workspaceDir, "skills");
+  const bundledSkillsDir = opts?.bundledSkillsDir ?? resolveBundledSkillsDir();
 
+  const bundledSkills = bundledSkillsDir
+    ? loadSkillsFromDir({
+        dir: bundledSkillsDir,
+        source: "clawdis-bundled",
+      })
+    : [];
   const managedSkills = loadSkillsFromDir({
     dir: managedSkillsDir,
     source: "clawdis-managed",
@@ -396,6 +431,8 @@ function loadSkillEntries(
   });
 
   const merged = new Map<string, Skill>();
+  // Precedence: bundled < managed < workspace
+  for (const skill of bundledSkills) merged.set(skill.name, skill);
   for (const skill of managedSkills) merged.set(skill.name, skill);
   for (const skill of workspaceSkills) merged.set(skill.name, skill);
 
@@ -423,6 +460,7 @@ export function buildWorkspaceSkillSnapshot(
   opts?: {
     config?: ClawdisConfig;
     managedSkillsDir?: string;
+    bundledSkillsDir?: string;
     entries?: SkillEntry[];
   },
 ): SkillSnapshot {
@@ -442,6 +480,7 @@ export function buildWorkspaceSkillsPrompt(
   opts?: {
     config?: ClawdisConfig;
     managedSkillsDir?: string;
+    bundledSkillsDir?: string;
     entries?: SkillEntry[];
   },
 ): string {
@@ -455,6 +494,7 @@ export function loadWorkspaceSkillEntries(
   opts?: {
     config?: ClawdisConfig;
     managedSkillsDir?: string;
+    bundledSkillsDir?: string;
   },
 ): SkillEntry[] {
   return loadSkillEntries(workspaceDir, opts);