diff --git a/docs/agent.md b/docs/agent.md index f383ec8d4..d9cdf2c7f 100644 --- a/docs/agent.md +++ b/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: `/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 diff --git a/docs/configuration.md b/docs/configuration.md index 7211d4b66..1e89aa242 100644 --- a/docs/configuration.md +++ b/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`). diff --git a/docs/skills.md b/docs/skills.md index c029272bc..40d830ded 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -7,16 +7,19 @@ read_when: # 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**: `/skills` +1) **Bundled skills**: shipped with the install (npm package or Clawdis.app) +2) **Managed/local skills**: `~/.clawdis/skills` +3) **Workspace skills**: `/skills` -If a skill name conflicts, the **workspace** version wins (user overrides managed). +If a skill name conflicts, precedence is: + +`/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. --- diff --git a/scripts/package-mac-app.sh b/scripts/package-mac-app.sh index 49472bf6e..ba12c2def 100755 --- a/scripts/package-mac-app.sh +++ b/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" < { 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(""); diff --git a/src/agents/skills.ts b/src/agents/skills.ts index e8df3448e..90a0a1051 100644 --- a/src/agents/skills.ts +++ b/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 `/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(); + // 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);