fix(skills): remove Codex mirror links left by earlier skill updates

Author: miguel-heygen

packages/cli/src/utils/skillsMirror.test.ts

@@ -277,6 +277,31 @@ describe("mirrorGlobalSkills", () => {
     expect(readFileSync(join(existing, "SKILL.md"), "utf8")).toBe("# locally managed\n");
   });
 
+  it("removes Codex links an earlier mirror created and keeps the user's own entries", () => {
+    const home = makeHome();
+    seedStore(home, ["hyperframes", "media-use"]);
+    const codexSkills = join(home, ".codex", "skills");
+    mkdirSync(join(codexSkills, ".system"), { recursive: true });
+    mkdirSync(join(codexSkills, "my-skill"), { recursive: true });
+    // What main's mirror wrote: a relative link back into the Claude store.
+    symlinkSync(
+      join("..", "..", ".claude", "skills", "hyperframes"),
+      join(codexSkills, "hyperframes"),
+    );
+    // Same skill name, but the user's own link to somewhere else.
+    const userCopy = join(home, "my-media-use");
+    mkdirSync(userCopy);
+    symlinkSync(userCopy, join(codexSkills, "media-use"));
+
+    mirrorGlobalSkills({ skills: ["hyperframes", "media-use"], home, platform: "linux", env: ENV });
+
+    expect(existsSync(join(codexSkills, "hyperframes"))).toBe(false);
+    expect(realpathSync(join(codexSkills, "media-use"))).toBe(realpathSync(userCopy));
+    expect(existsSync(join(codexSkills, ".system"))).toBe(true);
+    expect(existsSync(join(codexSkills, "my-skill"))).toBe(true);
+    expect(existsSync(join(home, ".claude", "skills", "hyperframes", "SKILL.md"))).toBe(true);
+  });
+
   // Pi natively discovers BOTH ~/.pi/agent/skills and the universal
   // ~/.agents/skills (pi's packages/coding-agent/docs/skills.md#locations).
   // A mirrored per-agent copy collides with the universal one and Pi skips

packages/cli/src/utils/skillsMirror.ts

@@ -32,6 +32,7 @@ import {
   rmSync,
   statSync,
   symlinkSync,
+  unlinkSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -237,6 +238,23 @@ function mirrorInto(
   return { mirrored: true };
 }
 
+/**
+ * Unlink symlinks an earlier mirror left in `targetDir` (they resolve to the same source skill).
+ * Real dirs and Windows copies carry no ownership proof, so they stay.
+ */
+function removeMirrorLinks(targetDir: string, source: string, skills: string[]): void {
+  for (const skill of skills) {
+    const targetSkill = join(targetDir, skill);
+    try {
+      if (!lstatSync(targetSkill).isSymbolicLink()) continue;
+      if (realpathSync(targetSkill) !== realpathSync(join(source, skill))) continue;
+      unlinkSync(targetSkill);
+    } catch {
+      // absent or dangling: nothing of ours to remove
+    }
+  }
+}
+
 /**
  * Mirror the global Claude store into every installed agent's global skills
  * dir. Best-effort and idempotent: a no-op when the store is absent, and per
@@ -283,7 +301,11 @@ export function mirrorGlobalSkills(opts: {
   for (const { agent, base, sub } of AGENT_GLOBAL_DIRS) {
     const targetDir = join(bases[base], ...sub.split("/").filter(Boolean));
     if (targetDir === source || targetDir === universalStore) continue; // install-owned
-    if (UNIVERSAL_STORE_READERS.has(agent)) continue; // already reads the universal store (#3294)
+    if (UNIVERSAL_STORE_READERS.has(agent)) {
+      // Already reads the universal store (#3294); drop links an older version mirrored here.
+      removeMirrorLinks(targetDir, source, skills);
+      continue;
+    }
     if (!existsSync(dirname(targetDir))) continue; // agent not installed (no marker)
     const attempt = mirrorInto(targetDir, source, skills, platform, () =>
       targetSafety(targetDir, resolvedProtectedPaths),