@npeercy/skills 0.1.3 → 0.1.5

package/lib/skills.js

@@ -104,13 +104,103 @@ async function promptYesNo(question, defaultYes = true) {
   return ['y', 'yes'].includes(ans);
 }
 
+function resolveSymlinkTarget(linkPath) {
+  const target = readlinkSync(linkPath);
+  return target.startsWith('/') ? target : resolve(dirname(linkPath), target);
+}
+
+function skillMdPathFromEntry(fullPath, entry) {
+  try {
+    if (entry.isDirectory()) {
+      const md = join(fullPath, 'SKILL.md');
+      return existsSync(md) ? md : null;
+    }
+
+    const st = lstatSync(fullPath);
+    if (!st.isSymbolicLink()) return null;
+    const target = resolveSymlinkTarget(fullPath);
+    const md = join(target, 'SKILL.md');
+    return existsSync(md) ? md : null;
+  } catch {
+    return null;
+  }
+}
+
+function readSkillMeta(skillMdPath) {
+  try {
+    return parseFrontmatter(readFileSync(skillMdPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function discoverSkillNameUsage(agents) {
+  const usage = new Map(); // skill-name -> [{agent, entryName, path, skillMdPath}]
+
+  for (const [agentName, agentPath] of Object.entries(agents)) {
+    if (!existsSync(agentPath)) continue;
+
+    for (const entry of readdirSync(agentPath, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const full = join(agentPath, entry.name);
+      const skillMd = skillMdPathFromEntry(full, entry);
+      if (!skillMd) continue;
+
+      const meta = readSkillMeta(skillMd);
+      if (!meta?.name) continue;
+
+      if (!usage.has(meta.name)) usage.set(meta.name, []);
+      usage.get(meta.name).push({
+        agent: agentName,
+        entryName: entry.name,
+        path: full,
+        skillMdPath: skillMd,
+      });
+    }
+  }
+
+  return usage;
+}
+
+function discoverAgentNameConflicts(agents) {
+  const conflicts = []; // [{agent,name,entries}]
+
+  for (const [agentName, agentPath] of Object.entries(agents)) {
+    if (!existsSync(agentPath)) continue;
+    const byName = new Map();
+
+    for (const entry of readdirSync(agentPath, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const full = join(agentPath, entry.name);
+      const skillMd = skillMdPathFromEntry(full, entry);
+      if (!skillMd) continue;
+
+      const meta = readSkillMeta(skillMd);
+      if (!meta?.name) continue;
+
+      if (!byName.has(meta.name)) byName.set(meta.name, []);
+      byName.get(meta.name).push(entry.name);
+    }
+
+    for (const [name, entries] of byName.entries()) {
+      if (entries.length > 1) {
+        conflicts.push({ agent: agentName, name, entries: entries.sort() });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
 function discoverUnmanaged(agents, st) {
-  const unmanaged = new Map(); // name -> { sources: [{agent,path,skillMdPath}] }
+  const unmanaged = new Map(); // skill-name -> { sources: [{agent,path,skillMdPath}] }
   const managedLinks = new Set(Object.keys(st.installed).map(linkNameForSkill));
 
   for (const [agentName, agentPath] of Object.entries(agents)) {
     if (!existsSync(agentPath)) continue;
+
     for (const entry of readdirSync(agentPath, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
       const full = join(agentPath, entry.name);
 
       // Skip managed link names
@@ -119,47 +209,74 @@ function discoverUnmanaged(agents, st) {
       // Skip if symlink points to managed store
       try {
         if (lstatSync(full).isSymbolicLink()) {
-          const target = readlinkSync(full);
+          const target = resolveSymlinkTarget(full);
           if (target.includes('skill-sharer')) continue;
         }
       } catch {
         // ignore stat errors
       }
 
-      const skillMd = entry.isDirectory()
-        ? join(full, 'SKILL.md')
-        : (lstatSync(full).isSymbolicLink() ? join(resolve(readlinkSync(full)), 'SKILL.md') : null);
-
-      if (!skillMd || !existsSync(skillMd)) continue;
+      const skillMd = skillMdPathFromEntry(full, entry);
+      if (!skillMd) continue;
 
-      const key = entry.name;
+      const meta = readSkillMeta(skillMd);
+      const key = meta?.name || entry.name;
       if (!unmanaged.has(key)) unmanaged.set(key, { sources: [] });
-      unmanaged.get(key).sources.push({ agent: agentName, path: full, skillMdPath: skillMd });
+      unmanaged.get(key).sources.push({
+        agent: agentName,
+        path: full,
+        skillMdPath: skillMd,
+      });
     }
   }
 
   return unmanaged;
 }
 
-async function installBuiltins(agents) {
-  const st = loadState();
+function bundledBuiltins() {
+  const out = [];
   const builtinsRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'builtin-skills');
-  if (!existsSync(builtinsRoot)) return;
+  if (!existsSync(builtinsRoot)) return out;
 
-  const installed = [];
   for (const entry of readdirSync(builtinsRoot, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
-
     const srcDir = join(builtinsRoot, entry.name);
     const skillMd = join(srcDir, 'SKILL.md');
     if (!existsSync(skillMd)) continue;
-
     const meta = parseFrontmatter(readFileSync(skillMd, 'utf8'));
     if (!meta) continue;
+    out.push({
+      id: `__builtin__/local/${meta.name}`,
+      name: meta.name,
+      srcDir,
+    });
+  }
 
-    const id = `__builtin__/local/${meta.name}`;
+  return out;
+}
+
+async function installBuiltins(agents) {
+  const st = loadState();
+
+  const installed = [];
+  const skipped = [];
+  const nameUsage = discoverSkillNameUsage(agents);
+
+  for (const b of bundledBuiltins()) {
+    const srcDir = b.srcDir;
+    const id = b.id;
     const version = 'v1';
     const dest = managedPath(id, version);
+    const linkName = linkNameForSkill(id);
+
+    const conflictingEntries = (nameUsage.get(b.name) || [])
+      .filter(s => s.entryName !== linkName);
+
+    if (conflictingEntries.length > 0) {
+      skipped.push({ name: b.name, conflicts: conflictingEntries });
+      continue;
+    }
+
     const files = collectFiles(srcDir);
 
     // Write to managed store
@@ -172,8 +289,7 @@ async function installBuiltins(agents) {
     }
 
     // Symlink into all detected agents
-    const linkName = linkNameForSkill(id);
-    for (const agentPath of Object.values(agents)) {
+    for (const [agentName, agentPath] of Object.entries(agents)) {
       mkdirSync(agentPath, { recursive: true });
       const link = join(agentPath, linkName);
       try {
@@ -184,6 +300,14 @@ async function installBuiltins(agents) {
         // doesn't exist
       }
       symlinkSync(dest, link);
+
+      if (!nameUsage.has(b.name)) nameUsage.set(b.name, []);
+      nameUsage.get(b.name).push({
+        agent: agentName,
+        entryName: linkName,
+        path: link,
+        skillMdPath: join(dest, 'SKILL.md'),
+      });
     }
 
     st.installed[id] = {
@@ -195,16 +319,26 @@ async function installBuiltins(agents) {
       builtin: true,
     };
 
-    installed.push(meta.name);
+    installed.push(b.name);
   }
 
   saveState(st);
+
   if (installed.length > 0) {
     console.log('\nInstalled built-in skills:');
     for (const name of installed) {
       console.log(`  ✓ ${name} → ${Object.keys(agents).join(', ') || '(no agents detected)'}`);
     }
   }
+
+  if (skipped.length > 0) {
+    console.log('\nSkipped built-ins to avoid skill-name conflicts in agents:');
+    for (const s of skipped) {
+      const where = s.conflicts.map(c => `${c.agent}/${c.entryName}`).join(', ');
+      console.log(`  ! ${s.name} (already present at: ${where})`);
+    }
+    console.log('  Tip: remove/rename duplicates if you want bundled docs linked automatically.');
+  }
 }
 
 // --- Commands ---
@@ -449,6 +583,20 @@ export async function cmdList(args = {}) {
     });
   }
 
+  // Bundled built-ins (show even if not installed yet)
+  const installedIds = new Set(Object.keys(st.installed));
+  for (const b of bundledBuiltins()) {
+    if (installedIds.has(b.id)) continue;
+    rows.push({
+      id: b.id,
+      version: '-',
+      latest: 'v1',
+      agents: '-',
+      status: 'bundled',
+      managed: false,
+    });
+  }
+
   // Unmanaged installs (present in agent dirs but not in skill-sharer state)
   const unmanaged = discoverUnmanaged(agents, st);
   for (const [name, info] of unmanaged.entries()) {
@@ -484,6 +632,15 @@ export async function cmdList(args = {}) {
   if (unmanagedCount > 0) {
     console.log(`\nFound ${unmanagedCount} unmanaged skill(s). Run: skills import`);
   }
+
+  const conflicts = discoverAgentNameConflicts(agents);
+  if (conflicts.length > 0) {
+    console.log('\nPotential skill-name conflicts detected (can break skill selection in agents):');
+    for (const c of conflicts) {
+      console.log(`  ${c.agent}: "${c.name}" appears in ${c.entries.join(', ')}`);
+    }
+    console.log('Resolve duplicates by removing/renaming one copy.');
+  }
 }
 
 function verifyInstall(id, rec, agents) {
@@ -762,6 +919,12 @@ export async function cmdDoctor(args) {
     }
   }
 
+  const conflicts = discoverAgentNameConflicts(agents);
+  for (const c of conflicts) {
+    console.log(`Conflict: ${c.agent} has duplicate skill name "${c.name}" in ${c.entries.join(', ')}`);
+    issues++;
+  }
+
   if (issues === 0) console.log('All good.');
   else console.log(`\n${issues} issue(s) found.`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npeercy/skills",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI-first skill marketplace for coding agents",
   "type": "module",
   "bin": {