promptgraph-mcp 2.4.7 → 2.4.8

package/README.md

@@ -154,12 +154,9 @@ Claude uses these automatically when the MCP server is running:
 
 ## Search modes
 
-| Mode | How | Quality |
-|---|---|---|
-| After `pg reindex` | Cosine similarity on 384-dim BGE vectors | Semantic — finds by meaning |
-| After `pg reindex --fast` | SQLite FTS5 BM25 | Keyword — exact word match |
-
-Search falls back to FTS5 automatically if no embeddings exist.
+Search falls back to FTS5 automatically if no embeddings exist. When embeddings are
+available, results are a hybrid of semantic similarity (embedding cosine) and keyword
+relevance (BM25) — giving you the best of both approaches.
 
 ---
 

package/ann.js

@@ -1,61 +1,33 @@
 import { getDb, blobToVec } from './db.js';
+import { getStore, resetStore } from './src/store/index.js';
 
-// In-memory flat index — no external dependency.
-// For typical skill counts (<5000) this is faster than vectra's disk-based HNSW
-// because all data fits in RAM and no I/O is needed per query.
-let _cache = null;
-let _cacheChunkCount = -1;
-
-function loadCache(db) {
-  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
-  if (_cache && count === _cacheChunkCount) return _cache;
-  const rows = db.prepare('SELECT skill_id, embedding FROM chunks').all();
-  _cache = rows.map(r => ({
-    skill_id: r.skill_id,
-    vec: new Float32Array(blobToVec(r.embedding)),
-  }));
-  _cacheChunkCount = count;
-  return _cache;
-}
-
-function cosineSim(a, b) {
-  let dot = 0, na = 0, nb = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-    na += a[i] * a[i];
-    nb += b[i] * b[i];
-  }
-  return dot / (Math.sqrt(na) * Math.sqrt(nb) + 1e-8);
-}
-
-// Called after reindex — invalidate cache so next search reloads
 export async function buildAnnIndex() {
-  _cache = null;
-  _cacheChunkCount = -1;
-  const db = getDb();
-  const count = db.prepare('SELECT COUNT(*) as n FROM chunks').get().n;
-  console.error(`[PromptGraph] In-memory index ready: ${count} chunks`);
+  try {
+    const db = getDb();
+    const rows = db.prepare('SELECT skill_id, embedding FROM chunks').all();
+    const entries = rows.map(r => ({
+      skill_id: r.skill_id,
+      vector: blobToVec(r.embedding),
+    }));
+    const store = getStore();
+    await store.build(entries);
+    console.error(`[PromptGraph] ANN index ready: ${store.size} vectors`);
+  } catch (e) {
+    console.error(`[PromptGraph] ANN build failed: ${e.message}`);
+  }
 }
 
 export async function annSearch(queryVec, topK = 20) {
   try {
-    const db = getDb();
-    const cache = loadCache(db);
-    if (!cache.length) return null;
-
-    const qArr = new Float32Array(queryVec);
-    const bestBySkill = new Map();
-    for (const entry of cache) {
-      const score = cosineSim(qArr, entry.vec);
-      const prev = bestBySkill.get(entry.skill_id);
-      if (!prev || score > prev) bestBySkill.set(entry.skill_id, score);
-    }
-
-    return [...bestBySkill.entries()]
-      .sort((a, b) => b[1] - a[1])
-      .slice(0, topK)
-      .map(([skill_id, score]) => ({ skill_id, score }));
-  } catch {
+    const store = getStore();
+    if (store.size === 0) return null;
+    return await store.search(queryVec, topK);
+  } catch (e) {
+    console.error(`[PromptGraph] ANN search error: ${e.message}`);
     return null;
   }
 }
+
+export function resetAnnIndex() {
+  resetStore();
+}

package/api.js

@@ -0,0 +1,200 @@
+import { search as internalSearch, getContext, listAll as internalList } from './search.js';
+import { indexAll, indexSource } from './indexer.js';
+import { getDb } from './db.js';
+import { loadConfig } from './config.js';
+
+/**
+ * Search for skills by query text.
+ * @param {string} query - Natural language search query
+ * @param {{ topK?: number, embedWeight?: number, bm25Weight?: number, source?: string, category?: string }} [options]
+ * @returns {Promise<Array<{id: string, name: string, description: string, source: string, score: number, snippet: string}>>}
+ */
+export async function search(query, options = {}) {
+  try {
+    const { topK = 5, source } = options;
+    const results = await internalSearch(query, source ? topK * 3 : topK);
+    if (source) {
+      return results.filter(r => r.source === source).slice(0, topK);
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Index all .md files in a directory under a source name.
+ * @param {string} sourceDir - Path to directory containing .md skill files
+ * @param {string} sourceName - Source label stored with each skill
+ * @returns {Promise<{indexed: number, skipped: number, errors: number}>}
+ */
+export async function index(sourceDir, sourceName) {
+  try {
+    if (sourceDir.includes('..')) {
+      return { indexed: 0, skipped: 0, errors: 1, error: 'Path traversal detected in sourceDir' };
+    }
+    const db = getDb();
+    const { globSync } = await import('glob');
+    const fs = await import('fs');
+    const path = await import('path');
+    const { createHash } = await import('crypto');
+    const { parseSkillFile, isSkillFile } = await import('./parser.js');
+    const { embedBatch, BATCH_SIZE } = await import('./embedder.js');
+    const { skillId, vecToBlob } = await import('./db.js');
+    const { chunkText } = await import('./chunker.js');
+
+    const files = globSync(`${sourceDir}/**/*.md`);
+    let indexed = 0, skipped = 0, errors = 0;
+    const batch = [];
+
+    for (const file of files) {
+      try {
+        const stat = fs.statSync(file);
+        if (stat.size > 5 * 1024 * 1024) { skipped++; continue; }
+        const raw = fs.readFileSync(file, 'utf8');
+        const hash = createHash('md5').update(raw).digest('hex');
+        if (!isSkillFile(file, raw)) { skipped++; continue; }
+        const parsed = parseSkillFile(file, sourceName, { raw });
+        batch.push({ ...parsed, hash });
+        if (batch.length >= BATCH_SIZE) {
+          await indexBatch(db, batch);
+          indexed += batch.length;
+          batch.length = 0;
+        }
+      } catch { errors++; }
+    }
+    if (batch.length > 0) {
+      await indexBatch(db, batch);
+      indexed += batch.length;
+    }
+    return { indexed, skipped, errors };
+  } catch (e) {
+    return { indexed: 0, skipped: 0, errors: 1, error: e.message };
+  }
+}
+
+/**
+ * Remove a skill by its ID.
+ * @param {string} skillId - Skill ID (format: "source::name")
+ * @returns {{ok: boolean, error?: string}}
+ */
+export function remove(skillId) {
+  try {
+    const db = getDb();
+    db.prepare('DELETE FROM skills WHERE id = ?').run(skillId);
+    db.prepare('DELETE FROM chunks WHERE skill_id = ?').run(skillId);
+    db.prepare('DELETE FROM edges WHERE from_skill = ? OR to_skill = ?').run(skillId, skillId);
+    db.prepare('DELETE FROM ratings WHERE skill_id = ?').run(skillId);
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Reindex changed files only (hash-based). Scans all configured sources,
+ * updates files whose content hash changed, and removes stale skills.
+ * @returns {Promise<{updated: number, removed: number, errors: number}>}
+ */
+export async function update() {
+  try {
+    const db = getDb();
+    const config = loadConfig();
+    const { globSync } = await import('glob');
+    const fs = await import('fs');
+    const path = await import('path');
+    const { createHash } = await import('crypto');
+    const { parseSkillFile, isSkillFile } = await import('./parser.js');
+    const { embedBatch, BATCH_SIZE } = await import('./embedder.js');
+    const { skillId, vecToBlob } = await import('./db.js');
+    const { chunkText } = await import('./chunker.js');
+    const { indexBatch } = await import('./indexer.js');
+
+    const normalizedSources = config.sources.map(s => ({ ...s, normDir: path.resolve(s.dir) }))
+      .sort((a, b) => b.normDir.length - a.normDir.length);
+
+    const seenFiles = new Set();
+    const allFiles = [];
+    for (const { dir, source } of normalizedSources) {
+      const files = globSync(`${dir}/**/*.md`);
+      for (const f of files) {
+        const norm = path.resolve(f);
+        if (!seenFiles.has(norm)) { seenFiles.add(norm); allFiles.push({ file: norm, source }); }
+      }
+    }
+
+    const dbByPath = new Map();
+    for (const row of db.prepare('SELECT id, path, hash FROM skills').all()) {
+      dbByPath.set(row.path, row);
+    }
+
+    const existingPaths = new Set(allFiles.map(f => f.file));
+    let removed = 0;
+    for (const [filePath, row] of dbByPath) {
+      if (!existingPaths.has(filePath)) {
+        db.prepare('DELETE FROM skills WHERE id = ?').run(row.id);
+        db.prepare('DELETE FROM chunks WHERE skill_id = ?').run(row.id);
+        db.prepare('DELETE FROM edges WHERE from_skill = ? OR to_skill = ?').run(row.id, row.id);
+        db.prepare('DELETE FROM ratings WHERE skill_id = ?').run(row.id);
+        removed++;
+      }
+    }
+
+    let updated = 0, errors = 0, batch = [];
+    for (const { file, source } of allFiles) {
+      try {
+        const raw = fs.readFileSync(file, 'utf8');
+        const hash = createHash('md5').update(raw).digest('hex');
+        const dbRow = dbByPath.get(file);
+        if (dbRow?.hash === hash) continue;
+        if (!isSkillFile(file, raw)) continue;
+        const parsed = parseSkillFile(file, source, { raw });
+        batch.push({ ...parsed, hash });
+        if (batch.length >= BATCH_SIZE) {
+          await indexBatch(db, batch);
+          updated += batch.length;
+          batch.length = 0;
+        }
+      } catch { errors++; }
+    }
+    if (batch.length > 0) {
+      await indexBatch(db, batch);
+      updated += batch.length;
+    }
+
+    return { updated, removed, errors };
+  } catch (e) {
+    return { updated: 0, removed: 0, errors: 1, error: e.message };
+  }
+}
+
+/**
+ * Get full skill details by ID, including edges.
+ * @param {string} skillId
+ * @returns {object|null}
+ */
+export function get(skillId) {
+  try {
+    return getContext(skillId);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all skills with optional filtering.
+ * @param {{ source?: string, category?: string, limit?: number, offset?: number }} [options]
+ * @returns {Array<object>}
+ */
+export function list(options = {}) {
+  try {
+    const { source, limit, offset } = options;
+    let results = internalList();
+    if (source) results = results.filter(r => r.source === source);
+    if (offset) results = results.slice(offset);
+    if (limit) results = results.slice(0, limit);
+    return results;
+  } catch {
+    return [];
+  }
+}

package/config.js

@@ -56,3 +56,10 @@ export async function promptConfig() {
   console.log(`\nConfig saved to ${CONFIG_PATH}`);
   return config;
 }
+
+export function sanitizePath(inputPath) {
+  if (inputPath.includes('..')) {
+    throw new Error(`Path traversal blocked: "${inputPath}"`);
+  }
+  return path.resolve(inputPath);
+}

package/db.js

@@ -63,6 +63,26 @@ export function getDb() {
     db.exec('ALTER TABLE skills ADD COLUMN hash TEXT');
   }
 
+  // migrate: add registry metadata columns
+  if (!cols.includes('version')) {
+    db.exec('ALTER TABLE skills ADD COLUMN version TEXT');
+  }
+  if (!cols.includes('author')) {
+    db.exec('ALTER TABLE skills ADD COLUMN author TEXT');
+  }
+  if (!cols.includes('license')) {
+    db.exec('ALTER TABLE skills ADD COLUMN license TEXT');
+  }
+  if (!cols.includes('updated_at')) {
+    db.exec('ALTER TABLE skills ADD COLUMN updated_at TEXT');
+  }
+  if (!cols.includes('downloads')) {
+    db.exec('ALTER TABLE skills ADD COLUMN downloads INTEGER DEFAULT 0');
+  }
+  if (!cols.includes('verified')) {
+    db.exec('ALTER TABLE skills ADD COLUMN verified INTEGER DEFAULT 0');
+  }
+
   // migrate: convert JSON text embeddings to Float32 BLOB (one-time, ~10x smaller)
   const textEmbeddings = db.prepare("SELECT COUNT(*) as n FROM chunks WHERE typeof(embedding) = 'text'").get();
   if (textEmbeddings?.n > 0) {

package/embedder.js

@@ -4,6 +4,11 @@ import os from 'os';
 
 const CACHE_DIR = path.join(os.homedir(), '.claude', '.promptgraph', 'model-cache');
 const BATCH_SIZE = 256;
+const MAX_EMBEDDING_CALLS = 10000;
+let embedCallCount = 0;
+
+export function getEmbedCallCount() { return embedCallCount; }
+export function resetEmbedCallCount() { embedCallCount = 0; }
 
 let model = null;
 
@@ -18,6 +23,7 @@ async function getModel() {
 }
 
 export async function embed(text) {
+  embedCallCount++;
   const m = await getModel();
   const results = [];
   for await (const batch of m.embed([text])) {
@@ -27,6 +33,10 @@ export async function embed(text) {
 }
 
 export async function embedBatch(texts) {
+  if (embedCallCount + texts.length > MAX_EMBEDDING_CALLS) {
+    throw new Error(`Embedding queue limit exceeded (max ${MAX_EMBEDDING_CALLS} chunks per session). Use --fast or reindex incrementally.`);
+  }
+  embedCallCount += texts.length;
   const m = await getModel();
   const all = [];
   for await (const batch of m.embed(texts)) {

package/github-import.js

@@ -45,6 +45,7 @@ async function validateMdFile(file, tmpDir) {
   try {
     const content = await httpsGet(file.download_url);
     const tmpPath = path.join(tmpDir, file.name);
+    fs.mkdirSync(path.dirname(tmpPath), { recursive: true });
     fs.writeFileSync(tmpPath, content);
     const result = validateSkill(tmpPath);
     if (!result.ok) {
@@ -70,17 +71,28 @@ export async function validateRepoSkills(ownerRepo) {
 
   let mdFiles;
   if (detected) {
-    // Has a skills subdirectory — list contents
+    // Has a skills subdirectory — use git tree API for recursive listing
     const subdir = detected.subdir;
-    let entries;
     try {
-      const json = await httpsGet(`https://api.github.com/repos/${ownerRepo}/contents/${subdir}`);
-      entries = JSON.parse(json);
+      const treeJson = await httpsGet(`https://api.github.com/repos/${ownerRepo}/git/trees/HEAD?recursive=1`);
+      const tree = JSON.parse(treeJson);
+      const prefix = subdir + '/';
+      const mdTreeEntries = (tree.tree || []).filter(f =>
+        f.type === 'blob' && f.path.startsWith(prefix) && f.path.endsWith('.md')
+      );
+      let branch = 'main';
+      try {
+        const repoJson = await httpsGet(`https://api.github.com/repos/${ownerRepo}`);
+        branch = JSON.parse(repoJson).default_branch || 'main';
+      } catch {}
+      mdFiles = mdTreeEntries.map(f => ({
+        name: f.path.replace(prefix, ''),
+        download_url: `https://raw.githubusercontent.com/${ownerRepo}/${branch}/${f.path}`
+      }));
     } catch (e) {
       try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch {}
       return { ok: false, errors: [`Failed to list ${subdir}/ contents: ${e.message}`], warnings: [] };
     }
-    mdFiles = entries.filter(e => e.type === 'file' && e.name.endsWith('.md'));
   } else {
     // No skills subdir — fall back to root-level .md files
     try {
@@ -131,6 +143,20 @@ async function detectSkillsDirFromAPI(ownerRepo) {
       if (dirMap.has(d)) return { subdir: dirMap.get(d), label: d };
     }
 
+    // 1.5 Nested skills dirs (e.g. .claude/skills, .claude-plugin/commands)
+    for (const prefix of ['.claude', '.claude-plugin']) {
+      if (dirMap.has(prefix)) {
+        for (const d of SKILL_DIRS) {
+          const nested = `${prefix}/${d}`;
+          try {
+            const sub = await httpsGet(`https://api.github.com/repos/${ownerRepo}/contents/${nested}`);
+            const subEntries = JSON.parse(sub);
+            if (subEntries.length > 0) return { subdir: nested, label: nested };
+          } catch {}
+        }
+      }
+    }
+
     // 2. Any subdir with 2+ .md files — pick the one with most .md files
     const subdirCandidates = entries.filter(e => e.type === 'dir' && !SKIP_DIRS_API.has(e.name.toLowerCase()));
     let best = null, bestCount = 0;
@@ -152,6 +178,8 @@ const SKIP_DIRS_API = new Set([
   '.github', 'docs', 'doc', 'documentation', 'examples', 'example',
   'tests', 'test', 'assets', 'images', 'img', 'media', 'static',
   'node_modules', 'vendor', 'dist', 'build', '.git',
+  'references', 'reference', 'refs', 'cheatsheet', 'cheat-sheet',
+  'cheatsheets', 'resources',
 ]);
 
 function git(args, cwd, stdio = 'inherit') {
@@ -177,16 +205,23 @@ function sparseClone(url, dest, subdir) {
   // Try HEAD, then main, then master
   for (const branch of ['HEAD', 'main', 'master']) {
     const r = git(['checkout', branch === 'HEAD' ? 'FETCH_HEAD' : branch], dest, 'pipe');
-    if (r.status === 0) return true;
+    if (r.status === 0) return finalizeCheckout(dest, true);
   }
   return false;
 }
 
+// Shared skip patterns — module scope so both cleanup functions can access them
+const SKIP_RE = /^(readme|changelog|license|contributing|code.of.conduct|security|authors|credits|install|installation|usage|promotion|faq|glossary|index|overview|summary|roadmap|todo|notes|template|example|sample|demo|guide|tutorial|walkthrough|architecture|design|spec|requirements|privacy|terms|disclaimer|notice|copying|warranty|funding)/i;
+const SKIP_DIRS_LOCAL = new Set([
+  '.github', 'docs', 'doc', 'assets', 'images', 'img', 'screenshots',
+  'media', 'static', 'scripts', 'ci_scripts', 'node_modules', 'vendor',
+  'dist', 'build', 'tests', 'test',
+  'references', 'reference', 'refs', 'cheatsheet', 'cheat-sheet',
+  'cheatsheets', 'resources',
+]);
+
 // After full-clone root: remove files that are not skills and dirs we don't need
 function cleanupRepoRoot(repoRoot) {
-  const SKIP_RE = /^(readme|changelog|license|contributing|code.of.conduct|security|authors|credits|install|installation|usage|promotion|faq|glossary|index|overview|summary|roadmap|todo|notes|template|example|sample|demo|guide|tutorial|walkthrough|architecture|design|spec|requirements|privacy|terms|disclaimer|notice|copying|warranty|funding)/i;
-  const SKIP_DIRS_LOCAL = new Set(['.github', 'docs', 'doc', 'assets', 'images', 'img', 'screenshots', 'media', 'static', 'scripts', 'ci_scripts', 'node_modules', 'vendor', 'dist', 'build', 'tests', 'test']);
-
   let removed = 0;
   const entries = fs.readdirSync(repoRoot, { withFileTypes: true });
   for (const entry of entries) {
@@ -223,9 +258,14 @@ function cleanupRepoDir(dirPath, SKIP_RE) {
   for (const entry of entries) {
     const fullPath = path.join(dirPath, entry.name);
     if (entry.isDirectory()) {
-      removed += cleanupRepoDir(fullPath, SKIP_RE);
-      // Remove empty dirs after cleanup
-      try { if (fs.readdirSync(fullPath).length === 0) fs.rmdirSync(fullPath); } catch {}
+      // Remove entire skip dirs (e.g. references/) nested inside skills dirs
+      if (SKIP_DIRS_LOCAL.has(entry.name.toLowerCase())) {
+        fs.rmSync(fullPath, { recursive: true, force: true });
+        removed++;
+      } else {
+        removed += cleanupRepoDir(fullPath, SKIP_RE);
+        try { if (fs.readdirSync(fullPath).length === 0) fs.rmdirSync(fullPath); } catch {}
+      }
     } else if (entry.isFile() && entry.name.endsWith('.md')) {
       const base = entry.name.replace(/\.md$/i, '').toLowerCase();
       if (SKIP_RE.test(base)) {
@@ -252,28 +292,42 @@ function removeEmptyDirs(dirPath) {
   }
 }
 
-// Update sparse repo — fetch + reset
+// After fetch/checkout: force materialization of all sparse-matched files.
+// partial clone (blob:none) + checkout often skips blob download on Windows.
+function forceMaterialize(dest) {
+  git(['checkout', 'HEAD', '--', '.'], dest, 'pipe');
+}
+
+// Update sparse repo — fetch + checkout
 function sparseUpdate(dest, subdir) {
   const fetch = git(['fetch', '--depth=1', 'origin'], dest);
   if (fetch.status !== 0) return false;
 
-  // Ensure sparse-checkout still set correctly
   git(['sparse-checkout', 'set', '--no-cone', `${subdir}/*.md`, `${subdir}/**/*.md`], dest, 'pipe');
 
-  for (const ref of ['origin/HEAD', 'origin/main', 'origin/master']) {
-    const r = git(['reset', '--hard', ref], dest, 'pipe');
-    if (r.status === 0) return true;
+  for (const ref of ['origin/main', 'origin/master']) {
+    const r = git(['checkout', ref], dest, 'pipe');
+    if (r.status !== 0) continue;
+    forceMaterialize(dest);
+    return true;
   }
   return false;
 }
 
+// After checkout, force materialization of sparse-matched files.
+function finalizeCheckout(dest, success) {
+  if (success) forceMaterialize(dest);
+  return success;
+}
+
 // Fallback: clone root but only checkout .md files
 function fullClone(url, dest) {
   if (fs.existsSync(dest)) {
     const fetch = git(['fetch', '--depth=1', '--filter=blob:none', 'origin'], dest);
     if (fetch.status !== 0) return false;
     for (const ref of ['origin/HEAD', 'origin/main', 'origin/master']) {
-      if (git(['reset', '--hard', ref], dest, 'pipe').status === 0) return true;
+      const ok = git(['reset', '--hard', ref], dest, 'pipe').status === 0;
+      if (ok) return finalizeCheckout(dest, true);
     }
     return false;
   }
@@ -287,13 +341,14 @@ function fullClone(url, dest) {
   if (fetch.status !== 0) return false;
   for (const branch of ['FETCH_HEAD', 'main', 'master']) {
     const r = git(['checkout', branch], dest, 'pipe');
-    if (r.status === 0) return true;
+    if (r.status === 0) return finalizeCheckout(dest, true);
   }
   return false;
 }
 
-// After clone: detect actual skills dir on disk
+// After clone: detect actual skills dir on disk (flat + nested)
 function detectSkillsDirLocal(repoRoot) {
+  // 1. Flat dirs matching SKILL_DIRS (e.g. skills/, commands/)
   for (const dir of SKILL_DIRS) {
     const candidate = path.join(repoRoot, dir);
     if (fs.existsSync(candidate)) {
@@ -301,6 +356,16 @@ function detectSkillsDirLocal(repoRoot) {
       if (files.length >= 1) return { dir: candidate, label: dir, sparse: true };
     }
   }
+  // 2. Nested dirs: .claude/skills, .claude-plugin/commands, etc.
+  for (const prefix of ['.claude', '.claude-plugin']) {
+    for (const dir of SKILL_DIRS) {
+      const candidate = path.join(repoRoot, prefix, dir);
+      if (fs.existsSync(candidate)) {
+        const files = globSync(`${candidate}/**/*.md`);
+        if (files.length >= 1) return { dir: candidate, label: `${prefix}/${dir}`, sparse: true };
+      }
+    }
+  }
   return { dir: repoRoot, label: '(root)', sparse: false };
 }
 
@@ -356,7 +421,17 @@ export async function importFromGitHub(repoUrl) {
     const sparseList = isSparse
       ? spawnSync('git', ['sparse-checkout', 'list'], { cwd: dest, encoding: 'utf8' }).stdout.trim()
       : '';
-    skillsSubdir = sparseList.split('\n').find(l => SKILL_DIRS.includes(l.trim())) || null;
+    skillsSubdir = (() => {
+      const lines = sparseList.split('\n').map(l => l.trim()).filter(Boolean);
+      if (lines.length === 0) return null;
+      const exact = lines.find(l => SKILL_DIRS.includes(l));
+      if (exact) return exact;
+      for (const line of lines) {
+        const m = line.match(/^(.+)\/(?:\*\*\/)?\*\.md$/);
+        if (m && !m[1].includes('*')) return m[1];
+      }
+      return null;
+    })();
 
     cloneOk = skillsSubdir
       ? sparseUpdate(dest, skillsSubdir)
@@ -381,7 +456,12 @@ export async function importFromGitHub(repoUrl) {
     removeEmptyDirs(dest);
   }
 
-  const { dir: skillsDir, label } = detectSkillsDirLocal(dest);
+  const { dir: localDir, label: localLabel } = detectSkillsDirLocal(dest);
+  // Prefer the known skillsSubdir (from API detection or sparse patterns) as the
+  // canonical skills directory — it's more accurate than local heuristics for
+  // repos with non-standard dir names (e.g. "specialized", "cli", or nested paths)
+  const skillsDir = skillsSubdir ? path.join(dest, skillsSubdir) : localDir;
+  const label = skillsSubdir || localLabel;
   const mdFiles = globSync(`${skillsDir}/**/*.md`);
 
   if (skillsSubdir) {