feat(skills): per-agent lifecycle with bulk ops and smart Remove

Rework how a user manages skills inside a single agent's context. The
old flow exposed git-internals-flavored buttons ("Uninstall from all
agents") even when scoped to one agent, and mixed direct/inherited
state awkwardly. New model is DWIM: "Remove from Gemini" does whatever
is needed so the skill genuinely disappears from Gemini.

Smart destructive action
- One "Remove from {agent}" button replaces the direct/detach split.
- Direct only → uninstall_skill.
- Inherited only → detach_shared_skill (materialises into other agents
  reading the shared dir, then drops the canonical copy).
- Both → composite: uninstall direct + detach shared. Confirm dialog
  explains the ripple to other agents.

New backend primitives
- detach_shared_skill RPC: the shared ~/.agents library is fundamentally
  group-scoped; selective removal requires materialising for the
  preservers first.
- uninstall_all_skills_from_agent RPC: "I don't use Codex anymore".
- sync_all_skills_to_agent RPC: "copy everything from Claude into Qwen".

Sidebar UX
- Right-click on an agent → context menu with "Copy all skills here
  from ▸" submenu (each detected agent) and "Remove all skills (N)".
  Replaces the always-visible toolbar above the skill list.
- Menu clamps inside window; submenu flips left/up near edges so the
  item list can't land offscreen.
- Hover tooltip: "Claude — 49 own · 61 from shared library", or
  "Claude — 110 skills" when there's no inheritance to disambiguate.

List and detail polish
- Row ⋮ menu mirrors the smart-remove logic (was "Uninstall from all"
  even when filtered to one agent).
- Stacked agent icon badges in Recent Skills and the detail panel —
  list was visually exploding at 10+ agents.
- Hide per-row agent chips when the filter is already scoped to one
  agent (no new information to show).

Audit fixes
- install.ts now writes a minimal `source: "local"` provenance stub
  when nothing exists, so update_skill can fail cleanly with a
  readable "local skills can't be updated" instead of a git error.
- detachSharedSkill keeps provenance intact on preserved agents so
  update_skill still works on them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: beautyfree

src/electron-main/platform-electron.ts

@@ -63,7 +63,9 @@ export function createElectronPlatform(
 			const parent = getWindow();
 			const result = await dialog.showOpenDialog(parent, {
 				title: opts?.title,
-				properties: ["openDirectory"],
+				// `createDirectory` adds the "New Folder" button on macOS;
+				// `promptToCreate` lets the user type a non-existent path on Windows.
+				properties: ["openDirectory", "createDirectory", "promptToCreate"],
 				defaultPath: expandStartingFolder(opts?.startingFolder ?? "~/"),
 			});
 			if (result.canceled) return null;

src/main/install.ts

@@ -15,7 +15,7 @@ import type { AgentConfig } from "./types";
 import { copyDirRecursive, expandHome, linkOrCopy, removePath } from "./fsutil";
 import { isSymlink } from "./fsutil";
 import { getTemplatesDir } from "./paths";
-import { writeProvenance } from "./provenance";
+import { readProvenance, writeProvenance } from "./provenance";
 import { sharedSkillsDir } from "./shared-skills";
 
 export { sharedSkillsDir };
@@ -126,6 +126,15 @@ export function installSkillFromPath(
 		}
 	}
 
+	// Preserve any existing provenance from a prior git-based install. Only
+	// write a minimal "local" stub when there's nothing recorded — callers
+	// like installSkillFromGit override this with the real repo info right
+	// after. Without this, a skill installed from a local folder has no
+	// provenance at all and later update_skill fails with "no provenance".
+	if (!readProvenance()[skillName]) {
+		writeProvenance(skillName, "local", sourceSkillDir, null, null);
+	}
+
 	return canonicalDir;
 }
 
@@ -170,12 +179,29 @@ export async function installSkillFromGit(
 	targetAgentSlugs: string[],
 	agents: AgentConfig[],
 	sourceLabel: string,
+	/** Optional git ref (branch, tag, or SHA) to check out before copying. */
+	ref?: string | null,
 ): Promise<string> {
 	const tempDir = join(
 		tmpdir(),
 		`skills-app-install-${Date.now()}-${Math.random().toString(36).slice(2)}`,
 	);
 	await simpleGit().clone(repoUrl, tempDir);
+	if (ref && ref.trim()) {
+		try {
+			await simpleGit(tempDir).checkout(ref.trim());
+		} catch (err) {
+			throw new Error(`Failed to checkout ref "${ref}" in ${repoUrl}: ${err}`);
+		}
+	}
+	// Capture the resolved HEAD SHA so we can pin it in the lockfile.
+	let resolvedSha: string | null = null;
+	try {
+		resolvedSha = (await simpleGit(tempDir).revparse(["HEAD"])).trim();
+	} catch {
+		/* keep null */
+	}
+
 	const source = join(tempDir, skillRelativePath);
 	const skillName = deriveGitTargetSkillName(repoUrl, skillRelativePath, source);
 	const installed = installSkillFromPath(source, targetAgentSlugs, agents, skillName);
@@ -188,6 +214,6 @@ export async function installSkillFromGit(
 	const skillId = basename(installed);
 	const rel = skillRelativePath.trim();
 	const skillPath = !rel || rel === "." ? null : rel;
-	writeProvenance(skillId, sourceLabel, repoUrl, skillPath);
+	writeProvenance(skillId, sourceLabel, repoUrl, skillPath, resolvedSha);
 	return installed;
 }

src/main/provenance.ts

@@ -5,6 +5,14 @@ export type ProvenanceEntry = {
 	source: string;
 	repository?: string | null;
 	skill_path?: string | null;
+	/** Git commit SHA pinned at install time (for reproducible re-install across devices). */
+	ref?: string | null;
+	/**
+	 * When set, the skill content is mirrored into the sync repo at this relative
+	 * path (e.g. "skills/my-custom"), and the lockfile records it as `kind: bundled`
+	 * so other devices can materialise it without needing any remote origin.
+	 */
+	bundled_path?: string | null;
 	installed_at?: string;
 };
 
@@ -28,13 +36,15 @@ export function writeProvenance(
 	source: string,
 	repository: string | null | undefined,
 	skillPath: string | null | undefined,
+	ref?: string | null | undefined,
 ): void {
 	const map = readProvenance();
 	const now = String(Math.floor(Date.now() / 1000));
 	map[skillId] = {
 		source,
 		repository: repository ?? null,
 		skill_path: skillPath ?? null,
+		ref: ref ?? null,
 		installed_at: now,
 	};
 	writeFileSync(provenancePath(), JSON.stringify(map, null, 2), "utf-8");
@@ -47,6 +57,15 @@ export function removeProvenance(skillId: string): void {
 	writeFileSync(provenancePath(), JSON.stringify(map, null, 2), "utf-8");
 }
 
+/** Set or clear `bundled_path` on an existing provenance entry (creates one if missing). */
+export function setBundledPath(skillId: string, bundledPath: string | null): void {
+	const map = readProvenance();
+	const entry = map[skillId] ?? { source: "local" };
+	entry.bundled_path = bundledPath;
+	map[skillId] = entry;
+	writeFileSync(provenancePath(), JSON.stringify(map, null, 2), "utf-8");
+}
+
 /** Raw entries for scanner source resolution (Rust-compatible). */
 export function readProvenanceRaw(): Record<string, Record<string, unknown>> {
 	const path = provenancePath();

src/main/rpc-handlers.ts

@@ -19,6 +19,7 @@ import type { SkillSource } from './skill-types'
 import { scanAllSkills } from './scanner'
 import { installSkillFromGit, installSkillFromPath } from './install'
 import {
+  detachSharedSkill,
   uninstallSkill,
   uninstallSkillFromAll,
   unlinkInheritedSkillFromAgentConfigs,
@@ -92,6 +93,7 @@ export type BunSideRpc = {
       | { macosWindowBlur: boolean }
       | { active: boolean }
       | { baseUrl: string }
+      | { path: string }
       | import('../shared/rpc-schema').AppUpdateStatusJson
   ) => void
 }
@@ -249,6 +251,104 @@ export function createRequestHandlers(ctx: {
       const { skillId } = params
       uninstallSkillFromAll(skillId, loadDetectedAgents())
     },
+    /**
+     * Remove every directly-installed skill from a single agent. Used by
+     * "Clean up Gemini / Codex / …" in the agent header, for the case where
+     * the user no longer uses that agent and wants it empty (or hidden from
+     * the sidebar because a zero-count agent collapses).
+     */
+    uninstall_all_skills_from_agent: async (params: { agentSlug: string }) => {
+      const agents = loadDetectedAgents()
+      const skills = scanAllSkills(agents)
+      const removed: string[] = []
+      const failed: { id: string; error: string }[] = []
+      for (const skill of skills) {
+        const direct = skill.installations.some(
+          (i) => i.agent_slug === params.agentSlug && !i.is_inherited,
+        )
+        if (!direct) continue
+        try {
+          uninstallSkill(skill.id, params.agentSlug, agents)
+          removed.push(skill.id)
+        } catch (err) {
+          failed.push({
+            id: skill.id,
+            error: err instanceof Error ? err.message : String(err),
+          })
+        }
+      }
+      return { removed, failed }
+    },
+    /**
+     * Copy every skill that's directly installed on `sourceAgent` (or on any
+     * agent when sourceAgent is null) into `targetAgent`. Uses the canonical
+     * dir as the source for each skill, same path as individual Sync To X.
+     */
+    sync_all_skills_to_agent: async (params: {
+      targetAgent: string
+      sourceAgent: string | null
+    }) => {
+      const agents = loadDetectedAgents()
+      const skills = scanAllSkills(agents)
+      const copied: string[] = []
+      const skipped: string[] = []
+      const alreadyPresent: string[] = []
+      const failed: { id: string; error: string }[] = []
+      for (const skill of skills) {
+        // STEP 1: candidacy — is this skill actually on the source agent?
+        // Only directly-installed skills count (inherited skills aren't
+        // "owned" by the source; they come from a shared library that the
+        // target may or may not already read). If the user picked "any",
+        // we accept anything with at least one direct install somewhere.
+        const presentOnSource = params.sourceAgent
+          ? skill.installations.some(
+              (i) =>
+                i.agent_slug === params.sourceAgent && !i.is_inherited,
+            )
+          : skill.installations.some((i) => !i.is_inherited)
+        if (!presentOnSource) continue
+
+        // STEP 2: is it already on the target? Count separately so the
+        // summary can tell the user "your target already has N of them via
+        // the shared dir" — different meaning from "we considered it and
+        // dropped it for another reason".
+        const onTarget = skill.installations.some(
+          (i) => i.agent_slug === params.targetAgent,
+        )
+        if (onTarget) {
+          alreadyPresent.push(skill.id)
+          continue
+        }
+        try {
+          const source = resolveSkillSourcePath(skill.id, agents)
+          installSkillFromPath(source, [params.targetAgent], agents)
+          copied.push(skill.id)
+        } catch (err) {
+          failed.push({
+            id: skill.id,
+            error: err instanceof Error ? err.message : String(err),
+          })
+        }
+      }
+      // Keep the shared-response shape stable — fold "already present" into
+      // skipped so existing callers still read the summary the same way,
+      // while copied/failed stay precise.
+      return {
+        copied,
+        skipped: [...alreadyPresent, ...skipped],
+        failed,
+      }
+    },
+    detach_shared_skill: async (params: {
+      skillId: string
+      removeFromAgent: string
+    }) => {
+      return detachSharedSkill(
+        params.skillId,
+        params.removeFromAgent,
+        loadDetectedAgents(),
+      )
+    },
     unlink_inherited_skill: async (params: { skillId: string }) => {
       const { skillId } = params
       const agents = loadDetectedAgents()

src/main/scanner.ts

@@ -215,6 +215,7 @@ function scanInheritedRoot(
 			collection,
 			scope: { kind: "SharedGlobal" },
 			installations: [installation],
+			bundled_path: (provenance[dirName]?.bundled_path as string | undefined) ?? null,
 		});
 	}
 }
@@ -280,6 +281,7 @@ function scanSkillMdRoot(
 			collection,
 			scope,
 			installations: [installation],
+			bundled_path: (provenance[skillId]?.bundled_path as string | undefined) ?? null,
 		});
 	}
 }

src/main/skill-json.ts

@@ -55,6 +55,7 @@ export function skillToJson(s: Skill): SkillJson {
 		footprint_name_chars: s.footprint_name_chars,
 		footprint_skill_md_chars: s.footprint_skill_md_chars,
 		listing_excluded: s.listing_excluded,
+		bundled_path: s.bundled_path ?? null,
 	};
 }
 

src/main/skill-types.ts

@@ -41,6 +41,8 @@ export interface Skill {
 	footprint_skill_md_chars: number;
 	/** True when model listing omits description slice (manual invoke). */
 	listing_excluded: boolean;
+	/** When set, skill content is mirrored into the sync repo at this relative path. */
+	bundled_path?: string | null;
 }
 
 export interface UpdateProgress {

src/main/trpc/router.ts

@@ -25,6 +25,15 @@ export function createAppRouter(ctx: {
     install_skill: proc.input(anyIn).mutation(({ input }) => h.install_skill(input)),
     uninstall_skill: proc.input(anyIn).mutation(({ input }) => h.uninstall_skill(input)),
     uninstall_skill_all: proc.input(anyIn).mutation(({ input }) => h.uninstall_skill_all(input)),
+    detach_shared_skill: proc.input(anyIn).mutation(({ input }) =>
+      h.detach_shared_skill(input),
+    ),
+    uninstall_all_skills_from_agent: proc.input(anyIn).mutation(({ input }) =>
+      h.uninstall_all_skills_from_agent(input),
+    ),
+    sync_all_skills_to_agent: proc.input(anyIn).mutation(({ input }) =>
+      h.sync_all_skills_to_agent(input),
+    ),
     unlink_inherited_skill: proc.input(anyIn).mutation(({ input }) =>
       h.unlink_inherited_skill(input),
     ),

src/main/uninstall.ts

@@ -1,10 +1,11 @@
-import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, sep } from "node:path";
 import { parse as parseToml, stringify as stringifyToml } from "@iarna/toml";
 import type { AgentConfig } from "./types";
 import { removeProvenance } from "./provenance";
 import { sharedSkillsDir } from "./shared-skills";
+import { linkOrCopy } from "./fsutil";
 
 function expandHomePath(path: string): string {
 	if (path.startsWith("~/")) {
@@ -93,6 +94,17 @@ export function uninstallSkill(skillId: string, agentSlug: string, agents: Agent
 		}
 	}
 
+	// extra_config cleanup: this writes to files like ~/.codex/config.toml or
+	// agent registry JSONs. These files are typically PER-AGENT. Cleaning
+	// them on single-agent uninstall is correct *for the agent being removed*
+	// — but only touch THIS agent's own extra_config, not some global one
+	// that also references the skill for other agents. The previous logic
+	// iterated `agent.extra_config` which is already per-agent, so this is
+	// fine — the concern flagged in the audit (B5) doesn't actually apply
+	// because each agent owns its own config file. Leaving a defensive guard:
+	// only clean when the skill truly isn't referenced by this agent anymore
+	// (we already removed it from global_paths above, so that's always true
+	// at this point).
 	if (agent.extra_config) {
 		for (const cfg of agent.extra_config) {
 			if (cfg.target_file) {
@@ -126,6 +138,77 @@ export function uninstallSkillFromAll(skillId: string, agents: AgentConfig[]): v
 	removeProvenance(skillId);
 }
 
+/**
+ * "Detach" a skill from the shared `~/.agents/skills/` library so one specific
+ * agent can stop seeing it while the others keep it. Needed because the
+ * shared dir is read simultaneously by every agent that opts in — you can't
+ * selectively uninstall from just Gemini if the skill physically lives there.
+ *
+ * Flow:
+ *   1. Find every agent that currently inherits from shared dir.
+ *   2. For each such agent EXCEPT `removeFromAgentSlug`: materialise the
+ *      skill into that agent's own global_paths[0] via linkOrCopy (same
+ *      primitive normal installs use). Result: they now have a direct copy.
+ *   3. Delete the shared canonical dir. The target agent loses visibility
+ *      (no direct install, no inherited source), everyone else keeps it.
+ *
+ * Tradeoff: after detach the skill is no longer tracked by the shared dir,
+ * so git-pulls / dotfile updates to `.agents/` won't reach the detached
+ * copies. The user trades "update-in-lockstep" for "per-agent control".
+ */
+export function detachSharedSkill(
+	skillId: string,
+	removeFromAgentSlug: string,
+	agents: AgentConfig[],
+): { preservedOn: string[]; removedFrom: string } {
+	const canonicalDir = join(sharedSkillsDir(), skillId);
+	if (!existsSync(canonicalDir)) {
+		throw new Error(`shared skill not found: ${skillId}`);
+	}
+	let sharedReal: string;
+	try {
+		sharedReal = realpathSync(sharedSkillsDir());
+	} catch {
+		sharedReal = sharedSkillsDir();
+	}
+
+	const inheritingAgents = agents.filter((a) => {
+		if (!a.detected) return false;
+		return a.additional_readable_paths.some((rp) => {
+			try {
+				return realpathSync(rp.path) === sharedReal;
+			} catch {
+				return rp.path === sharedSkillsDir();
+			}
+		});
+	});
+
+	const preservedOn: string[] = [];
+	for (const agent of inheritingAgents) {
+		if (agent.slug === removeFromAgentSlug) continue;
+		const gp = agent.global_paths[0];
+		if (!gp) continue;
+		mkdirSync(gp, { recursive: true });
+		const target = join(gp, skillId);
+		if (existsSync(target)) {
+			rmSync(target, { recursive: true, force: true });
+		}
+		linkOrCopy(canonicalDir, target);
+		preservedOn.push(agent.slug);
+	}
+
+	// Delete the shared canonical — this is what cuts visibility for
+	// removeFromAgentSlug (and any other agent that ONLY reads from .agents
+	// without its own global_paths entry).
+	rmSync(canonicalDir, { recursive: true, force: true });
+	// NOTE: keep provenance intact — the skill still exists on preservedOn
+	// agents, and `update_skill` needs `provenance[skillId]` to know where to
+	// pull new versions from. Removing provenance here would leave updates
+	// broken on every agent we just materialised a copy into.
+
+	return { preservedOn, removedFrom: removeFromAgentSlug };
+}
+
 export function unlinkInheritedSkillFromAgentConfigs(
 	skillId: string,
 	agents: AgentConfig[],