@npeercy/skills 0.1.4 → 0.1.6

package/bin/skills.js

@@ -23,7 +23,7 @@ Setup:
 Discovery:
   search [query]                        Search skills (no query = browse all)
   info <skill>                          Skill details + versions
-  list [--verify] [--outdated] [--json] Show all local skills (managed + unmanaged)
+  list [--verify] [--outdated] [--json] Show all local skills (managed + unmanaged + bundled)
 
 Install:
   install <skill>[@ver] [--agent <a>] [--dry-run]
@@ -99,7 +99,7 @@ async function maybeWarnOutdated() {
 async function main() {
   const args = process.argv.slice(2);
 
-  // `skills` by itself -> list all local skills (managed + unmanaged)
+  // `skills` by itself -> list all local skills (managed + unmanaged + bundled)
   if (args.length === 0) {
     await maybeWarnOutdated();
     await cmdList({ verify: false, outdated: false, json: false });

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,22 +209,24 @@ 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);
+      const skillMd = skillMdPathFromEntry(full, entry);
+      if (!skillMd) continue;
 
-      if (!skillMd || !existsSync(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,
+      });
     }
   }
 
@@ -167,11 +259,24 @@ 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
@@ -184,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 {
@@ -196,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] = {
@@ -211,12 +323,22 @@ async function installBuiltins(agents) {
   }
 
   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 ---
@@ -510,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) {
@@ -788,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.4",
+  "version": "0.1.6",
   "description": "CLI-first skill marketplace for coding agents",
   "type": "module",
   "bin": {