skill-tree 0.1.7 → 0.2.1

package/dist/cli/index.js

@@ -31,11 +31,11 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/storage/base.ts
-var BaseStorageAdapter, MemoryStorageAdapter;
+var _BaseStorageAdapter, BaseStorageAdapter, MemoryStorageAdapter;
 var init_base = __esm({
   "src/storage/base.ts"() {
     "use strict";
-    BaseStorageAdapter = class {
+    _BaseStorageAdapter = class _BaseStorageAdapter {
       constructor() {
         this.initialized = false;
       }
@@ -63,9 +63,6 @@ var init_base = __esm({
           if (filter.author && skill.author !== filter.author) {
             return false;
           }
-          if (filter.minSuccessRate !== void 0 && skill.metrics.successRate < filter.minSuccessRate) {
-            return false;
-          }
           if (filter.createdAfter && skill.createdAt < filter.createdAfter) {
             return false;
           }
@@ -130,19 +127,118 @@ var init_base = __esm({
        * Simple text search across skill fields
        */
       textSearch(skills, query) {
-        const lowerQuery = query.toLowerCase();
-        const terms = lowerQuery.split(/\s+/).filter((t) => t.length > 0);
-        return skills.filter((skill) => {
-          const searchText = [
-            skill.name,
-            skill.description,
-            skill.instructions,
-            ...skill.tags
-          ].join(" ").toLowerCase();
-          return terms.every((term) => searchText.includes(term));
+        const queryTerms = this.tokenize(query);
+        if (queryTerms.length === 0) return [];
+        const N = skills.length;
+        const k1 = 1.5;
+        const b = 0.75;
+        const docs = skills.map((skill) => ({
+          skill,
+          terms: this.tokenize(
+            [skill.name, skill.description, ...skill.tags].join(" ")
+          )
+        }));
+        const avgDl = docs.reduce((sum, d) => sum + d.terms.length, 0) / (N || 1);
+        const df = /* @__PURE__ */ new Map();
+        for (const doc of docs) {
+          const unique = new Set(doc.terms);
+          for (const t of unique) {
+            df.set(t, (df.get(t) ?? 0) + 1);
+          }
+        }
+        const scored = docs.map((doc) => {
+          let score = 0;
+          const tf = /* @__PURE__ */ new Map();
+          for (const t of doc.terms) {
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+          }
+          for (const qt of queryTerms) {
+            const termDf = df.get(qt) ?? 0;
+            if (termDf === 0) continue;
+            const idf = Math.log((N - termDf + 0.5) / (termDf + 0.5) + 1);
+            const termTf = tf.get(qt) ?? 0;
+            const tfNorm = termTf * (k1 + 1) / (termTf + k1 * (1 - b + b * doc.terms.length / avgDl));
+            score += idf * tfNorm;
+          }
+          return { skill: doc.skill, score };
         });
+        return scored.filter((s) => s.score > 0).sort((a, b2) => b2.score - a.score).map((s) => s.skill);
+      }
+      tokenize(text) {
+        return text.toLowerCase().split(/\W+/).filter((t) => t.length > 1 && !_BaseStorageAdapter.STOP_WORDS.has(t)).map((t) => _BaseStorageAdapter.stem(t));
+      }
+      static stem(word) {
+        if (word.length <= 3) return word;
+        let w = word;
+        w = w.replace(/ies$/, "y");
+        w = w.replace(/(ation|tion)$/, "t");
+        w = w.replace(/sion$/, "s");
+        w = w.replace(/(ing|ment|ness|able|ible|ous|ive|ful|less|ize|ise|ance|ence)$/, "");
+        w = w.replace(/([^aeiou])ed$/, "$1");
+        w = w.replace(/es$/, "");
+        w = w.replace(/([^s])s$/, "$1");
+        w = w.replace(/(.)\1$/, "$1");
+        if (w.length <= 1) return word;
+        return w;
       }
     };
+    _BaseStorageAdapter.STOP_WORDS = /* @__PURE__ */ new Set([
+      "the",
+      "a",
+      "an",
+      "is",
+      "are",
+      "was",
+      "were",
+      "be",
+      "been",
+      "being",
+      "have",
+      "has",
+      "had",
+      "do",
+      "does",
+      "did",
+      "will",
+      "would",
+      "could",
+      "should",
+      "may",
+      "might",
+      "shall",
+      "can",
+      "to",
+      "of",
+      "in",
+      "for",
+      "on",
+      "with",
+      "at",
+      "by",
+      "from",
+      "as",
+      "into",
+      "through",
+      "and",
+      "but",
+      "or",
+      "not",
+      "so",
+      "yet",
+      "if",
+      "when",
+      "that",
+      "this",
+      "it",
+      "its",
+      "also",
+      "which",
+      "what",
+      "how",
+      "why",
+      "where"
+    ]);
+    BaseStorageAdapter = _BaseStorageAdapter;
     MemoryStorageAdapter = class extends BaseStorageAdapter {
       constructor() {
         super(...arguments);
@@ -358,12 +454,19 @@ var init_sqlite = __esm({
         status TEXT NOT NULL,
         parent_version TEXT,
         derived_from TEXT,
-        metrics TEXT NOT NULL,
         source TEXT,
         taxonomy TEXT,
         external_source TEXT
       )
     `);
+        try {
+          db.exec("ALTER TABLE skills DROP COLUMN metrics");
+        } catch {
+          const cols = db.prepare("PRAGMA table_info(skills)").all();
+          if (cols.some((c) => c.name === "metrics")) {
+            this.rebuildSkillsTableWithoutMetrics(db, cols);
+          }
+        }
         db.exec(`
       CREATE TABLE IF NOT EXISTS skill_versions (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -527,6 +630,75 @@ var init_sqlite = __esm({
           db.prepare("UPDATE schema_version SET version = ?").run(SCHEMA_VERSION);
         }
       }
+      /**
+       * Rebuild the `skills` table without the legacy `metrics` column.
+       *
+       * Used as the fallback path on SQLite < 3.35 where ALTER TABLE DROP
+       * COLUMN isn't supported. Uses the standard "table dance" pattern:
+       * CREATE NEW → INSERT FROM OLD → DROP OLD → RENAME, inside a single
+       * transaction so a partial state can't outlive a crash.
+       *
+       * The `existingCols` arg is the full PRAGMA table_info output for the
+       * legacy table — we use it to figure out which columns to copy. Some
+       * legacy installs may have a subset of the current schema's columns
+       * (e.g., taxonomy/external_source were added in v2, related in v3),
+       * so we only copy columns that exist on both sides.
+       */
+      rebuildSkillsTableWithoutMetrics(db, existingCols) {
+        const NEW_SCHEMA_COLUMNS = [
+          "id",
+          "version",
+          "name",
+          "description",
+          "instructions",
+          "related",
+          "author",
+          "tags",
+          "created_at",
+          "updated_at",
+          "status",
+          "parent_version",
+          "derived_from",
+          "source",
+          "taxonomy",
+          "external_source"
+        ];
+        const sourceNames = new Set(existingCols.map((c) => c.name));
+        const copyable = NEW_SCHEMA_COLUMNS.filter((c) => sourceNames.has(c));
+        const copyList = copyable.join(", ");
+        db.exec("BEGIN");
+        try {
+          db.exec(`
+        CREATE TABLE skills_new (
+          id TEXT PRIMARY KEY,
+          version TEXT NOT NULL,
+          name TEXT NOT NULL,
+          description TEXT,
+          instructions TEXT NOT NULL DEFAULT '',
+          related TEXT,
+          author TEXT NOT NULL,
+          tags TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          status TEXT NOT NULL,
+          parent_version TEXT,
+          derived_from TEXT,
+          source TEXT,
+          taxonomy TEXT,
+          external_source TEXT
+        )
+      `);
+          db.exec(
+            `INSERT INTO skills_new (${copyList}) SELECT ${copyList} FROM skills`
+          );
+          db.exec("DROP TABLE skills");
+          db.exec("ALTER TABLE skills_new RENAME TO skills");
+          db.exec("COMMIT");
+        } catch (err) {
+          db.exec("ROLLBACK");
+          throw err;
+        }
+      }
       getDb() {
         if (!this.db) {
           throw new Error("Database not initialized. Call initialize() first.");
@@ -539,10 +711,10 @@ var init_sqlite = __esm({
         const stmt = db.prepare(`
       INSERT OR REPLACE INTO skills (
         id, version, name, description, instructions, related, author, tags,
-        created_at, updated_at, status, parent_version, derived_from, metrics,
+        created_at, updated_at, status, parent_version, derived_from,
         source, taxonomy, external_source
       ) VALUES (
-        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
       )
     `);
         stmt.run(
@@ -559,7 +731,6 @@ var init_sqlite = __esm({
           skill.status,
           skill.parentVersion || null,
           skill.derivedFrom ? JSON.stringify(skill.derivedFrom) : null,
-          JSON.stringify(skill.metrics),
           skill.source ? JSON.stringify(skill.source) : null,
           skill.taxonomy ? JSON.stringify(skill.taxonomy) : null,
           skill.externalSource ? JSON.stringify({
@@ -654,10 +825,6 @@ var init_sqlite = __esm({
           sql += " AND author = ?";
           params.push(filter.author);
         }
-        if (filter?.minSuccessRate !== void 0) {
-          sql += " AND json_extract(metrics, '$.successRate') >= ?";
-          params.push(filter.minSuccessRate);
-        }
         if (filter?.createdAfter) {
           sql += " AND created_at >= ?";
           params.push(filter.createdAfter.toISOString());
@@ -853,15 +1020,15 @@ var init_sqlite = __esm({
       /**
        * Get or create a taxonomy node
        */
-      async ensureTaxonomyNode(path18) {
+      async ensureTaxonomyNode(path19) {
         this.ensureInitialized();
         const db = this.getDb();
-        const pathStr = path18.join("/");
+        const pathStr = path19.join("/");
         const existing = db.prepare("SELECT id FROM taxonomy_nodes WHERE path = ?").get(pathStr);
         if (existing) return existing.id;
         const id = `node-${pathStr.replace(/\//g, "-").toLowerCase()}`;
-        const name = path18[path18.length - 1] || "Root";
-        const parentPath = path18.slice(0, -1);
+        const name = path19[path19.length - 1] || "Root";
+        const parentPath = path19.slice(0, -1);
         let parentId = null;
         if (parentPath.length > 0) {
           parentId = await this.ensureTaxonomyNode(parentPath);
@@ -1052,7 +1219,6 @@ var init_sqlite = __esm({
           status: row.status,
           parentVersion: row.parent_version || void 0,
           derivedFrom: row.derived_from ? JSON.parse(row.derived_from) : void 0,
-          metrics: JSON.parse(row.metrics),
           source: row.source ? JSON.parse(row.source) : void 0,
           taxonomy: row.taxonomy ? JSON.parse(row.taxonomy) : void 0,
           externalSource: externalSource ? {
@@ -1069,11 +1235,7 @@ var init_sqlite = __esm({
           source: skill.source ? {
             ...skill.source,
             importedAt: skill.source.importedAt.toISOString()
-          } : void 0,
-          metrics: {
-            ...skill.metrics,
-            lastUsed: skill.metrics.lastUsed?.toISOString()
-          }
+          } : void 0
         };
       }
       deserializeSkill(data) {
@@ -1084,11 +1246,7 @@ var init_sqlite = __esm({
           source: data.source ? {
             ...data.source,
             importedAt: new Date(data.source.importedAt)
-          } : void 0,
-          metrics: {
-            ...data.metrics,
-            lastUsed: data.metrics.lastUsed ? new Date(data.metrics.lastUsed) : void 0
-          }
+          } : void 0
         };
       }
       hashSkill(skill) {
@@ -1294,9 +1452,6 @@ ${this.indentContent(skill.instructions, 4)}
         if (filter.tags && filter.tags.length > 0) {
           result = result.filter((s) => s.tags.some((t) => filter.tags.includes(t)));
         }
-        if (filter.minSuccessRate !== void 0) {
-          result = result.filter((s) => s.metrics.successRate >= filter.minSuccessRate);
-        }
         if (filter.limit) {
           result = result.slice(0, filter.limit);
         }
@@ -1393,11 +1548,6 @@ var init_parser = __esm({
           createdAt: defaults?.createdAt || now,
           updatedAt: now,
           status: "active",
-          metrics: defaults?.metrics || {
-            usageCount: 0,
-            successRate: 0,
-            feedbackScores: []
-          },
           source: {
             type: "imported",
             location: "AGENTS.md",
@@ -1765,8 +1915,6 @@ var init_sync = __esm({
           // Keep existing ID
           createdAt: existing.createdAt,
           // Preserve creation date
-          metrics: existing.metrics,
-          // Preserve usage metrics
           source: incoming.source || existing.source,
           parentVersion: existing.version
           // Track update lineage
@@ -2007,10 +2155,6 @@ var ConflictStore = class {
       ...skill,
       createdAt: skill.createdAt instanceof Date ? skill.createdAt.toISOString() : skill.createdAt,
       updatedAt: skill.updatedAt instanceof Date ? skill.updatedAt.toISOString() : skill.updatedAt,
-      metrics: {
-        ...skill.metrics,
-        lastUsed: skill.metrics?.lastUsed instanceof Date ? skill.metrics.lastUsed.toISOString() : skill.metrics?.lastUsed
-      },
       source: skill.source ? {
         ...skill.source,
         importedAt: skill.source.importedAt instanceof Date ? skill.source.importedAt.toISOString() : skill.source.importedAt
@@ -2022,10 +2166,6 @@ var ConflictStore = class {
       ...data,
       createdAt: new Date(data.createdAt),
       updatedAt: new Date(data.updatedAt),
-      metrics: {
-        ...data.metrics,
-        lastUsed: data.metrics?.lastUsed ? new Date(data.metrics.lastUsed) : void 0
-      },
       source: data.source ? {
         ...data.source,
         importedAt: new Date(data.source.importedAt)
@@ -2592,12 +2732,7 @@ ${remoteValue}`;
       tags: metadata.tags ? metadata.tags.split(",").map((t) => t.trim()) : [],
       createdAt: metadata.created ? new Date(metadata.created) : /* @__PURE__ */ new Date(),
       updatedAt: metadata.updated ? new Date(metadata.updated) : /* @__PURE__ */ new Date(),
-      status: isValidStatus(metadata.status) ? metadata.status : "active",
-      metrics: {
-        usageCount: 0,
-        successRate: 0,
-        feedbackScores: []
-      }
+      status: isValidStatus(metadata.status) ? metadata.status : "active"
     };
   }
   async writeSkill(skill) {
@@ -2884,15 +3019,12 @@ var DEFAULT_CONFIG = {
   maxSummaryLength: 80,
   format: "xml"
 };
-var CatalogRenderer = class _CatalogRenderer {
+var _CatalogRenderer = class _CatalogRenderer {
   constructor(storage, config2) {
     this.storage = storage;
     this.overviewCache = null;
     this.config = { ...DEFAULT_CONFIG, ...config2 };
   }
-  static {
-    this.CACHE_TTL_MS = 6e4;
-  }
   /**
    * Render level-0 catalog overview for system prompt injection.
    * Shows top-level categories with counts. ~200 tokens.
@@ -2920,11 +3052,11 @@ var CatalogRenderer = class _CatalogRenderer {
    * Render a specific category path for browse drill-down.
    * Shows subcategories at intermediate nodes, or skill summaries at leaf nodes.
    */
-  async renderCategory(path18) {
+  async renderCategory(path19) {
     if (hasCatalogSupport(this.storage)) {
-      return this.renderCategoryFromTaxonomy(this.storage, path18);
+      return this.renderCategoryFromTaxonomy(this.storage, path19);
     }
-    return this.renderCategoryFromTags(path18);
+    return this.renderCategoryFromTags(path19);
   }
   /**
    * Invalidate the overview cache (e.g., after skill changes).
@@ -2962,9 +3094,9 @@ var CatalogRenderer = class _CatalogRenderer {
     const categories = counted.sort((a, b) => b.count - a.count).slice(0, this.config.maxCategoriesPerLevel).map((c) => ({ name: c.node.name, count: c.count }));
     return this.renderOverviewXml(totalSkills, categories);
   }
-  async renderCategoryFromTaxonomy(storage, path18) {
-    const tree = await storage.getTaxonomyTree(path18);
-    const pathStr = path18.join("/");
+  async renderCategoryFromTaxonomy(storage, path19) {
+    const tree = await storage.getTaxonomyTree(path19);
+    const pathStr = path19.join("/");
     if (tree.length > 0 && tree.some((n) => n.children.length > 0)) {
       const root = tree[0];
       const rootCount = this.countNodeSkills(root);
@@ -2974,7 +3106,7 @@ var CatalogRenderer = class _CatalogRenderer {
       lines.push(`<catalog_browse path="${escapeXml(pathStr)}" count="${rootCount}">`);
       lines.push("  <subcategories>");
       for (const { node: child, count } of children) {
-        const childPath = [...path18, child.name].join("/");
+        const childPath = [...path19, child.name].join("/");
         lines.push(`    <category path="${escapeXml(childPath)}" count="${count}" />`);
       }
       lines.push("  </subcategories>");
@@ -2998,13 +3130,13 @@ var CatalogRenderer = class _CatalogRenderer {
     const categories = Array.from(tagCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, this.config.maxCategoriesPerLevel).map(([name, count]) => ({ name, count }));
     return this.renderOverviewXml(skills.length, categories);
   }
-  async renderCategoryFromTags(path18) {
-    if (path18.length === 0) {
+  async renderCategoryFromTags(path19) {
+    if (path19.length === 0) {
       return this.renderOverviewFromTags();
     }
-    const tag = path18[0];
+    const tag = path19[0];
     const matching = await this.storage.listSkills({ status: ["active"], tags: [tag] });
-    const pathStr = path18.join("/");
+    const pathStr = path19.join("/");
     return this.renderLeafSkills(matching, pathStr, matching.length);
   }
   // ===========================================================================
@@ -3057,12 +3189,276 @@ var CatalogRenderer = class _CatalogRenderer {
     return count;
   }
 };
+_CatalogRenderer.CACHE_TTL_MS = 6e4;
+var CatalogRenderer = _CatalogRenderer;
+
+// src/serving/term-similarity.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "shall",
+  "can",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "and",
+  "but",
+  "or",
+  "nor",
+  "not",
+  "so",
+  "yet",
+  "both",
+  "either",
+  "neither",
+  "each",
+  "every",
+  "all",
+  "any",
+  "few",
+  "more",
+  "most",
+  "other",
+  "some",
+  "such",
+  "no",
+  "only",
+  "own",
+  "same",
+  "than",
+  "too",
+  "very",
+  "just",
+  "because",
+  "if",
+  "when",
+  "that",
+  "this",
+  "it",
+  "its",
+  "also",
+  "which",
+  "what",
+  "how",
+  "why",
+  "where"
+]);
+function tokenizeList(text) {
+  return text.toLowerCase().split(/\W+/).filter((t) => t.length > 2 && !STOP_WORDS.has(t));
+}
+function tokenize(text) {
+  return new Set(tokenizeList(text));
+}
+
+// src/serving/hybrid-retrieval.ts
+var DEFAULT_FIELD_WEIGHTS = {
+  name: 10,
+  description: 5,
+  body: 5,
+  tags: 3
+};
+var DEFAULTS = {
+  rrfK: 60,
+  bm25K1: 1.2,
+  bm25B: 0.75,
+  bm25Saturation: 8,
+  signalWeights: { lexical: 0.5, dense: 0.5 }
+};
+function buildFieldDoc(skill, fw) {
+  const fields = [
+    [fw.name, tokenizeList(skill.name)],
+    [fw.description, tokenizeList(skill.description)],
+    [fw.body, tokenizeList(skill.instructions ?? "")],
+    [fw.tags, skill.tags.flatMap((t) => tokenizeList(t))]
+  ];
+  const wtf = /* @__PURE__ */ new Map();
+  let dl = 0;
+  for (const [weight, toks] of fields) {
+    if (weight <= 0) continue;
+    dl += weight * toks.length;
+    for (const t of toks) wtf.set(t, (wtf.get(t) ?? 0) + weight);
+  }
+  return { id: skill.id, wtf, dl };
+}
+function bm25Scores(query, skills, fieldWeights = DEFAULT_FIELD_WEIGHTS, k1 = DEFAULTS.bm25K1, b = DEFAULTS.bm25B) {
+  const scores = /* @__PURE__ */ new Map();
+  if (skills.length === 0) return scores;
+  const queryTerms = [...tokenize(query)];
+  const docs = skills.map((s) => buildFieldDoc(s, fieldWeights));
+  const N = docs.length;
+  const avgdl = docs.reduce((sum, d) => sum + d.dl, 0) / N || 1;
+  const df = /* @__PURE__ */ new Map();
+  for (const t of queryTerms) {
+    let count = 0;
+    for (const d of docs) if (d.wtf.has(t)) count++;
+    df.set(t, count);
+  }
+  for (const d of docs) {
+    let score = 0;
+    for (const t of queryTerms) {
+      const f = d.wtf.get(t);
+      if (!f) continue;
+      const n = df.get(t);
+      const idf = Math.log(1 + (N - n + 0.5) / (n + 0.5));
+      const denom = f + k1 * (1 - b + b * (d.dl / avgdl));
+      score += idf * (f * (k1 + 1) / (denom || 1));
+    }
+    scores.set(d.id, score);
+  }
+  return scores;
+}
+function cosineSimilarity(a, b) {
+  const len = Math.min(a.length, b.length);
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < len; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+function reciprocalRankFusion(rankings, k = DEFAULTS.rrfK) {
+  const fused = /* @__PURE__ */ new Map();
+  for (const ranking of rankings) {
+    ranking.forEach((id, idx) => {
+      fused.set(id, (fused.get(id) ?? 0) + 1 / (k + idx + 1));
+    });
+  }
+  return fused;
+}
+function skillEmbedText(skill) {
+  return [
+    skill.name,
+    skill.description,
+    skill.tags.join(" "),
+    skill.instructions ?? ""
+  ].join("\n");
+}
+function rankByScore(scores) {
+  return [...scores.entries()].sort((a, b) => b[1] - a[1]).map(([id]) => id);
+}
+async function scoreSkillsHybrid(query, skills, options = {}) {
+  if (skills.length === 0) return [];
+  const fieldWeights = options.fieldWeights ?? DEFAULT_FIELD_WEIGHTS;
+  const sat = options.bm25Saturation ?? DEFAULTS.bm25Saturation;
+  const raw = bm25Scores(
+    query,
+    skills,
+    fieldWeights,
+    options.bm25K1 ?? DEFAULTS.bm25K1,
+    options.bm25B ?? DEFAULTS.bm25B
+  );
+  const lexAbs = /* @__PURE__ */ new Map();
+  for (const s of skills) {
+    const r = raw.get(s.id) ?? 0;
+    lexAbs.set(s.id, r / (r + sat));
+  }
+  let denseAbs = null;
+  if (options.embedder) {
+    try {
+      const vectors = await options.embedder.embed([
+        query,
+        ...skills.map(skillEmbedText)
+      ]);
+      const queryVec = vectors[0];
+      if (queryVec && vectors.length === skills.length + 1) {
+        denseAbs = /* @__PURE__ */ new Map();
+        skills.forEach((s, i) => {
+          denseAbs.set(s.id, Math.max(0, cosineSimilarity(queryVec, vectors[i + 1])));
+        });
+      }
+    } catch {
+      denseAbs = null;
+    }
+  }
+  const sw = options.signalWeights ?? DEFAULTS.signalWeights;
+  const wLex = sw.lexical;
+  const wDense = denseAbs ? sw.dense : 0;
+  const wSum = wLex + wDense || 1;
+  const useUtility = !!options.utilityScorer?.trained;
+  const scored = skills.map((s) => {
+    const l = lexAbs.get(s.id) ?? 0;
+    const d = denseAbs?.get(s.id) ?? 0;
+    const relevanceScore = useUtility ? options.utilityScorer.score({ skillId: s.id, lexAbs: l, denseAbs: d }) : (wLex * l + wDense * d) / wSum;
+    return { skill: s, relevanceScore };
+  });
+  if (!useUtility && (options.fusion ?? "weighted") === "rrf" && denseAbs) {
+    const rrf = reciprocalRankFusion(
+      [rankByScore(lexAbs), rankByScore(denseAbs)],
+      options.rrfK ?? DEFAULTS.rrfK
+    );
+    scored.sort(
+      (a, b) => (rrf.get(b.skill.id) ?? 0) - (rrf.get(a.skill.id) ?? 0) || b.relevanceScore - a.relevanceScore
+    );
+  } else {
+    scored.sort((a, b) => b.relevanceScore - a.relevanceScore);
+  }
+  if (options.reranker) {
+    const topN = options.rerankTopN ?? 20;
+    const head = scored.slice(0, topN);
+    if (head.length > 1) {
+      const ranked = await options.reranker.rerank(
+        query,
+        head.map((h) => ({
+          id: h.skill.id,
+          text: `${h.skill.name}
+${h.skill.description}
+${h.skill.instructions ?? ""}`
+        }))
+      );
+      const byId = new Map(head.map((h) => [h.skill.id, h.skill]));
+      const fusedDesc = head.map((h) => h.relevanceScore);
+      const reordered = ranked.filter((r) => byId.has(r.id)).map((r, i) => ({ skill: byId.get(r.id), relevanceScore: fusedDesc[i] ?? 0 }));
+      const headIds = new Set(reordered.map((s) => s.skill.id));
+      const tail = scored.filter((s) => !headIds.has(s.skill.id));
+      return [...reordered, ...tail];
+    }
+  }
+  return scored;
+}
 
 // src/serving/loadout-compiler.ts
 var DEFAULT_CONFIG2 = {
   defaultMaxSkills: 15,
   defaultStatus: ["active"],
-  semanticThreshold: 0.6
+  semanticThreshold: 0.6,
+  retrieval: {},
+  scoringPoolSize: 200
 };
 var LoadoutCompiler = class {
   constructor(storage, config2) {
@@ -3073,7 +3469,24 @@ var LoadoutCompiler = class {
     };
   }
   /**
-   * Main entry point - compile skills from criteria
+   * Main entry point - compile skills from criteria.
+   *
+   * Filter pipeline order:
+   *   1. status (initial query)
+   *   2. exclude (drop matching IDs)
+   *   3. tags / tagsAll
+   *   4. author
+   *   5. semantic (currently no-op)
+   *   6. relationships (rootSkills traversal)
+   *   7. **include** — presence guarantee: ensures every ID in the
+   *      include list is in the result regardless of the filters above,
+   *      fetching missing ones from storage as needed. `exclude` still
+   *      wins (excluded IDs are removed from the include list before
+   *      this step).
+   *   8. limits (maxSkills, maxTokens)
+   *
+   * For "restrict to exactly these skills" semantics, combine
+   * `include: [...]` with `maxSkills: include.length`.
    */
   async compile(criteria) {
     const status = criteria.status ?? this.config.defaultStatus;
@@ -3083,6 +3496,7 @@ var LoadoutCompiler = class {
     candidates = this.applyQualityFilters(candidates, criteria);
     candidates = await this.applySemanticFilters(candidates, criteria);
     candidates = await this.applyRelationshipFilters(candidates, criteria);
+    candidates = await this.ensureIncludedPresent(candidates, criteria);
     candidates = this.applyLimits(candidates, criteria);
     return candidates;
   }
@@ -3096,6 +3510,66 @@ var LoadoutCompiler = class {
       maxSkills: this.config.defaultMaxSkills
     });
   }
+  /**
+   * Compile with hybrid-retrieval scoring against a task description
+   * (Tier 1). Returns skills annotated with absolute relevance scores in
+   * [0,1], sorted by descending relevance. Used by the hybrid loadout
+   * strategy to determine which skills should be auto-expanded vs shown
+   * as summaries vs excluded.
+   *
+   * Scoring uses field-weighted BM25 over the skill name/description/body/
+   * tags (the body matters most), optionally fused with dense embeddings
+   * (when an `embedder` is
+   * configured via `retrieval`). The candidate pool is the (filtered) set
+   * up to `scoringPoolSize` — larger than the final loadout — so the ranker
+   * re-ranks a real corpus rather than only a lexically pre-truncated top-N.
+   */
+  async compileWithScoring(taskDescription, criteria) {
+    const baseCriteria = {
+      ...criteria,
+      taskDescription,
+      // Score a broad pool, not the final loadout size. Callers narrow the
+      // result via partitionByConfidence + maxExpanded downstream.
+      maxSkills: criteria?.maxSkills ?? this.config.scoringPoolSize
+    };
+    const skills = await this.compile(baseCriteria);
+    return scoreSkillsHybrid(taskDescription, skills, this.config.retrieval);
+  }
+  /**
+   * Partition scored skills into confidence tiers.
+   * - High confidence (>= expandAbove): should be auto-expanded
+   * - Medium confidence (>= includeAbove): included as summaries
+   * - Below includeAbove: excluded
+   *
+   * Abstain floor (Tier 1, T1.3): if `thresholds.minConfidence` is set and
+   * even the single best-scoring skill is below it, the whole loadout
+   * abstains — every skill is excluded and **nothing** is injected. This
+   * makes "no sufficiently relevant skill" a first-class outcome (B=0),
+   * which prevents irrelevant skills from dragging task success below the
+   * no-skill baseline. `scored` is expected to be sorted descending, but we
+   * defensively take the max rather than assume order.
+   */
+  partitionByConfidence(scored, thresholds) {
+    const expand = [];
+    const summarize = [];
+    const excluded = [];
+    if (thresholds.minConfidence !== void 0) {
+      const topScore = scored.reduce((m, s) => Math.max(m, s.relevanceScore), 0);
+      if (scored.length === 0 || topScore < thresholds.minConfidence) {
+        return { expand, summarize, excluded: [...scored] };
+      }
+    }
+    for (const item of scored) {
+      if (item.relevanceScore >= thresholds.expandAbove) {
+        expand.push(item);
+      } else if (item.relevanceScore >= thresholds.includeAbove) {
+        summarize.push(item);
+      } else {
+        excluded.push(item);
+      }
+    }
+    return { expand, summarize, excluded };
+  }
   /**
    * Compile from a named profile
    */
@@ -3128,7 +3602,9 @@ var LoadoutCompiler = class {
   // Filter Methods
   // ===========================================================================
   /**
-   * Apply explicit include/exclude filters
+   * Apply explicit exclude filter. Include is handled separately at the
+   * compile level (see `ensureIncludedPresent`) so it can guarantee
+   * presence regardless of the other filters in this method or below.
    */
   applyExplicitFilters(skills, criteria) {
     let result = skills;
@@ -3136,15 +3612,6 @@ var LoadoutCompiler = class {
       const excludeSet = new Set(criteria.exclude);
       result = result.filter((s) => !excludeSet.has(s.id));
     }
-    if (criteria.include && criteria.include.length > 0) {
-      const includeSet = new Set(criteria.include);
-      const currentIds = new Set(result.map((s) => s.id));
-      const includedSkills = result.filter((s) => includeSet.has(s.id));
-      const otherSkills = result.filter((s) => !includeSet.has(s.id));
-      if (includedSkills.length > 0) {
-        result = [...includedSkills, ...otherSkills];
-      }
-    }
     return result;
   }
   /**
@@ -3168,24 +3635,37 @@ var LoadoutCompiler = class {
    */
   applyQualityFilters(skills, criteria) {
     let result = skills;
-    if (criteria.minSuccessRate !== void 0) {
-      result = result.filter(
-        (s) => s.metrics.successRate >= criteria.minSuccessRate
-      );
-    }
     if (criteria.author) {
       result = result.filter((s) => s.author === criteria.author);
     }
     return result;
   }
   /**
-   * Apply semantic filters (task description, problem context, etc.)
+   * Apply semantic filters (task description matching).
    *
-   * Currently returns skills unchanged. Semantic matching was removed;
-   * use SQLite FTS via storage.searchSkills() for keyword-based search.
+   * When `taskDescription` is provided, uses storage.searchSkills()
+   * to find matching skills and boosts them to the front. Skills not
+   * matching the search are retained at lower priority so that tag
+   * filters and explicit includes still work.
    */
-  async applySemanticFilters(skills, _criteria) {
-    return skills;
+  async applySemanticFilters(skills, criteria) {
+    if (!criteria.taskDescription) return skills;
+    const searchResults = await this.storage.searchSkills(criteria.taskDescription);
+    const searchIds = new Set(searchResults.map((s) => s.id));
+    const candidateIds = new Set(skills.map((s) => s.id));
+    const boosted = [];
+    const rest = [];
+    for (const s of searchResults) {
+      if (candidateIds.has(s.id)) {
+        boosted.push(s);
+      }
+    }
+    for (const s of skills) {
+      if (!searchIds.has(s.id)) {
+        rest.push(s);
+      }
+    }
+    return [...boosted, ...rest];
   }
   /**
    * Apply relationship-based filters (root skills, dependencies)
@@ -3230,28 +3710,47 @@ var LoadoutCompiler = class {
     }
     return skills.filter((s) => result.has(s.id));
   }
+  /**
+   * Ensure every ID in `criteria.include` is present in the result,
+   * regardless of which earlier filter would have dropped it. Missing
+   * skills are fetched directly from storage.
+   *
+   * `criteria.exclude` still wins: an ID listed in both `include` and
+   * `exclude` is treated as excluded (consistent with openteams' "deny
+   * wins" inheritance rule on permissions).
+   *
+   * Included skills are placed at the front of the result, preserving
+   * the order of `criteria.include`. Other skills retain their relative
+   * order behind them.
+   */
+  async ensureIncludedPresent(current, criteria) {
+    if (!criteria.include?.length) return current;
+    const excludeSet = new Set(criteria.exclude ?? []);
+    const effectiveInclude = criteria.include.filter(
+      (id) => !excludeSet.has(id)
+    );
+    if (effectiveInclude.length === 0) return current;
+    const currentById = new Map(current.map((s) => [s.id, s]));
+    const ordered = [];
+    for (const id of effectiveInclude) {
+      const existing = currentById.get(id);
+      if (existing) {
+        ordered.push(existing);
+        currentById.delete(id);
+        continue;
+      }
+      const fetched = await this.storage.getSkill(id);
+      if (fetched) {
+        ordered.push(fetched);
+      }
+    }
+    return [...ordered, ...currentById.values()];
+  }
   /**
    * Apply limits and sorting
    */
   applyLimits(skills, criteria) {
     let result = skills;
-    if (criteria.priorityOrder) {
-      result = [...result].sort((a, b) => {
-        switch (criteria.priorityOrder) {
-          case "usage":
-            return b.metrics.usageCount - a.metrics.usageCount;
-          case "successRate":
-            return b.metrics.successRate - a.metrics.successRate;
-          case "recent":
-            const aDate = a.metrics.lastUsed?.getTime() ?? 0;
-            const bDate = b.metrics.lastUsed?.getTime() ?? 0;
-            return bDate - aDate;
-          case "relevance":
-          default:
-            return 0;
-        }
-      });
-    }
     const maxSkills = criteria.maxSkills ?? this.config.defaultMaxSkills;
     if (result.length > maxSkills) {
       result = result.slice(0, maxSkills);
@@ -3289,76 +3788,11 @@ var LoadoutCompiler = class {
 // src/serving/project-detector.ts
 var import_fs = require("fs");
 var import_path = require("path");
-var ProjectDetector = class _ProjectDetector {
+var _ProjectDetector = class _ProjectDetector {
   constructor() {
     /** Cache for project context */
     this.cache = /* @__PURE__ */ new Map();
   }
-  static {
-    /** Project type patterns */
-    this.PROJECT_TYPES = [
-      { manifestFile: "package.json", type: "nodejs", tags: ["nodejs", "javascript"], packageManager: "npm" },
-      { manifestFile: "pyproject.toml", type: "python", tags: ["python"], packageManager: "pip" },
-      { manifestFile: "requirements.txt", type: "python", tags: ["python"], packageManager: "pip" },
-      { manifestFile: "Cargo.toml", type: "rust", tags: ["rust"], packageManager: "cargo" },
-      { manifestFile: "go.mod", type: "go", tags: ["go", "golang"] },
-      { manifestFile: "pom.xml", type: "java", tags: ["java", "maven"], packageManager: "maven" },
-      { manifestFile: "build.gradle", type: "java", tags: ["java", "gradle"], packageManager: "gradle" },
-      { manifestFile: "build.gradle.kts", type: "kotlin", tags: ["kotlin", "gradle"], packageManager: "gradle" }
-    ];
-  }
-  static {
-    /** TypeScript detection */
-    this.TYPESCRIPT_FILES = ["tsconfig.json", "tsconfig.base.json"];
-  }
-  static {
-    /** Node.js framework patterns */
-    this.NODE_FRAMEWORKS = [
-      { name: "react", packageName: "react", tags: ["react", "frontend"] },
-      { name: "next", packageName: "next", tags: ["nextjs", "react", "fullstack"] },
-      { name: "vue", packageName: "vue", tags: ["vue", "frontend"] },
-      { name: "nuxt", packageName: "nuxt", tags: ["nuxt", "vue", "fullstack"] },
-      { name: "angular", packageName: "@angular/core", tags: ["angular", "frontend"] },
-      { name: "svelte", packageName: "svelte", tags: ["svelte", "frontend"] },
-      { name: "express", packageName: "express", tags: ["express", "backend", "api"] },
-      { name: "fastify", packageName: "fastify", tags: ["fastify", "backend", "api"] },
-      { name: "nestjs", packageName: "@nestjs/core", tags: ["nestjs", "backend", "api"] },
-      { name: "hono", packageName: "hono", tags: ["hono", "backend", "api"] },
-      { name: "prisma", packageName: "@prisma/client", tags: ["prisma", "database", "orm"] },
-      { name: "drizzle", packageName: "drizzle-orm", tags: ["drizzle", "database", "orm"] },
-      { name: "typeorm", packageName: "typeorm", tags: ["typeorm", "database", "orm"] },
-      { name: "jest", packageName: "jest", tags: ["testing", "jest"] },
-      { name: "vitest", packageName: "vitest", tags: ["testing", "vitest"] },
-      { name: "playwright", packageName: "@playwright/test", tags: ["testing", "e2e", "playwright"] },
-      { name: "cypress", packageName: "cypress", tags: ["testing", "e2e", "cypress"] }
-    ];
-  }
-  static {
-    /** Python framework patterns (from pyproject.toml or requirements.txt) */
-    this.PYTHON_FRAMEWORKS = [
-      { name: "fastapi", packageName: "fastapi", tags: ["fastapi", "backend", "api"] },
-      { name: "django", packageName: "django", tags: ["django", "backend", "fullstack"] },
-      { name: "flask", packageName: "flask", tags: ["flask", "backend", "api"] },
-      { name: "sqlalchemy", packageName: "sqlalchemy", tags: ["sqlalchemy", "database", "orm"] },
-      { name: "pytest", packageName: "pytest", tags: ["testing", "pytest"] },
-      { name: "pydantic", packageName: "pydantic", tags: ["pydantic", "validation"] }
-    ];
-  }
-  static {
-    /** Directory patterns */
-    this.DIRECTORY_PATTERNS = [
-      { pattern: ".github/workflows", feature: "github-actions", tags: ["ci", "github-actions"] },
-      { pattern: ".gitlab-ci.yml", feature: "gitlab-ci", tags: ["ci", "gitlab"] },
-      { pattern: "Dockerfile", feature: "docker", tags: ["docker", "containers"] },
-      { pattern: "docker-compose.yml", feature: "docker-compose", tags: ["docker", "containers"] },
-      { pattern: "docker-compose.yaml", feature: "docker-compose", tags: ["docker", "containers"] },
-      { pattern: "terraform", feature: "terraform", tags: ["terraform", "infrastructure"] },
-      { pattern: "kubernetes", feature: "kubernetes", tags: ["kubernetes", "infrastructure"] },
-      { pattern: "k8s", feature: "kubernetes", tags: ["kubernetes", "infrastructure"] },
-      { pattern: ".env.example", feature: "env-config", tags: ["configuration"] },
-      { pattern: "prisma/schema.prisma", feature: "prisma", tags: ["prisma", "database"] }
-    ];
-  }
   /**
    * Detect project context from a directory
    */
@@ -3520,6 +3954,62 @@ var ProjectDetector = class _ProjectDetector {
     }
   }
 };
+/** Project type patterns */
+_ProjectDetector.PROJECT_TYPES = [
+  { manifestFile: "package.json", type: "nodejs", tags: ["nodejs", "javascript"], packageManager: "npm" },
+  { manifestFile: "pyproject.toml", type: "python", tags: ["python"], packageManager: "pip" },
+  { manifestFile: "requirements.txt", type: "python", tags: ["python"], packageManager: "pip" },
+  { manifestFile: "Cargo.toml", type: "rust", tags: ["rust"], packageManager: "cargo" },
+  { manifestFile: "go.mod", type: "go", tags: ["go", "golang"] },
+  { manifestFile: "pom.xml", type: "java", tags: ["java", "maven"], packageManager: "maven" },
+  { manifestFile: "build.gradle", type: "java", tags: ["java", "gradle"], packageManager: "gradle" },
+  { manifestFile: "build.gradle.kts", type: "kotlin", tags: ["kotlin", "gradle"], packageManager: "gradle" }
+];
+/** TypeScript detection */
+_ProjectDetector.TYPESCRIPT_FILES = ["tsconfig.json", "tsconfig.base.json"];
+/** Node.js framework patterns */
+_ProjectDetector.NODE_FRAMEWORKS = [
+  { name: "react", packageName: "react", tags: ["react", "frontend"] },
+  { name: "next", packageName: "next", tags: ["nextjs", "react", "fullstack"] },
+  { name: "vue", packageName: "vue", tags: ["vue", "frontend"] },
+  { name: "nuxt", packageName: "nuxt", tags: ["nuxt", "vue", "fullstack"] },
+  { name: "angular", packageName: "@angular/core", tags: ["angular", "frontend"] },
+  { name: "svelte", packageName: "svelte", tags: ["svelte", "frontend"] },
+  { name: "express", packageName: "express", tags: ["express", "backend", "api"] },
+  { name: "fastify", packageName: "fastify", tags: ["fastify", "backend", "api"] },
+  { name: "nestjs", packageName: "@nestjs/core", tags: ["nestjs", "backend", "api"] },
+  { name: "hono", packageName: "hono", tags: ["hono", "backend", "api"] },
+  { name: "prisma", packageName: "@prisma/client", tags: ["prisma", "database", "orm"] },
+  { name: "drizzle", packageName: "drizzle-orm", tags: ["drizzle", "database", "orm"] },
+  { name: "typeorm", packageName: "typeorm", tags: ["typeorm", "database", "orm"] },
+  { name: "jest", packageName: "jest", tags: ["testing", "jest"] },
+  { name: "vitest", packageName: "vitest", tags: ["testing", "vitest"] },
+  { name: "playwright", packageName: "@playwright/test", tags: ["testing", "e2e", "playwright"] },
+  { name: "cypress", packageName: "cypress", tags: ["testing", "e2e", "cypress"] }
+];
+/** Python framework patterns (from pyproject.toml or requirements.txt) */
+_ProjectDetector.PYTHON_FRAMEWORKS = [
+  { name: "fastapi", packageName: "fastapi", tags: ["fastapi", "backend", "api"] },
+  { name: "django", packageName: "django", tags: ["django", "backend", "fullstack"] },
+  { name: "flask", packageName: "flask", tags: ["flask", "backend", "api"] },
+  { name: "sqlalchemy", packageName: "sqlalchemy", tags: ["sqlalchemy", "database", "orm"] },
+  { name: "pytest", packageName: "pytest", tags: ["testing", "pytest"] },
+  { name: "pydantic", packageName: "pydantic", tags: ["pydantic", "validation"] }
+];
+/** Directory patterns */
+_ProjectDetector.DIRECTORY_PATTERNS = [
+  { pattern: ".github/workflows", feature: "github-actions", tags: ["ci", "github-actions"] },
+  { pattern: ".gitlab-ci.yml", feature: "gitlab-ci", tags: ["ci", "gitlab"] },
+  { pattern: "Dockerfile", feature: "docker", tags: ["docker", "containers"] },
+  { pattern: "docker-compose.yml", feature: "docker-compose", tags: ["docker", "containers"] },
+  { pattern: "docker-compose.yaml", feature: "docker-compose", tags: ["docker", "containers"] },
+  { pattern: "terraform", feature: "terraform", tags: ["terraform", "infrastructure"] },
+  { pattern: "kubernetes", feature: "kubernetes", tags: ["kubernetes", "infrastructure"] },
+  { pattern: "k8s", feature: "kubernetes", tags: ["kubernetes", "infrastructure"] },
+  { pattern: ".env.example", feature: "env-config", tags: ["configuration"] },
+  { pattern: "prisma/schema.prisma", feature: "prisma", tags: ["prisma", "database"] }
+];
+var ProjectDetector = _ProjectDetector;
 
 // src/serving/view-renderer.ts
 var DEFAULT_CONFIG3 = {
@@ -3573,6 +4063,9 @@ var ViewRenderer = class {
         lines.push(`<skill id="${this.escapeXml(id)}" state="available">`);
         lines.push(`  <name>${this.escapeXml(skill.name)}</name>`);
         lines.push(`  <description>${this.escapeXml(summary)}</description>`);
+        if (skill.serving?.instructionPreview) {
+          lines.push(`  <key_insight>${this.escapeXml(skill.serving.instructionPreview)}</key_insight>`);
+        }
         if (skill.tags.length > 0) {
           lines.push(`  <tags>${skill.tags.map((t) => this.escapeXml(t)).join(", ")}</tags>`);
         }
@@ -3711,8 +4204,11 @@ var ViewRenderer = class {
    */
   estimateSummaryTokens(skill) {
     const summary = this.getSummary(skill);
-    const content = [skill.name, summary, skill.tags.join(" ")].join(" ");
-    return Math.ceil(content.length / 4);
+    const parts = [skill.name, summary, skill.tags.join(" ")];
+    if (skill.serving?.instructionPreview) {
+      parts.push(skill.serving.instructionPreview);
+    }
+    return Math.ceil(parts.join(" ").length / 4);
   }
 };
 
@@ -3741,7 +4237,6 @@ var securityProfile = {
   tagsAll: ["security"],
   taskDescription: "security review, vulnerability detection, secure coding",
   maxSkills: 8,
-  minSuccessRate: 0.7,
   priorityOrder: "relevance"
 };
 var testingProfile = {
@@ -3780,6 +4275,10 @@ var builtInProfiles = {
 };
 
 // src/serving/graph-server.ts
+var DEFAULT_CONFIDENCE_THRESHOLDS = {
+  expandAbove: 0.3,
+  includeAbove: 0.15
+};
 var DEFAULT_CONFIG4 = {
   agentCanModify: true,
   agentCanSetLoadout: false,
@@ -3787,8 +4286,16 @@ var DEFAULT_CONFIG4 = {
   requireApproval: false,
   autoExpandOnUse: true,
   autoExpandRelated: true,
-  maxExpanded: 5,
+  // Default cap on simultaneously-expanded (full-body) skills. Set to 3:
+  // on the SkillsBench selection benchmark the true-positive skill lands in
+  // the top 3 every time, so 3 (vs 5) lifts loadout precision ~23%→38% with
+  // zero recall loss — fewer irrelevant bodies injected into context.
+  maxExpanded: 3,
   evictionStrategy: "lru",
+  confidenceThresholds: DEFAULT_CONFIDENCE_THRESHOLDS,
+  retrieval: {},
+  scoringPoolSize: 200,
+  deferExpansion: false,
   persistState: false,
   outputFormat: "xml",
   includeTokenEstimates: false,
@@ -3796,18 +4303,22 @@ var DEFAULT_CONFIG4 = {
   profiles: {}
 };
 var SkillGraphServer = class {
-  // Track LRU for eviction
   constructor(storage, config2) {
     this.storage = storage;
     this.catalogRenderer = null;
     this.handlers = /* @__PURE__ */ new Set();
     this.lruOrder = [];
+    this.relevanceScores = /* @__PURE__ */ new Map();
     this.config = {
       ...DEFAULT_CONFIG4,
       ...config2,
-      profiles: { ...builtInProfiles, ...DEFAULT_CONFIG4.profiles, ...config2?.profiles }
+      profiles: { ...builtInProfiles, ...DEFAULT_CONFIG4.profiles, ...config2?.profiles },
+      confidenceThresholds: { ...DEFAULT_CONFIDENCE_THRESHOLDS, ...config2?.confidenceThresholds }
     };
-    this.compiler = new LoadoutCompiler(storage);
+    this.compiler = new LoadoutCompiler(storage, {
+      retrieval: this.config.retrieval,
+      scoringPoolSize: this.config.scoringPoolSize
+    });
     this.projectDetector = new ProjectDetector();
     this.viewRenderer = new ViewRenderer({
       includeTokenEstimates: this.config.includeTokenEstimates
@@ -3848,11 +4359,32 @@ var SkillGraphServer = class {
     return this.applyLoadout(skills, { type: "criteria", criteria });
   }
   /**
-   * Set loadout based on task description (semantic matching)
+   * Set loadout based on task description using hybrid confidence-tiered
+   * compilation. Skills above the high threshold are auto-expanded,
+   * skills between high and low thresholds are included as summaries,
+   * and skills below the low threshold are excluded.
+   *
+   * Stores relevance scores for use by the 'relevance' eviction strategy.
    */
   async setLoadoutForTask(taskDescription) {
-    const skills = await this.compiler.compileForTask(taskDescription);
-    return this.applyLoadout(skills, { type: "task", taskDescription });
+    const scored = await this.compiler.compileWithScoring(taskDescription);
+    const { expand, summarize, excluded } = this.compiler.partitionByConfidence(
+      scored,
+      this.config.confidenceThresholds
+    );
+    const allIncluded = [...expand, ...summarize];
+    const skills = allIncluded.map((s) => s.skill);
+    const state = this.applyLoadout(skills, { type: "task", taskDescription });
+    for (const item of allIncluded) {
+      this.relevanceScores.set(item.skill.id, item.relevanceScore);
+    }
+    for (const item of expand) {
+      if (this.state.expanded.size >= this.config.maxExpanded) break;
+      this.state.expanded.add(item.skill.id);
+      this.touchLru(item.skill.id);
+      this.emit({ type: "skill:expanded", skillId: item.skill.id });
+    }
+    return state;
   }
   /**
    * Set loadout based on detected project context
@@ -3989,16 +4521,6 @@ var SkillGraphServer = class {
     this.emit({ type: "skill:collapsed", skillId });
     return true;
   }
-  /**
-   * Record skill usage (for LRU tracking and auto-expansion)
-   */
-  recordUsage(skillId) {
-    if (!this.state.available.has(skillId)) return;
-    this.touchLru(skillId);
-    if (this.config.autoExpandOnUse && !this.state.expanded.has(skillId)) {
-      this.expandSkill(skillId);
-    }
-  }
   // ===========================================================================
   // AGENT API - Methods for agent-side modifications
   // ===========================================================================
@@ -4062,12 +4584,8 @@ var SkillGraphServer = class {
    * Returns skill summaries for display
    */
   async agentSearchSkills(query, limit = 5) {
-    const allSkills = await this.storage.listSkills({ status: ["active"] });
-    const queryLower = query.toLowerCase();
-    const matches = allSkills.filter(
-      (skill) => skill.name.toLowerCase().includes(queryLower) || skill.description.toLowerCase().includes(queryLower) || skill.instructions.toLowerCase().includes(queryLower) || skill.tags.some((tag) => tag.toLowerCase().includes(queryLower))
-    ).slice(0, limit);
-    return matches.map((skill) => ({
+    const matches = await this.storage.searchSkills(query);
+    return matches.slice(0, limit).map((skill) => ({
       id: skill.id,
       name: skill.name,
       description: this.getSummary(skill),
@@ -4108,19 +4626,19 @@ var SkillGraphServer = class {
    * Returns rendered category view (subcategories or skill summaries at leaf).
    * Pass no path for the top-level overview.
    */
-  async agentBrowseCatalog(path18) {
+  async agentBrowseCatalog(path19) {
     if (!this.catalogRenderer) {
       return "<error>Catalog browsing is not enabled</error>";
     }
-    if (!path18 || path18.length === 0) {
+    if (!path19 || path19.length === 0) {
       const result2 = await this.catalogRenderer.renderOverview();
       if (result2) {
         this.emit({ type: "catalog:browsed", path: [] });
       }
       return result2;
     }
-    const result = await this.catalogRenderer.renderCategory(path18);
-    this.emit({ type: "catalog:browsed", path: path18 });
+    const result = await this.catalogRenderer.renderCategory(path19);
+    this.emit({ type: "catalog:browsed", path: path19 });
     return result;
   }
   /**
@@ -4152,13 +4670,25 @@ var SkillGraphServer = class {
   /**
    * Render current state as system prompt content.
    * Includes catalog overview when catalog is enabled.
+   *
+   * When `deferExpansion` is enabled, all skills are rendered as
+   * summaries regardless of expansion state — the agent must
+   * explicitly request expansion. This avoids the reactive-signals
+   * problem where upfront skill injection derails model planning.
    */
   async renderSystemPrompt() {
+    let renderState = this.state;
+    if (this.config.deferExpansion) {
+      renderState = {
+        ...this.state,
+        expanded: /* @__PURE__ */ new Set()
+      };
+    }
     let prompt;
     if (this.config.outputFormat === "markdown") {
-      prompt = this.viewRenderer.renderMarkdown(this.state);
+      prompt = this.viewRenderer.renderMarkdown(renderState);
     } else {
-      prompt = this.viewRenderer.renderXml(this.state);
+      prompt = this.viewRenderer.renderXml(renderState);
     }
     if (this.catalogRenderer) {
       const overview = await this.catalogRenderer.renderOverview();
@@ -4196,21 +4726,70 @@ var SkillGraphServer = class {
   // PRIVATE HELPERS
   // ===========================================================================
   /**
-   * Apply a new set of skills as the loadout
+   * Get the relevance score for a skill (0 if not scored).
+   */
+  getRelevanceScore(skillId) {
+    return this.relevanceScores.get(skillId) ?? 0;
+  }
+  /**
+   * Apply a new set of skills as the loadout.
+   * After populating the available set, evaluates autoExpand triggers
+   * on each skill to determine if any should be pre-expanded.
    */
   applyLoadout(skills, source) {
     this.state.available.clear();
     this.state.expanded.clear();
     this.state.pending.clear();
     this.lruOrder = [];
+    this.relevanceScores.clear();
     for (const skill of skills) {
       this.state.available.set(skill.id, skill);
     }
+    this.evaluateAutoExpand(source);
     this.state.source = source;
     this.state.updatedAt = /* @__PURE__ */ new Date();
     this.emit({ type: "loadout:changed", state: this.state });
     return this.state;
   }
+  /**
+   * Evaluate autoExpand trigger conditions for all skills in the loadout.
+   * Checks keyword matches against the task description, file pattern
+   * matches against the project path, and framework matches.
+   */
+  evaluateAutoExpand(source) {
+    const taskText = source.taskDescription ?? "";
+    for (const [id, skill] of this.state.available) {
+      if (this.state.expanded.size >= this.config.maxExpanded) break;
+      if (this.state.expanded.has(id)) continue;
+      const triggers = skill.serving?.autoExpand;
+      if (!triggers || triggers.length === 0) continue;
+      for (const trigger of triggers) {
+        if (this.matchesTrigger(trigger, taskText, source)) {
+          this.state.expanded.add(id);
+          this.touchLru(id);
+          this.emit({ type: "skill:expanded", skillId: id });
+          break;
+        }
+      }
+    }
+  }
+  /**
+   * Check if a single autoExpand trigger matches the current context.
+   */
+  matchesTrigger(trigger, taskText, source) {
+    const conditions = trigger.conditions;
+    if (!conditions) return false;
+    const taskLower = taskText.toLowerCase();
+    if (trigger.on === "mention" && conditions.keywords?.length) {
+      return conditions.keywords.some((kw) => taskLower.includes(kw.toLowerCase()));
+    }
+    if (trigger.on === "file-match" && conditions.filePatterns?.length && source.projectPath) {
+      return conditions.filePatterns.some(
+        (pattern) => source.projectPath.includes(pattern)
+      );
+    }
+    return false;
+  }
   /**
    * Evict a skill from expanded based on strategy
    */
@@ -4221,7 +4800,7 @@ var SkillGraphServer = class {
       case "lru":
         toEvict = this.lruOrder.shift();
         break;
-      case "priority":
+      case "priority": {
         let lowestPriority = Infinity;
         for (const id of this.state.expanded) {
           const skill = this.state.available.get(id);
@@ -4232,6 +4811,18 @@ var SkillGraphServer = class {
           }
         }
         break;
+      }
+      case "relevance": {
+        let lowestScore = Infinity;
+        for (const id of this.state.expanded) {
+          const score = this.relevanceScores.get(id) ?? 0;
+          if (score < lowestScore) {
+            lowestScore = score;
+            toEvict = id;
+          }
+        }
+        break;
+      }
       case "manual":
         return;
     }
@@ -5116,12 +5707,7 @@ ${err.stderr || err.message}`
       tags: this.parseTags(metadata.tags),
       createdAt: metadata.created ? new Date(metadata.created) : /* @__PURE__ */ new Date(),
       updatedAt: metadata.updated ? new Date(metadata.updated) : /* @__PURE__ */ new Date(),
-      status: metadata.status || "active",
-      metrics: {
-        usageCount: parseInt(metadata.usageCount) || 0,
-        successRate: parseFloat(metadata.successRate) || 0,
-        feedbackScores: []
-      }
+      status: metadata.status || "active"
     };
   }
   /**
@@ -5190,9 +5776,6 @@ ${body.join("\n")}
       if (filter.author && skill.author !== filter.author) {
         return false;
       }
-      if (filter.minSuccessRate !== void 0 && skill.metrics.successRate < filter.minSuccessRate) {
-        return false;
-      }
       if (filter.createdAfter && skill.createdAt < filter.createdAfter) {
         return false;
       }
@@ -6011,11 +6594,6 @@ ${skill.instructions}
       status,
       parentVersion: parentVersion || void 0,
       derivedFrom: derivedFrom.length > 0 ? derivedFrom : void 0,
-      metrics: {
-        usageCount: 0,
-        successRate: 0,
-        feedbackScores: []
-      },
       source: metadata?.source,
       upstream,
       namespace: metadata?.namespace
@@ -6462,11 +7040,6 @@ var LineageTracker = class {
       createdAt: /* @__PURE__ */ new Date(),
       updatedAt: /* @__PURE__ */ new Date(),
       status: "draft",
-      metrics: {
-        usageCount: 0,
-        successRate: 0,
-        feedbackScores: []
-      },
       source: {
         type: "composed",
         importedAt: /* @__PURE__ */ new Date()
@@ -7593,41 +8166,15 @@ var SkillBank = class {
     }
   }
   /**
-   * Handle events from serving layer
+   * Handle events from serving layer.
+   *
+   * The `loadout:changed` event is currently the only one we react to.
+   * Earlier versions also handled `skill:used` / `skill:feedback` to mutate
+   * `Skill.metrics`, but skill-tree no longer tracks per-skill usage —
+   * cognitive-core owns that signal via `playbook.evolution.*`.
    */
   async handleServingEvent(event) {
     switch (event.type) {
-      case "skill:used":
-        const skill = await this.storage.getSkill(event.skillId);
-        if (skill) {
-          skill.metrics.usageCount++;
-          skill.metrics.lastUsed = /* @__PURE__ */ new Date();
-          if (event.success) {
-            const total = skill.metrics.usageCount;
-            const currentSuccesses = skill.metrics.successRate * (total - 1);
-            skill.metrics.successRate = (currentSuccesses + 1) / total;
-          } else {
-            const total = skill.metrics.usageCount;
-            const currentSuccesses = skill.metrics.successRate * (total - 1);
-            skill.metrics.successRate = currentSuccesses / total;
-          }
-          skill.updatedAt = /* @__PURE__ */ new Date();
-          await this.storage.saveSkill(skill);
-        }
-        break;
-      case "skill:feedback":
-        const feedbackSkill = await this.storage.getSkill(event.skillId);
-        if (feedbackSkill) {
-          feedbackSkill.metrics.feedbackScores.push(event.score);
-          if (feedbackSkill.metrics.feedbackScores.length > 50) {
-            feedbackSkill.metrics.feedbackScores = feedbackSkill.metrics.feedbackScores.slice(-50);
-          }
-          feedbackSkill.updatedAt = /* @__PURE__ */ new Date();
-          await this.storage.saveSkill(feedbackSkill);
-        }
-        break;
-      case "skill:requested":
-        break;
       case "loadout:changed":
         break;
     }
@@ -7649,26 +8196,17 @@ var SkillBank = class {
         deprecated: 0,
         experimental: 0
       },
-      byTag: {},
-      avgSuccessRate: 0,
-      totalUsage: 0
+      byTag: {}
     };
     if (this.namespaceConfig) {
       stats.byScope = { personal: 0, team: 0, global: 0 };
       stats.byVisibility = { private: 0, "team-only": 0, public: 0 };
     }
-    let successRateSum = 0;
-    let successRateCount = 0;
     for (const skill of skills) {
       stats.byStatus[skill.status]++;
       for (const tag of skill.tags) {
         stats.byTag[tag] = (stats.byTag[tag] || 0) + 1;
       }
-      stats.totalUsage += skill.metrics.usageCount;
-      if (skill.metrics.successRate > 0) {
-        successRateSum += skill.metrics.successRate;
-        successRateCount++;
-      }
       if (stats.byScope && stats.byVisibility) {
         const scope = skill.namespace?.scope || "personal";
         const visibility = skill.namespace?.visibility || "private";
@@ -7676,7 +8214,6 @@ var SkillBank = class {
         stats.byVisibility[visibility]++;
       }
     }
-    stats.avgSuccessRate = successRateCount > 0 ? successRateSum / successRateCount : 0;
     return stats;
   }
   /**
@@ -7866,8 +8403,8 @@ function substituteEnvVarsInObject(obj) {
   }
   return obj;
 }
-function setNestedProperty(obj, path18, value) {
-  const parts = path18.split(".");
+function setNestedProperty(obj, path19, value) {
+  const parts = path19.split(".");
   let current = obj;
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
@@ -8026,8 +8563,8 @@ var ConfigLoader = class {
   /**
    * Get a specific config value by path
    */
-  get(path18) {
-    const parts = path18.split(".");
+  get(path19) {
+    const parts = path19.split(".");
     let current = this.getConfig();
     for (const part of parts) {
       if (current === null || typeof current !== "object") {
@@ -8136,11 +8673,6 @@ function convertIndexerSkill(indexerSkill) {
     createdAt: new Date(indexerSkill.scrapedAt),
     updatedAt: new Date(indexerSkill.updatedAt),
     status,
-    metrics: {
-      usageCount: 0,
-      successRate: 0,
-      feedbackScores: []
-    },
     source: {
       type: "imported",
       location: indexerSkill.sourceUrl,
@@ -8977,15 +9509,349 @@ function createIntegratedIndexer(skillBank, config2 = {}) {
   return new IndexerService(config2, skillBank);
 }
 
+// src/import/skillmd.ts
+function splitFrontmatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (match) {
+    return { frontmatter: match[1], body: match[2], hasFrontmatter: true };
+  }
+  return { frontmatter: "", body: normalized, hasFrontmatter: false };
+}
+function extractField(yaml, field) {
+  const match = yaml.match(new RegExp(`^${field}:\\s*(.+)$`, "m"));
+  if (!match) return void 0;
+  return match[1].trim().replace(/^["']|["']$/g, "");
+}
+function extractMultiline(yaml, field) {
+  const match = yaml.match(
+    new RegExp(`^${field}:\\s*\\|\\n((?:\\s{2}.+\\n?)+)`, "m")
+  );
+  if (match) {
+    return match[1].split("\n").map((line) => line.replace(/^\s{2}/, "")).join("\n").trim();
+  }
+  return extractField(yaml, field);
+}
+function extractList(yaml, field) {
+  const match = yaml.match(new RegExp(`^${field}:\\n((?:\\s+-\\s+.+\\n?)+)`, "m"));
+  if (match) {
+    return match[1].split("\n").map((line) => line.replace(/^\s+-\s+/, "").trim().replace(/^["']|["']$/g, "")).filter((line) => line.length > 0);
+  }
+  return [];
+}
+function parseSkillMd(content) {
+  const { frontmatter, body, hasFrontmatter } = splitFrontmatter(content);
+  return {
+    name: extractField(frontmatter, "name"),
+    description: extractMultiline(frontmatter, "description"),
+    version: extractField(frontmatter, "version"),
+    author: extractField(frontmatter, "author"),
+    status: extractField(frontmatter, "status"),
+    date: extractField(frontmatter, "date"),
+    tags: extractList(frontmatter, "tags"),
+    body: body.trim(),
+    hasFrontmatter
+  };
+}
+
+// src/import/skill-from-md.ts
+var VALID_STATUSES2 = ["draft", "active", "deprecated", "experimental"];
+function slugify(input) {
+  return input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "skill";
+}
+function skillFromSkillMd(content, options = {}) {
+  const warnings = [];
+  const parsed = parseSkillMd(content);
+  if (!parsed.hasFrontmatter) {
+    warnings.push("SKILL.md has no YAML frontmatter; using fallback metadata");
+  }
+  if (!parsed.body) {
+    warnings.push("SKILL.md body is empty; instructions will be empty");
+  }
+  const id = slugify(options.id || parsed.name || options.defaultName || "skill");
+  const tags = new Set(parsed.tags);
+  for (const tag of options.extraTags ?? []) {
+    if (tag) tags.add(tag);
+  }
+  const status = parsed.status && VALID_STATUSES2.includes(parsed.status) ? parsed.status : options.defaultStatus ?? "active";
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const skill = {
+    id,
+    name: parsed.name || options.defaultName || id,
+    version: parsed.version || options.defaultVersion || "1.0.0",
+    description: parsed.description || options.defaultDescription || "",
+    instructions: parsed.body,
+    author: parsed.author || options.defaultAuthor || "unknown",
+    tags: Array.from(tags),
+    createdAt: now,
+    updatedAt: now,
+    status,
+    source: options.source,
+    taxonomy: options.taxonomyPath && options.taxonomyPath.length > 0 ? { primaryPath: options.taxonomyPath } : void 0,
+    externalSource: options.externalSource
+  };
+  return { skill, warnings, parsed };
+}
+
+// src/services/skillnet.ts
+var DEFAULT_SKILLNET_API = "http://api-skillnet.openkg.cn/v1";
+function parseGitHubUrl(url) {
+  const m = url.match(
+    /github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/(?:tree|blob)\/([^/]+)\/(.*))?$/
+  );
+  if (!m) return null;
+  const [, owner, repo, ref, path19] = m;
+  return {
+    owner,
+    repo,
+    ref: ref || "main",
+    path: (path19 || "").replace(/\/$/, "")
+  };
+}
+var SkillNetClient = class {
+  constructor(config2 = {}) {
+    this.apiBaseUrl = (config2.apiBaseUrl || DEFAULT_SKILLNET_API).replace(/\/$/, "");
+    this.githubToken = config2.githubToken;
+    this.githubMirror = config2.githubMirror;
+    const resolved = config2.fetchImpl || globalThis.fetch;
+    if (!resolved) {
+      throw new Error(
+        "No fetch implementation available. Provide config.fetchImpl or run on Node 18+."
+      );
+    }
+    this.fetchImpl = resolved;
+  }
+  /**
+   * Search the SkillNet index. Free and requires no API key.
+   */
+  async search(query, options = {}) {
+    const params = new URLSearchParams({ q: query });
+    if (options.mode) params.set("mode", options.mode);
+    if (options.category) params.set("category", options.category);
+    if (options.limit != null) params.set("limit", String(options.limit));
+    if (options.page != null) params.set("page", String(options.page));
+    if (options.minStars != null) params.set("min_stars", String(options.minStars));
+    if (options.sortBy) params.set("sort_by", options.sortBy);
+    if (options.threshold != null) params.set("threshold", String(options.threshold));
+    const url = `${this.apiBaseUrl}/search?${params.toString()}`;
+    const res = await this.fetchImpl(url);
+    if (!res.ok) {
+      throw new Error(`SkillNet search failed: ${res.status} ${res.statusText}`);
+    }
+    const body = await res.json();
+    const rows = Array.isArray(body.data) ? body.data : [];
+    return rows.map((row) => ({
+      skillName: String(row.skill_name ?? ""),
+      skillDescription: row.skill_description != null ? String(row.skill_description) : void 0,
+      author: row.author != null ? String(row.author) : void 0,
+      stars: typeof row.stars === "number" ? row.stars : Number(row.stars) || 0,
+      skillUrl: String(row.skill_url ?? ""),
+      category: row.category != null ? String(row.category) : void 0,
+      evaluation: row.evaluation && typeof row.evaluation === "object" ? row.evaluation : void 0
+    }));
+  }
+  /**
+   * Convert a GitHub skill URL into the raw URL for its SKILL.md.
+   * Applies the configured mirror prefix when set.
+   */
+  toRawSkillMdUrl(skillUrl) {
+    const parsed = parseGitHubUrl(skillUrl);
+    if (!parsed) {
+      throw new Error(`Not a recognizable GitHub skill URL: ${skillUrl}`);
+    }
+    const { owner, repo, ref, path: path19 } = parsed;
+    const filePath = /SKILL\.md$/i.test(path19) ? path19 : path19 ? `${path19}/SKILL.md` : "SKILL.md";
+    const raw = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${filePath}`;
+    return this.githubMirror ? `${this.githubMirror.replace(/\/$/, "")}/${raw}` : raw;
+  }
+  /**
+   * Fetch the raw SKILL.md content for a skill URL.
+   */
+  async fetchSkillMd(skillUrl) {
+    const rawUrl = this.toRawSkillMdUrl(skillUrl);
+    const headers = {};
+    if (this.githubToken) {
+      headers.Authorization = `Bearer ${this.githubToken}`;
+    }
+    const res = await this.fetchImpl(rawUrl, { headers });
+    if (!res.ok) {
+      throw new Error(
+        `Failed to fetch SKILL.md (${res.status} ${res.statusText}): ${rawUrl}`
+      );
+    }
+    return { content: await res.text(), rawUrl };
+  }
+  /**
+   * Convert a SkillNet search result + its SKILL.md content into a skill-tree Skill.
+   */
+  convertSkillNetSkill(result, content, rawUrl) {
+    const gh = parseGitHubUrl(result.skillUrl);
+    const folderName = gh?.path ? gh.path.split("/").filter(Boolean).pop() : void 0;
+    const now = /* @__PURE__ */ new Date();
+    const { skill, warnings } = skillFromSkillMd(content, {
+      id: folderName || result.skillName,
+      defaultName: result.skillName,
+      defaultDescription: result.skillDescription,
+      defaultAuthor: result.author || "skillnet",
+      // SkillNet skills are curated/published → default active.
+      defaultStatus: "active",
+      extraTags: [
+        ...result.category ? [result.category.toLowerCase()] : [],
+        ...gh?.repo ? [gh.repo] : []
+      ],
+      taxonomyPath: result.category ? [result.category] : void 0,
+      source: {
+        type: "imported",
+        location: result.skillUrl,
+        importedAt: now
+      },
+      externalSource: {
+        url: result.skillUrl,
+        repo: gh ? `${gh.owner}/${gh.repo}` : "",
+        scrapedAt: now
+      },
+      now
+    });
+    return { skill, warnings, rawUrl };
+  }
+  /**
+   * Import a single skill by its SkillNet/GitHub URL into a SkillBank.
+   */
+  async importSkill(skillUrl, bank, meta = {}) {
+    const { content, rawUrl } = await this.fetchSkillMd(skillUrl);
+    const result = {
+      skillName: meta.skillName || "",
+      skillDescription: meta.skillDescription,
+      author: meta.author,
+      stars: meta.stars ?? 0,
+      skillUrl,
+      category: meta.category,
+      evaluation: meta.evaluation
+    };
+    const converted = this.convertSkillNetSkill(result, content, rawUrl);
+    await bank.saveSkill(converted.skill);
+    return converted;
+  }
+  /**
+   * Search SkillNet and import the matching skills into a SkillBank.
+   */
+  async importFromSearch(query, bank, options = {}) {
+    const result = {
+      imported: 0,
+      failed: 0,
+      skills: [],
+      errors: []
+    };
+    const results = await this.search(query, options);
+    for (const row of results) {
+      if (!row.skillUrl) {
+        result.failed++;
+        result.errors.push(`Skipped "${row.skillName}": no skill_url`);
+        continue;
+      }
+      try {
+        const converted = await this.importSkill(row.skillUrl, bank, row);
+        result.imported++;
+        result.skills.push(converted.skill);
+      } catch (err) {
+        result.failed++;
+        result.errors.push(
+          `Failed to import ${row.skillUrl}: ${err.message}`
+        );
+      }
+    }
+    return result;
+  }
+};
+function createSkillNetClient(config2 = {}) {
+  return new SkillNetClient(config2);
+}
+
+// src/import/local.ts
+var fs13 = __toESM(require("fs/promises"));
+var path13 = __toESM(require("path"));
+var SKILL_FILE_RE = /^skill\.md$/i;
+async function findSkillMdFiles(root, maxDepth = 6) {
+  const found = [];
+  async function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = await fs13.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err.code === "ENOENT") return;
+      throw err;
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && SKILL_FILE_RE.test(entry.name)) {
+        found.push({
+          filePath: path13.join(dir, entry.name),
+          directory: dir,
+          id: path13.basename(dir)
+        });
+      }
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+        await walk(path13.join(dir, entry.name), depth + 1);
+      }
+    }
+  }
+  await walk(root, 0);
+  return found;
+}
+async function importSkillMdFile(filePath, bank, options = {}) {
+  const content = await fs13.readFile(filePath, "utf-8");
+  const dirName = path13.basename(path13.dirname(filePath));
+  const now = /* @__PURE__ */ new Date();
+  const { skill, warnings } = skillFromSkillMd(content, {
+    source: { type: "imported", location: filePath, importedAt: now },
+    now,
+    ...options,
+    id: options.id ?? dirName
+  });
+  await bank.saveSkill(skill);
+  return { skill, warnings };
+}
+async function importLocalSkillDir(dirPath, bank, options = {}) {
+  const result = {
+    imported: 0,
+    failed: 0,
+    skills: [],
+    errors: []
+  };
+  const files = await findSkillMdFiles(dirPath);
+  const seen = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    if (seen.has(file.id)) {
+      result.errors.push(`Skipped duplicate id "${file.id}" at ${file.filePath}`);
+      continue;
+    }
+    try {
+      const { skill } = await importSkillMdFile(file.filePath, bank, {
+        ...options,
+        id: file.id
+      });
+      seen.add(skill.id);
+      result.imported++;
+      result.skills.push(skill);
+    } catch (err) {
+      result.failed++;
+      result.errors.push(`Failed to import ${file.filePath}: ${err.message}`);
+    }
+  }
+  return result;
+}
+
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 
 // src/cli/commands/list.ts
 var import_commander = require("commander");
 
 // src/cli/utils/paths.ts
-var fs13 = __toESM(require("fs"));
-var path13 = __toESM(require("path"));
+var fs14 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
 var os2 = __toESM(require("os"));
 var DEFAULT_PATHS = [
   ".claude/skills",
@@ -8999,13 +9865,13 @@ var DEFAULT_PATHS = [
 ];
 function expandHome(p) {
   if (p.startsWith("~/")) {
-    return path13.join(os2.homedir(), p.slice(2));
+    return path14.join(os2.homedir(), p.slice(2));
   }
   return p;
 }
 function dirExists(p) {
   try {
-    return fs13.statSync(p).isDirectory();
+    return fs14.statSync(p).isDirectory();
   } catch {
     return false;
   }
@@ -9013,23 +9879,23 @@ function dirExists(p) {
 function resolveSkillPath(explicitPath) {
   if (explicitPath) {
     const resolved = expandHome(explicitPath);
-    return path13.resolve(resolved);
+    return path14.resolve(resolved);
   }
   const envPath = process.env.SKILL_TREE_PATH;
   if (envPath) {
-    return path13.resolve(expandHome(envPath));
+    return path14.resolve(expandHome(envPath));
   }
   for (const defaultPath of DEFAULT_PATHS) {
-    const resolved = path13.resolve(expandHome(defaultPath));
+    const resolved = path14.resolve(expandHome(defaultPath));
     if (dirExists(resolved)) {
       return resolved;
     }
   }
-  return path13.resolve(".claude/skills");
+  return path14.resolve(".claude/skills");
 }
 function ensureDir(dir) {
   if (!dirExists(dir)) {
-    fs13.mkdirSync(dir, { recursive: true });
+    fs14.mkdirSync(dir, { recursive: true });
   }
 }
 
@@ -9104,10 +9970,6 @@ function formatSkillDetail(skill) {
   if (skill.derivedFrom && skill.derivedFrom.length > 0) {
     lines.push(`${import_chalk.default.dim("Derived:")}   ${skill.derivedFrom.join(", ")}`);
   }
-  const { usageCount, successRate } = skill.metrics;
-  if (usageCount > 0) {
-    lines.push(`${import_chalk.default.dim("Usage:")}     ${usageCount} times, ${Math.round(successRate * 100)}% success`);
-  }
   lines.push("");
   lines.push(import_chalk.default.dim("Description"));
   lines.push(import_chalk.default.dim("\u2500".repeat(50)));
@@ -9187,11 +10049,6 @@ function formatStats(stats) {
     }
     lines.push("");
   }
-  if (stats.totalUsage > 0) {
-    lines.push(import_chalk.default.dim("Usage:"));
-    lines.push(`  Total uses:      ${stats.totalUsage}`);
-    lines.push(`  Avg success:     ${Math.round(stats.avgSuccessRate * 100)}%`);
-  }
   return lines.join("\n");
 }
 function printError(message) {
@@ -9485,7 +10342,7 @@ var deleteCommand = new import_commander11.Command("delete").description("Delete
 
 // src/cli/commands/export.ts
 var import_commander12 = require("commander");
-var fs14 = __toESM(require("fs"));
+var fs15 = __toESM(require("fs"));
 var exportCommand = new import_commander12.Command("export").description("Export all skills to JSON").option("-o, --output <file>", "Output file path (defaults to stdout)").action(async (options, command) => {
   const globalOpts = command.optsWithGlobals();
   try {
@@ -9493,7 +10350,7 @@ var exportCommand = new import_commander12.Command("export").description("Export
     const skills = await skillBank.exportAll();
     const json = JSON.stringify(skills, null, 2);
     if (options.output) {
-      fs14.writeFileSync(options.output, json, "utf-8");
+      fs15.writeFileSync(options.output, json, "utf-8");
       if (!globalOpts.quiet) {
         printSuccess(`Exported ${skills.length} skill(s) to ${options.output}`);
       }
@@ -9508,13 +10365,13 @@ var exportCommand = new import_commander12.Command("export").description("Export
 
 // src/cli/commands/import.ts
 var import_commander13 = require("commander");
-var fs15 = __toESM(require("fs"));
+var fs16 = __toESM(require("fs"));
 
 // src/import/detect.ts
 function isSkillTreeSkill(obj) {
   if (typeof obj !== "object" || obj === null) return false;
   const skill = obj;
-  return typeof skill.id === "string" && typeof skill.name === "string" && typeof skill.version === "string" && typeof skill.instructions === "string" && typeof skill.metrics === "object";
+  return typeof skill.id === "string" && typeof skill.name === "string" && typeof skill.version === "string" && typeof skill.instructions === "string";
 }
 function isIndexerSkill(obj) {
   if (typeof obj !== "object" || obj === null) return false;
@@ -9567,14 +10424,38 @@ function isLikelyIndexerFormat(content) {
 }
 
 // src/cli/commands/import.ts
-var importCommand = new import_commander13.Command("import").description("Import skills from JSON file").argument("<file>", "JSON file to import").option("--from-indexer", "Import from skill-indexer export format").option("--auto-detect", "Auto-detect format (default: true)", true).action(async (file, options, command) => {
+var importCommand = new import_commander13.Command("import").description("Import skills from a JSON file, a SKILL.md file, or a directory of skills").argument("<path>", "JSON file, SKILL.md file, or directory to import").option("--from-indexer", "Import from skill-indexer export format").option("--skill-md", "Treat input as SKILL.md (auto-detected for directories and .md files)").option("--auto-detect", "Auto-detect format (default: true)", true).action(async (file, options, command) => {
   const globalOpts = command.optsWithGlobals();
   try {
-    if (!fs15.existsSync(file)) {
-      printError(`File not found: ${file}`);
+    if (!fs16.existsSync(file)) {
+      printError(`Path not found: ${file}`);
       process.exit(1);
     }
-    const content = fs15.readFileSync(file, "utf-8");
+    const stat = fs16.statSync(file);
+    const isMarkdown = options.skillMd || stat.isDirectory() || /\.md$/i.test(file);
+    if (isMarkdown) {
+      const bank = await createSkillBankFromOptions(globalOpts);
+      if (stat.isDirectory()) {
+        const result2 = await importLocalSkillDir(file, bank);
+        if (globalOpts.json) {
+          console.log(JSON.stringify(result2, null, 2));
+          return;
+        }
+        printSuccess(`Imported ${result2.imported} skill(s) from ${file}`);
+        if (result2.failed > 0) printWarning(`Failed to import ${result2.failed} skill(s)`);
+        for (const e of result2.errors) printInfo(`  - ${e}`);
+      } else {
+        const { skill, warnings } = await importSkillMdFile(file, bank);
+        if (globalOpts.json) {
+          console.log(JSON.stringify({ imported: 1, skill: skill.id, warnings }, null, 2));
+          return;
+        }
+        printSuccess(`Imported "${skill.id}"`);
+        for (const w of warnings) printWarning(w);
+      }
+      return;
+    }
+    const content = fs16.readFileSync(file, "utf-8");
     let skills;
     const isIndexerFormat = options.fromIndexer || options.autoDetect !== false && isLikelyIndexerFormat(content);
     if (isIndexerFormat) {
@@ -9605,9 +10486,6 @@ var importCommand = new import_commander13.Command("import").description("Import
       for (const skill of skills) {
         skill.createdAt = new Date(skill.createdAt);
         skill.updatedAt = new Date(skill.updatedAt);
-        if (skill.metrics.lastUsed) {
-          skill.metrics.lastUsed = new Date(skill.metrics.lastUsed);
-        }
         if (skill.source?.importedAt) {
           skill.source.importedAt = new Date(skill.source.importedAt);
         }
@@ -10103,8 +10981,8 @@ async function runSkillIndexer5(args, quiet) {
 
 // src/cli/commands/indexer/sync.ts
 var import_commander19 = require("commander");
-var fs16 = __toESM(require("fs"));
-var path14 = __toESM(require("path"));
+var fs17 = __toESM(require("fs"));
+var path15 = __toESM(require("path"));
 var os3 = __toESM(require("os"));
 var import_child_process7 = require("child_process");
 
@@ -10565,11 +11443,11 @@ async function runLegacyImport(options, globalOpts) {
     if (!globalOpts.quiet) {
       printInfo("Exporting skills from indexer...");
     }
-    exportPath = path14.join(os3.tmpdir(), `skill-tree-sync-${Date.now()}.json`);
+    exportPath = path15.join(os3.tmpdir(), `skill-tree-sync-${Date.now()}.json`);
     const args = ["export-skilltree", "-o", exportPath, "-f", "json"];
     if (options.indexedOnly) args.push("--indexed-only");
     await runSkillIndexer6(args, true);
-    if (!fs16.existsSync(exportPath)) {
+    if (!fs17.existsSync(exportPath)) {
       printError("Failed to export skills from indexer");
       process.exit(1);
     }
@@ -10577,7 +11455,7 @@ async function runLegacyImport(options, globalOpts) {
   if (!globalOpts.quiet) {
     printInfo(`Reading export from ${exportPath}...`);
   }
-  const content = fs16.readFileSync(exportPath, "utf-8");
+  const content = fs17.readFileSync(exportPath, "utf-8");
   const { skills, stats } = parseIndexerExport(content);
   if (!globalOpts.quiet) {
     printInfo(`Found ${stats.total} skills (${stats.withStructuredContent} with structured content)`);
@@ -10597,7 +11475,7 @@ async function runLegacyImport(options, globalOpts) {
   const result = await skillBank.importSkills(skills);
   if (!options.exportPath && exportPath) {
     try {
-      fs16.unlinkSync(exportPath);
+      fs17.unlinkSync(exportPath);
     } catch {
     }
   }
@@ -10634,7 +11512,7 @@ var indexerCommand = new import_commander20.Command("index").description("Skill
 
 // src/cli/commands/config.ts
 var import_commander21 = require("commander");
-var fs17 = __toESM(require("fs"));
+var fs18 = __toESM(require("fs"));
 var configCommand = new import_commander21.Command("config").description("View and manage configuration");
 configCommand.command("show").description("Show current configuration").option("--path <path>", "Path to specific config value (e.g., storage.path)").action((options) => {
   const globalOpts = configCommand.parent?.opts() || {};
@@ -10667,7 +11545,7 @@ configCommand.command("show").description("Show current configuration").option("
 configCommand.command("init").description("Create default configuration file").option("-f, --force", "Overwrite existing config file").action((options) => {
   const globalOpts = configCommand.parent?.opts() || {};
   const configPath = expandPath(globalOpts.config || getConfigPath());
-  if (fs17.existsSync(configPath) && !options.force) {
+  if (fs18.existsSync(configPath) && !options.force) {
     console.error(`Config file already exists: ${configPath}`);
     console.error("Use --force to overwrite");
     process.exit(1);
@@ -10686,7 +11564,7 @@ configCommand.command("path").description("Show configuration file path").action
 configCommand.command("edit").description("Open configuration file in editor").action(() => {
   const globalOpts = configCommand.parent?.opts() || {};
   const configPath = expandPath(globalOpts.config || getConfigPath());
-  if (!fs17.existsSync(configPath)) {
+  if (!fs18.existsSync(configPath)) {
     const loader = new ConfigLoader(configPath);
     loader.createDefaultConfigFile();
   }
@@ -10717,7 +11595,7 @@ configCommand.command("defaults").description("Show default configuration values
 configCommand.command("validate").description("Validate configuration file").action(() => {
   const globalOpts = configCommand.parent?.opts() || {};
   const configPath = expandPath(globalOpts.config || getConfigPath());
-  if (!fs17.existsSync(configPath)) {
+  if (!fs18.existsSync(configPath)) {
     console.error(`Config file not found: ${configPath}`);
     process.exit(1);
   }
@@ -10784,15 +11662,15 @@ function printConfig(obj, indent) {
 
 // src/cli/commands/sync.ts
 var import_commander22 = require("commander");
-var path15 = __toESM(require("path"));
-var fs18 = __toESM(require("fs"));
+var path16 = __toESM(require("path"));
+var fs19 = __toESM(require("fs"));
 function getSyncConfigPath(basePath) {
-  return path15.join(basePath, ".skillbank", "sync-config.json");
+  return path16.join(basePath, ".skillbank", "sync-config.json");
 }
 async function loadSyncConfig(basePath) {
   const configPath = getSyncConfigPath(basePath);
   try {
-    const content = await fs18.promises.readFile(configPath, "utf-8");
+    const content = await fs19.promises.readFile(configPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -10800,8 +11678,8 @@ async function loadSyncConfig(basePath) {
 }
 async function saveSyncConfig(basePath, config2) {
   const configPath = getSyncConfigPath(basePath);
-  await fs18.promises.mkdir(path15.dirname(configPath), { recursive: true });
-  await fs18.promises.writeFile(configPath, JSON.stringify(config2, null, 2), "utf-8");
+  await fs19.promises.mkdir(path16.dirname(configPath), { recursive: true });
+  await fs19.promises.writeFile(configPath, JSON.stringify(config2, null, 2), "utf-8");
 }
 async function createSyncAdapter(basePath, globalOpts) {
   const config2 = await loadSyncConfig(basePath);
@@ -10831,8 +11709,8 @@ function initCommand() {
         agentName: options.name,
         environment: options.env
       });
-      const gitDir = path15.join(basePath, ".git");
-      if (!fs18.existsSync(gitDir)) {
+      const gitDir = path16.join(basePath, ".git");
+      if (!fs19.existsSync(gitDir)) {
         printError(`Not a git repository: ${basePath}`);
         printInfo("Initialize a git repository first with: git init");
         process.exit(1);
@@ -11108,7 +11986,7 @@ function resolveCommand() {
 
 // src/cli/commands/read.ts
 var import_commander23 = require("commander");
-var path16 = __toESM(require("path"));
+var path17 = __toESM(require("path"));
 function serializeSkillMd(skill) {
   const lines = [];
   lines.push("---");
@@ -11154,7 +12032,7 @@ var readCommand = new import_commander23.Command("read").description("Read skill
       } else {
         console.log(`Reading: ${skill.name}`);
       }
-      const skillDir = path16.join(basePath, ".skilltree", "skills", skill.id);
+      const skillDir = path17.join(basePath, ".skilltree", "skills", skill.id);
       console.log(`Base directory: ${skillDir}`);
       console.log("");
       console.log(serializeSkillMd(skill));
@@ -11231,19 +12109,19 @@ var materializeCommand = new import_commander24.Command("materialize").descripti
 });
 
 // src/cli/commands/loadout/index.ts
-var import_commander38 = require("commander");
+var import_commander37 = require("commander");
 
 // src/cli/commands/loadout/list.ts
 var import_commander25 = require("commander");
 
 // src/serving/state-persistence.ts
-var fs19 = __toESM(require("fs"));
-var path17 = __toESM(require("path"));
+var fs20 = __toESM(require("fs"));
+var path18 = __toESM(require("path"));
 var STATE_FILENAME = ".loadout-state.json";
 function loadState(skillPath) {
-  const filePath = path17.join(skillPath, STATE_FILENAME);
+  const filePath = path18.join(skillPath, STATE_FILENAME);
   try {
-    const raw = fs19.readFileSync(filePath, "utf-8");
+    const raw = fs20.readFileSync(filePath, "utf-8");
     const data = JSON.parse(raw);
     return {
       available: new Map(data.available),
@@ -11257,7 +12135,7 @@ function loadState(skillPath) {
   }
 }
 function saveState(skillPath, state) {
-  const filePath = path17.join(skillPath, STATE_FILENAME);
+  const filePath = path18.join(skillPath, STATE_FILENAME);
   const data = {
     available: Array.from(state.available.entries()),
     expanded: Array.from(state.expanded),
@@ -11265,12 +12143,12 @@ function saveState(skillPath, state) {
     source: state.source,
     updatedAt: state.updatedAt.toISOString()
   };
-  fs19.writeFileSync(filePath, JSON.stringify(data, null, 2));
+  fs20.writeFileSync(filePath, JSON.stringify(data, null, 2));
 }
 function clearState(skillPath) {
-  const filePath = path17.join(skillPath, STATE_FILENAME);
+  const filePath = path18.join(skillPath, STATE_FILENAME);
   try {
-    fs19.unlinkSync(filePath);
+    fs20.unlinkSync(filePath);
     return true;
   } catch {
     return false;
@@ -11523,36 +12401,9 @@ var collapseSubcommand = new import_commander32.Command("collapse").description(
   }
 });
 
-// src/cli/commands/loadout/use.ts
-var import_commander33 = require("commander");
-var useSubcommand = new import_commander33.Command("use").description("Mark a skill as being used (auto-expands and records usage)").argument("<id>", "Skill ID to use").action(async (id, _options, command) => {
-  const globalOpts = command.optsWithGlobals();
-  try {
-    const { server, save } = await createLoadoutServer(globalOpts);
-    server.recordUsage(id);
-    const expanded = server.expandSkill(id);
-    if (!expanded) {
-      printError(`Skill "${id}" not found in loadout`);
-      process.exit(1);
-    }
-    save();
-    const skill = server.getState().available.get(id);
-    if (globalOpts.json) {
-      console.log(JSON.stringify(skill, null, 2));
-      return;
-    }
-    printSuccess(`Using "${id}"`);
-    console.log();
-    console.log(formatSkillDetail(skill));
-  } catch (error) {
-    printError(error.message);
-    process.exit(1);
-  }
-});
-
 // src/cli/commands/loadout/get.ts
-var import_commander34 = require("commander");
-var getSubcommand = new import_commander34.Command("get").description("Get details about a skill in the loadout").argument("<id>", "Skill ID").action(async (id, _options, command) => {
+var import_commander33 = require("commander");
+var getSubcommand = new import_commander33.Command("get").description("Get details about a skill in the loadout").argument("<id>", "Skill ID").action(async (id, _options, command) => {
   const globalOpts = command.optsWithGlobals();
   try {
     const { server } = await createLoadoutServer(globalOpts);
@@ -11574,8 +12425,8 @@ var getSubcommand = new import_commander34.Command("get").description("Get detai
 });
 
 // src/cli/commands/loadout/render.ts
-var import_commander35 = require("commander");
-var renderSubcommand = new import_commander35.Command("render").description("Render the current loadout as a system prompt (XML or Markdown)").option("--format <format>", "Output format: xml or markdown", "xml").action(async (options, command) => {
+var import_commander34 = require("commander");
+var renderSubcommand = new import_commander34.Command("render").description("Render the current loadout as a system prompt (XML or Markdown)").option("--format <format>", "Output format: xml or markdown", "xml").action(async (options, command) => {
   const globalOpts = command.optsWithGlobals();
   try {
     const { server } = await createLoadoutServer(globalOpts);
@@ -11593,8 +12444,8 @@ var renderSubcommand = new import_commander35.Command("render").description("Ren
 });
 
 // src/cli/commands/loadout/clear.ts
-var import_commander36 = require("commander");
-var clearSubcommand = new import_commander36.Command("clear").description("Clear the current loadout state").action(async (_options, command) => {
+var import_commander35 = require("commander");
+var clearSubcommand = new import_commander35.Command("clear").description("Clear the current loadout state").action(async (_options, command) => {
   const globalOpts = command.optsWithGlobals();
   try {
     const skillPath = resolveSkillPath(globalOpts.path);
@@ -11615,15 +12466,15 @@ var clearSubcommand = new import_commander36.Command("clear").description("Clear
 });
 
 // src/cli/commands/loadout/browse.ts
-var import_commander37 = require("commander");
-var browseSubcommand = new import_commander37.Command("browse").description("Browse the skill catalog by category").argument("[path]", "Category path to browse (e.g., Development/Python)").action(async (pathArg, _options, command) => {
+var import_commander36 = require("commander");
+var browseSubcommand = new import_commander36.Command("browse").description("Browse the skill catalog by category").argument("[path]", "Category path to browse (e.g., Development/Python)").action(async (pathArg, _options, command) => {
   const globalOpts = command.optsWithGlobals();
   try {
     const { server } = await createLoadoutServer(globalOpts);
-    const path18 = pathArg ? pathArg.split("/").filter(Boolean) : void 0;
-    const output = await server.agentBrowseCatalog(path18);
+    const path19 = pathArg ? pathArg.split("/").filter(Boolean) : void 0;
+    const output = await server.agentBrowseCatalog(path19);
     if (globalOpts.json) {
-      console.log(JSON.stringify({ path: path18 ?? [], output }, null, 2));
+      console.log(JSON.stringify({ path: path19 ?? [], output }, null, 2));
       return;
     }
     if (!output) {
@@ -11638,7 +12489,94 @@ var browseSubcommand = new import_commander37.Command("browse").description("Bro
 });
 
 // src/cli/commands/loadout/index.ts
-var loadoutCommand = new import_commander38.Command("loadout").description("Manage skill loadouts for agent sessions").addCommand(listSubcommand).addCommand(searchSubcommand).addCommand(addSubcommand).addCommand(removeSubcommand).addCommand(profileSubcommand).addCommand(setSubcommand).addCommand(expandSubcommand).addCommand(collapseSubcommand).addCommand(useSubcommand).addCommand(getSubcommand).addCommand(renderSubcommand).addCommand(clearSubcommand).addCommand(browseSubcommand);
+var loadoutCommand = new import_commander37.Command("loadout").description("Manage skill loadouts for agent sessions").addCommand(listSubcommand).addCommand(searchSubcommand).addCommand(addSubcommand).addCommand(removeSubcommand).addCommand(profileSubcommand).addCommand(setSubcommand).addCommand(expandSubcommand).addCommand(collapseSubcommand).addCommand(getSubcommand).addCommand(renderSubcommand).addCommand(clearSubcommand).addCommand(browseSubcommand);
+
+// src/cli/commands/skillnet.ts
+var import_commander38 = require("commander");
+function buildClient() {
+  return createSkillNetClient({
+    apiBaseUrl: process.env.SKILLNET_API_URL,
+    githubToken: process.env.GITHUB_TOKEN,
+    githubMirror: process.env.GITHUB_MIRROR
+  });
+}
+var searchSubcommand2 = new import_commander38.Command("search").description("Search the SkillNet index (free, no API key)").argument("<query>", "Search query (keywords or natural language)").option("-m, --mode <mode>", "Search mode: keyword or vector", "keyword").option("-c, --category <category>", "Category filter (Development, Research, ...)").option("-l, --limit <n>", "Results per page (max 50)", (v) => parseInt(v, 10)).option("--min-stars <n>", "Minimum star count (keyword mode)", (v) => parseInt(v, 10)).option("--sort-by <field>", "Sort by stars or recent (keyword mode)").option("--threshold <n>", "Similarity threshold 0-1 (vector mode)", (v) => parseFloat(v)).action(async (query, options, command) => {
+  const globalOpts = command.optsWithGlobals();
+  try {
+    const client = buildClient();
+    const searchOpts = {
+      mode: options.mode,
+      category: options.category,
+      limit: options.limit,
+      minStars: options.minStars,
+      sortBy: options.sortBy,
+      threshold: options.threshold
+    };
+    const results = await client.search(query, searchOpts);
+    if (globalOpts.json) {
+      console.log(JSON.stringify(results, null, 2));
+      return;
+    }
+    if (results.length === 0) {
+      printInfo("No skills found.");
+      return;
+    }
+    printInfo(`Found ${results.length} skill(s):
+`);
+    for (const r of results) {
+      console.log(`  ${r.skillName} \u2B50${r.stars}${r.category ? ` [${r.category}]` : ""}`);
+      if (r.skillDescription) console.log(`    ${r.skillDescription}`);
+      console.log(`    ${r.skillUrl}`);
+    }
+  } catch (err) {
+    printError(err.message);
+    process.exit(1);
+  }
+});
+var importSubcommand = new import_commander38.Command("import").description("Import skills from SkillNet into the local skill bank").argument("[query]", "Search query to import matching skills").option("-u, --url <url>", "Import a single skill by its GitHub/SkillNet URL").option("-m, --mode <mode>", "Search mode: keyword or vector", "keyword").option("-c, --category <category>", "Category filter").option("-l, --limit <n>", "Max skills to import", (v) => parseInt(v, 10), 5).option("--min-stars <n>", "Minimum star count", (v) => parseInt(v, 10)).option("--threshold <n>", "Similarity threshold 0-1 (vector mode)", (v) => parseFloat(v)).action(async (query, options, command) => {
+  const globalOpts = command.optsWithGlobals();
+  if (!query && !options.url) {
+    printError("Provide a search query or --url to import a single skill");
+    process.exit(1);
+  }
+  try {
+    const client = buildClient();
+    const bank = await createSkillBankFromOptions(globalOpts);
+    if (options.url) {
+      const converted = await client.importSkill(options.url, bank);
+      if (globalOpts.json) {
+        console.log(JSON.stringify({ imported: 1, skill: converted.skill.id }, null, 2));
+      } else {
+        printSuccess(`Imported "${converted.skill.id}"`);
+        for (const w of converted.warnings) printWarning(w);
+      }
+      return;
+    }
+    if (!globalOpts.quiet) {
+      printInfo(`Searching SkillNet for "${query}"...`);
+    }
+    const result = await client.importFromSearch(query, bank, {
+      mode: options.mode,
+      category: options.category,
+      limit: options.limit,
+      minStars: options.minStars,
+      threshold: options.threshold
+    });
+    if (globalOpts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    printSuccess(`Imported ${result.imported} skill(s)`);
+    if (result.failed > 0) {
+      printWarning(`Failed to import ${result.failed} skill(s)`);
+      for (const e of result.errors) printInfo(`  - ${e}`);
+    }
+  } catch (err) {
+    printError(err.message);
+    process.exit(1);
+  }
+});
+var skillnetCommand = new import_commander38.Command("skillnet").description("Search and import skills from the SkillNet ecosystem").addCommand(searchSubcommand2).addCommand(importSubcommand);
 
 // src/cli/index.ts
 var program = new import_commander39.Command();
@@ -11663,5 +12601,5 @@ program.addCommand(syncCommand2);
 program.addCommand(readCommand);
 program.addCommand(materializeCommand);
 program.addCommand(loadoutCommand);
+program.addCommand(skillnetCommand);
 program.parse();
-//# sourceMappingURL=index.js.map