99// populate.
1010//
1111// So we mirror the canonical Claude store into each of those per-agent dirs, but
12- // only for agents the machine actually has (their marker dir exists). On Unix
12+ // only for agents the machine actually has (their marker dir exists). Agents
13+ // that already consume the universal ~/.agents/skills store globally (Pi) are
14+ // skipped: their universal copy is authoritative and a per-agent copy would
15+ // collide with it (#3294). On Unix
1316// each skill is a relative symlink back into the store (one source of truth,
1417// near-zero size, auto-fresh on update); on Windows it's a copy, because
1518// symlinks there need admin / Developer Mode and otherwise silently dangle —
@@ -24,6 +27,22 @@ import { homedir } from "node:os";
2427import { dirname , isAbsolute , join , relative } from "node:path" ;
2528import { AGENT_GLOBAL_DIRS , type AgentDirBase } from "./agentDirs.generated.js" ;
2629
30+ /**
31+ * Agents that natively discover the universal `~/.agents/skills` store globally
32+ * in ADDITION to their own agent-specific directory. Mirroring into their own
33+ * dir makes every skill discoverable twice.
34+ *
35+ * Pi is the known case (earendil-works/pi): it reads both `~/.pi/agent/skills/`
36+ * and `~/.agents/skills/` as global locations (pi's packages/coding-agent/docs/
37+ * skills.md#locations), so a mirrored entry collides with the universal copy
38+ * and Pi skips the universal one on name conflict (#3294).
39+ *
40+ * The generated table cannot carry this capability — it is a plain
41+ * (agent, base, sub) list synced from vercel-labs/skills — so the set lives
42+ * here next to the mirror logic that needs it.
43+ */
44+ const UNIVERSAL_STORE_READERS = new Set ( [ "pi" ] ) ;
45+
2746export interface MirrorResult {
2847 /** The store mirrored from, or null when no global Claude store was found. */
2948 source : string | null ;
@@ -128,6 +147,7 @@ export function mirrorGlobalSkills(opts: {
128147 for ( const { agent, base, sub } of AGENT_GLOBAL_DIRS ) {
129148 const targetDir = join ( bases [ base ] , ...sub . split ( "/" ) . filter ( Boolean ) ) ;
130149 if ( targetDir === source || targetDir === universalStore ) continue ; // install-owned
150+ if ( UNIVERSAL_STORE_READERS . has ( agent ) ) continue ; // already reads the universal store (#3294)
131151 if ( ! existsSync ( dirname ( targetDir ) ) ) continue ; // agent not installed (no marker)
132152 if ( mirrorInto ( targetDir , source , skills , platform ) ) mirrored . push ( { agent, dir : targetDir } ) ;
133153 }
0 commit comments