@event4u/agent-config 16.5.0 → 17.0.0

package/dist/cli-delegate/cmd_route_explain.js

@@ -1,12 +1,39 @@
 #!/usr/bin/env tsx
 import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+import {
+  DEFAULT_CATALOGUE_ROOTS,
+  resolveSkillCatalogueRoots
+} from "./chunk-NTM7G2V4.js";
 import {
   _asRuleList,
   match_prompt
 } from "./chunk-LF2KKJ4Q.js";
+import {
+  DEFAULT_SUGGEST_LIMIT,
+  buildTermStats,
+  compareRanked,
+  rawSkillScore,
+  roundHalfToEven,
+  skillTerms,
+  tokenize,
+  triggerTextFromFlatLines,
+  widensTermSource
+} from "./chunk-AX3U3UWJ.js";
 import {
   load_agent_settings
-} from "./chunk-H76PHZBI.js";
+} from "./chunk-XLY5G3CM.js";
+import {
+  fileDigest,
+  makeSkillOriginResolver,
+  qualifiedSkillName,
+  readScanCache,
+  scanCachePath,
+  scanVerdict,
+  splitQualifiedName
+} from "./chunk-FIEEOH5C.js";
+import "./chunk-4E2W63DA.js";
+import "./chunk-MWRD5YOH.js";
+import "./chunk-OY53J6II.js";
 import "./chunk-T6BP34WI.js";
 import {
   resolvePackageRoot
@@ -14,9 +41,9 @@ import {
 import "./chunk-J55WI3RR.js";
 
 // src/scripts/_cli/cmd_route_explain.ts
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL as pathToFileURL2 } from "node:url";
 
 // src/scripts/_lib/token_count.ts
 import { createRequire } from "node:module";
@@ -94,10 +121,509 @@ function method_note() {
   return method_note_proxy();
 }
 
+// src/scripts/skill_tools/score_skill_relevance.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+var _HERE = fileURLToPath(import.meta.url);
+var ROOT = path.resolve(path.dirname(_HERE), "..", "..", "..");
+var DEFAULT_SKILLS_ROOTS = resolveSkillCatalogueRoots(ROOT);
+var DEFAULT_SKILLS_DIR = DEFAULT_SKILLS_ROOTS[0] ?? null;
+function pyLen(s) {
+  let n = 0;
+  for (const _ of s) {
+    n++;
+  }
+  return n;
+}
+function _tokenize(text) {
+  return tokenize(text);
+}
+function _parse_frontmatter_text(text) {
+  if (!text.startsWith("---")) {
+    return {};
+  }
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) {
+    return {};
+  }
+  const block = text.slice(3, end);
+  const out = {};
+  let currentListKey = null;
+  for (const raw of _splitlines(block)) {
+    const line = _rstrip(raw);
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    if (currentListKey !== null && line.startsWith("  - ")) {
+      const existing = out[currentListKey];
+      const list = Array.isArray(existing) ? existing : [];
+      if (!Array.isArray(existing)) {
+        out[currentListKey] = list;
+      }
+      list.push(line.slice(4).trim());
+      continue;
+    }
+    currentListKey = null;
+    const m = /^([a-zA-Z_][\w-]*)[ \t\r\f\v]*:[ \t\r\f\v]*(.*)$/u.exec(line);
+    if (!m) {
+      continue;
+    }
+    const key = m[1];
+    let val = m[2].trim();
+    if (val === "") {
+      currentListKey = key;
+      continue;
+    }
+    if (val.startsWith('"') && val.endsWith('"')) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+function _splitlines(s) {
+  if (s === "") {
+    return [];
+  }
+  return s.split(/\r\n|\r|\n/u);
+}
+function _rstrip(s) {
+  return s.replace(/\s+$/u, "");
+}
+function _body_of(text) {
+  if (!text.startsWith("---")) return text;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return text;
+  return text.slice(end + 4);
+}
+function _body_signals(body) {
+  const headings = [];
+  const when = [];
+  let whenLevel = 0;
+  let fenceMark = null;
+  let fenceLen = 0;
+  for (const raw of body.split("\n")) {
+    const line = raw.trimEnd();
+    const f = /^\s*(`{3,}|~{3,})(.*)$/.exec(line);
+    if (f) {
+      const run = f[1];
+      const mark = run[0];
+      if (fenceMark === null) {
+        fenceMark = mark;
+        fenceLen = run.length;
+        continue;
+      }
+      if (mark === fenceMark && run.length >= fenceLen && f[2].trim() === "") {
+        fenceMark = null;
+        fenceLen = 0;
+      }
+      continue;
+    }
+    if (fenceMark !== null) {
+      if (whenLevel > 0) when.push(raw);
+      continue;
+    }
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h) {
+      const level = h[1].length;
+      const title = h[2].trim();
+      if (level >= 2 && level <= 3) headings.push(title);
+      if (whenLevel > 0 && level <= whenLevel) {
+        whenLevel = 0;
+      } else if (whenLevel > 0) {
+        when.push(title);
+      }
+      if (whenLevel === 0 && /^when to use\b/i.test(title)) whenLevel = level;
+      continue;
+    }
+    if (whenLevel > 0) when.push(raw);
+  }
+  return { whenToUse: when.join(" ").trim(), headings };
+}
+function defaultNeighbourContext(workspaceRoot = ROOT) {
+  return {
+    origin: makeSkillOriginResolver(workspaceRoot, { packageRoot: ROOT }),
+    scans: readScanCache(scanCachePath(workspaceRoot))
+  };
+}
+function _load_skills_across(roots, opts = {}, ctx) {
+  const context = ctx ?? defaultNeighbourContext();
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const root of roots) {
+    for (const s of _load_skills(root, opts, context)) {
+      if (seen.has(s.qualified)) continue;
+      seen.add(s.qualified);
+      out.push(s);
+    }
+  }
+  return out;
+}
+function _load_skills(skillsDir, opts = {}, ctx = defaultNeighbourContext()) {
+  const wantsBody = Boolean(opts.includeWhenToUse || opts.includeHeadings);
+  const skills = [];
+  for (const skillMd of _globSkillMd(skillsDir)) {
+    const text = fs.readFileSync(skillMd, "utf-8");
+    const fm = _parse_frontmatter_text(text);
+    const rawName = fm["name"];
+    const name = _truthyStr(rawName) ? String(rawName) : path.basename(path.dirname(skillMd));
+    const rawDesc = fm["description"];
+    const desc = _truthyStr(rawDesc) ? String(rawDesc) : "";
+    let personas = fm["personas"] ?? [];
+    if (typeof personas === "string") {
+      personas = [personas];
+    }
+    const personaList = [...personas];
+    const rawTriggers = fm["triggers"];
+    const triggerText = Array.isArray(rawTriggers) ? triggerTextFromFlatLines(rawTriggers) : [];
+    const { whenToUse, headings } = wantsBody ? _body_signals(_body_of(text)) : { whenToUse: "", headings: [] };
+    const origin = ctx.origin(skillMd);
+    const qualified = qualifiedSkillName(name, origin);
+    const verdict = origin === "package" ? { ok: true } : scanVerdict(ctx.scans, qualified, fileDigest(skillMd));
+    if (!verdict.ok) {
+      skills.push({
+        name,
+        origin,
+        qualified,
+        unscanned: verdict.kind,
+        description: "",
+        personas: [],
+        terms: _tokenize(name),
+        triggerText: [],
+        whenToUseText: "",
+        headingText: []
+      });
+      continue;
+    }
+    skills.push({
+      name,
+      origin,
+      qualified,
+      unscanned: null,
+      description: desc,
+      personas: personaList,
+      terms: _tokenize(name + " " + desc),
+      triggerText,
+      whenToUseText: whenToUse,
+      headingText: headings
+    });
+  }
+  return skills;
+}
+function _truthyStr(v) {
+  if (typeof v === "string") {
+    return v !== "";
+  }
+  return false;
+}
+function _globSkillMd(root) {
+  let names;
+  try {
+    names = fs.readdirSync(root);
+  } catch {
+    return [];
+  }
+  const dirs = [];
+  for (const name of names) {
+    const dir = path.join(root, name);
+    const skillMd = path.join(dir, "SKILL.md");
+    try {
+      if (fs.statSync(dir).isDirectory() && fs.statSync(skillMd).isFile()) {
+        dirs.push(name);
+      }
+    } catch {
+    }
+  }
+  dirs.sort();
+  return dirs.map((name) => path.join(root, name, "SKILL.md"));
+}
+function _rankable(skill) {
+  return {
+    name: skill.name,
+    description: skill.description,
+    personas: skill.personas,
+    triggerText: skill.triggerText,
+    whenToUseText: skill.whenToUseText,
+    headingText: skill.headingText
+  };
+}
+function _terms(skill, opts) {
+  return widensTermSource(opts) ? skillTerms(_rankable(skill), opts) : skill.terms;
+}
+function _rawScore(taskTerms, skill, terms, opts = {}, stats) {
+  return rawSkillScore(taskTerms, _rankable(skill), terms, opts, stats);
+}
+function rank(task, skillsDir, opts = {}, ctx) {
+  return rankDetailed(task, skillsDir, opts, ctx).rows;
+}
+function rankDetailed(task, skillsDir, opts = {}, ctx) {
+  const taskTerms = _tokenize(task);
+  const skills = _load_skills_across(
+    typeof skillsDir === "string" ? [skillsDir] : skillsDir,
+    opts,
+    ctx
+  );
+  const termSets = skills.map((s) => _terms(s, opts));
+  const stats = opts.idfWeighting ? buildTermStats(skills.map(_rankable), termSets) : void 0;
+  const rows = [];
+  const raw = /* @__PURE__ */ new Map();
+  const descriptions = /* @__PURE__ */ new Map();
+  for (let i = 0; i < skills.length; i += 1) {
+    const s = skills[i];
+    const unrounded = _rawScore(taskTerms, s, termSets[i], opts, stats);
+    const score = roundHalfToEven(unrounded);
+    if (score > 0) {
+      rows.push([s.qualified, score, [...s.personas]]);
+      raw.set(s.qualified, unrounded);
+      descriptions.set(s.qualified, s.description);
+    }
+  }
+  rows.sort((a, b) => compareRanked(a[0], a[1], b[0], b[1], opts, raw));
+  return { rows, raw, descriptions };
+}
+function _ljust(s, w) {
+  const len = pyLen(s);
+  return len >= w ? s : s + " ".repeat(w - len);
+}
+function _rjust3(n) {
+  const s = String(n);
+  return s.length >= 3 ? s : " ".repeat(3 - s.length) + s;
+}
+function _print_human(rowsIn, top) {
+  let rows = rowsIn;
+  if (top) {
+    rows = rows.slice(0, top);
+  }
+  if (rows.length === 0) {
+    return ["(no relevant skills found)"];
+  }
+  const width = Math.max(...rows.map((r) => pyLen(r[0])));
+  const lines = [];
+  for (const [name, score, personas] of rows) {
+    const personaStr = personas.length > 0 ? personas.join(", ") : "\u2014";
+    lines.push(`  ${_rjust3(score)}  ${_ljust(name, width)}  ${personaStr}`);
+  }
+  return lines;
+}
+function _pyJsonStr(s) {
+  let out = '"';
+  for (const ch of s) {
+    const code = ch.codePointAt(0);
+    if (ch === '"') {
+      out += '\\"';
+    } else if (ch === "\\") {
+      out += "\\\\";
+    } else if (ch === "\n") {
+      out += "\\n";
+    } else if (ch === "\r") {
+      out += "\\r";
+    } else if (ch === "	") {
+      out += "\\t";
+    } else if (ch === "\b") {
+      out += "\\b";
+    } else if (ch === "\f") {
+      out += "\\f";
+    } else if (code < 32) {
+      out += `\\u${code.toString(16).padStart(4, "0")}`;
+    } else if (code < 127) {
+      out += ch;
+    } else if (code <= 65535) {
+      out += `\\u${code.toString(16).padStart(4, "0")}`;
+    } else {
+      const c = code - 65536;
+      const hi = 55296 + (c >> 10);
+      const lo = 56320 + (c & 1023);
+      out += `\\u${hi.toString(16).padStart(4, "0")}\\u${lo.toString(16).padStart(4, "0")}`;
+    }
+  }
+  return out + '"';
+}
+function pyJsonDumpsIndent2(obj, level = 0) {
+  if (obj === null) {
+    return "null";
+  }
+  if (typeof obj === "number") {
+    return String(obj);
+  }
+  if (typeof obj === "string") {
+    return _pyJsonStr(obj);
+  }
+  if (obj === true) {
+    return "true";
+  }
+  if (obj === false) {
+    return "false";
+  }
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) {
+      return "[]";
+    }
+    const pad2 = " ".repeat(2 * (level + 1));
+    const closePad2 = " ".repeat(2 * level);
+    return `[
+${obj.map((v) => pad2 + pyJsonDumpsIndent2(v, level + 1)).join(",\n")}
+${closePad2}]`;
+  }
+  const keys = Object.keys(obj);
+  if (keys.length === 0) {
+    return "{}";
+  }
+  const pad = " ".repeat(2 * (level + 1));
+  const closePad = " ".repeat(2 * level);
+  const parts = keys.map(
+    (k) => `${pad}${_pyJsonStr(k)}: ${pyJsonDumpsIndent2(obj[k], level + 1)}`
+  );
+  return `{
+${parts.join(",\n")}
+${closePad}}`;
+}
+var PROG = "score_skill_relevance.py";
+function _argError(message) {
+  process.stderr.write(`${PROG}: error: ${message}
+`);
+  process.exit(2);
+}
+function _parseInt(raw) {
+  if (!/^[+-]?\d+$/u.test(raw.trim())) {
+    _argError(`argument --top: invalid int value: '${raw}'`);
+  }
+  return parseInt(raw, 10);
+}
+function parse_args(argv) {
+  const args = {
+    task: "",
+    skills_dir: DEFAULT_SKILLS_DIR,
+    skills_dir_explicit: false,
+    top: 0,
+    json: false,
+    sample: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") {
+      args.json = true;
+    } else if (a === "--sample") {
+      args.sample = true;
+    } else if (a === "--task") {
+      const v = argv[++i];
+      if (v === void 0) {
+        _argError("argument --task: expected one argument");
+      }
+      args.task = v;
+    } else if (a.startsWith("--task=")) {
+      args.task = a.slice("--task=".length);
+    } else if (a === "--skills-dir") {
+      const v = argv[++i];
+      if (v === void 0) {
+        _argError("argument --skills-dir: expected one argument");
+      }
+      args.skills_dir = v;
+      args.skills_dir_explicit = true;
+    } else if (a.startsWith("--skills-dir=")) {
+      args.skills_dir = a.slice("--skills-dir=".length);
+      args.skills_dir_explicit = true;
+    } else if (a === "--top") {
+      const v = argv[++i];
+      if (v === void 0) {
+        _argError("argument --top: expected one argument");
+      }
+      args.top = _parseInt(v);
+    } else if (a.startsWith("--top=")) {
+      args.top = _parseInt(a.slice("--top=".length));
+    } else {
+      _argError(`unrecognized arguments: ${a}`);
+    }
+  }
+  return args;
+}
+var _SAMPLE = {
+  task: "build a livewire component for the user dashboard with reactive state"
+};
+function catalogueDeficit(dir) {
+  if (dir === null) {
+    return `no catalogue root resolved \u2014 tried ${DEFAULT_CATALOGUE_ROOTS.join(", ")} under ${ROOT}`;
+  }
+  try {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+      return `${dir} is not a directory`;
+    }
+    if (fs.readdirSync(dir).length === 0) {
+      return `${dir} exists and is EMPTY \u2014 an empty catalogue, not an empty result`;
+    }
+  } catch (e) {
+    return `${dir} could not be read: ${e instanceof Error ? e.message : String(e)}`;
+  }
+  return null;
+}
+function main(argv = null) {
+  const args = parse_args(argv ?? process.argv.slice(2));
+  const task = args.sample ? _SAMPLE.task : args.task;
+  if (!task) {
+    _argError("--task is required (or pass --sample)");
+  }
+  const roots = args.skills_dir_explicit ? args.skills_dir === null ? [] : [args.skills_dir] : DEFAULT_SKILLS_ROOTS;
+  const unreadable = args.skills_dir_explicit ? catalogueDeficit(args.skills_dir) : roots.length === 0 ? catalogueDeficit(null) : null;
+  if (unreadable !== null) {
+    if (args.json) {
+      process.stdout.write(
+        pyJsonDumpsIndent2({
+          task,
+          status: "no_catalogue",
+          reason: unreadable,
+          ...args.skills_dir === null ? { tried: [...DEFAULT_CATALOGUE_ROOTS] } : { skills_dir: args.skills_dir }
+        })
+      );
+      process.stdout.write("\n");
+    } else {
+      process.stderr.write(
+        `(no skills catalogue read \u2014 ${unreadable})
+This is NOT "no skill matches": nothing was read, so no conclusion about skill coverage follows from it.
+`
+      );
+    }
+    return 3;
+  }
+  const rows = rank(task, roots);
+  if (args.json) {
+    const sliced = args.top ? rows.slice(0, args.top) : rows;
+    const payload = sliced.map(([n, s, p]) => ({ name: n, score: s, personas: p }));
+    process.stdout.write(pyJsonDumpsIndent2({ task, ranked: payload }));
+    process.stdout.write("\n");
+  } else {
+    const lines = _print_human(rows, args.top || null);
+    process.stdout.write(lines.join("\n") + "\n");
+  }
+  return 0;
+}
+function _isCliEntry() {
+  if (true) {
+    return false;
+  }
+  if (process.argv[1] === void 0) {
+    return false;
+  }
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) {
+    return true;
+  }
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+var _isMain = _isCliEntry();
+if (_isMain) {
+  process.exitCode = main();
+}
+
 // src/scripts/_cli/cmd_route_explain.ts
 var REPO_ROOT = resolvePackageRoot(import.meta.url);
-var ROUTER_JSON = path.join(REPO_ROOT, "dist", "router.json");
-var RULES_DIST_DIR = path.join(REPO_ROOT, "dist", "agent-src", "rules");
+var ROUTER_JSON = path2.join(REPO_ROOT, "dist", "router.json");
+var RULES_DIST_DIR = path2.join(REPO_ROOT, "dist", "agent-src", "rules");
 var MEASUREMENT_HEADER = "Measurement level: trigger matching only \u2014 what the host actually invokes is NOT measured here (ADR-126).";
 function _trigger_label(trigger) {
   for (const kind of ["keyword", "phrase", "command", "path_prefix", "file_pattern"]) {
@@ -128,9 +654,9 @@ function _disposition(tier, projection_mode) {
   return projection_mode === "eager-all" ? `injected at projection time (${tier}, lean_projection.mode: eager-all)` : `router-resolved pointer at projection time (${tier}, lean_projection.mode: ${projection_mode})`;
 }
 function _rule_body_size(rule_id) {
-  const p = path.join(RULES_DIST_DIR, `${rule_id}.md`);
+  const p = path2.join(RULES_DIST_DIR, `${rule_id}.md`);
   try {
-    const text = fs.readFileSync(p, "utf-8");
+    const text = fs2.readFileSync(p, "utf-8");
     const m = measure(text);
     return { chars: m.chars, tokens: m.tokens_gpt };
   } catch {
@@ -228,16 +754,100 @@ function render_text(report) {
   }
   return out.join("\n") + "\n";
 }
-function main(argv) {
+var SKILLS_MEASUREMENT_HEADER = "Measurement level: lexical ranking only \u2014 a high score is a pointer, not a verdict.";
+function build_skills_report(task, opts) {
+  const roots = resolveSkillCatalogueRoots(opts.workspaceRoot, opts.home, {
+    packageFallback: opts.packageRoot
+  });
+  const packageRootAbs = path2.join(opts.packageRoot, "dist", "agent-src", "skills");
+  const { rows, descriptions } = roots.length > 0 ? rankDetailed(task, roots) : { rows: [], descriptions: /* @__PURE__ */ new Map() };
+  const fallbackOnly = roots.length === 1 && roots[0] === packageRootAbs;
+  const toRow = (d) => ([name, score, personas]) => ({
+    skill: name,
+    score,
+    personas,
+    description: d.get(name) ?? ""
+  });
+  let notInstalled = [];
+  if (roots.length > 0 && !fallbackOnly && _hasSkills(packageRootAbs)) {
+    const installed = new Set(roots.flatMap(_skillNames));
+    const pkg = rankDetailed(task, [packageRootAbs]);
+    notInstalled = pkg.rows.filter(([name]) => !installed.has(splitQualifiedName(name).name)).slice(0, opts.limit).map(toRow(pkg.descriptions));
+  }
+  return {
+    measurement_level: SKILLS_MEASUREMENT_HEADER,
+    task,
+    skills_roots: roots,
+    package_fallback_used: fallbackOnly,
+    skills_indexed: rows.length,
+    limit: opts.limit,
+    suggestions: rows.slice(0, opts.limit).map(toRow(descriptions)),
+    not_installed: notInstalled
+  };
+}
+function _skillNames(root) {
+  try {
+    return fs2.readdirSync(root).filter((n) => fs2.existsSync(path2.join(root, n, "SKILL.md")));
+  } catch {
+    return [];
+  }
+}
+function _hasSkills(root) {
+  return _skillNames(root).length > 0;
+}
+function _pushRow(out, r, label) {
+  out.push(`  \xB7 ${r.skill}  [${r.score}]${label}`);
+  if (r.description) out.push(`      ${r.description}`);
+  if (r.personas.length > 0) out.push(`      personas: ${r.personas.join(", ")}`);
+}
+function render_skills_text(report) {
+  const out = [report.measurement_level, ""];
+  out.push(`task: ${JSON.stringify(report.task)}`);
+  if (report.skills_roots.length === 0) {
+    out.push("catalogue: NONE readable \u2014 no workspace root, no host root, no package fallback.");
+    out.push("");
+    out.push('  \xB7 (no catalogue to rank \u2014 this is "unknown", never "no skill covers this")');
+    return out.join("\n") + "\n";
+  }
+  out.push(
+    `catalogue: ${report.skills_roots.join(" \xB7 ")}` + (report.package_fallback_used ? "  [the installed package's own projection \u2014 no workspace or host root resolved]" : "")
+  );
+  out.push("");
+  out.push(`ranked skills (${report.suggestions.length} of ${report.skills_indexed} scoring above zero, limit ${report.limit}):`);
+  const label = report.package_fallback_used ? "  not-installed" : "";
+  for (const r of report.suggestions) _pushRow(out, r, label);
+  if (report.suggestions.length === 0) {
+    out.push("  \xB7 (nothing scored above zero \u2014 say that, and proceed without a skill)");
+  }
+  if (report.not_installed.length > 0) {
+    out.push("");
+    out.push(
+      `not installed on this host \u2014 reachable from the installed package's own projection (${report.not_installed.length}):`
+    );
+    for (const r of report.not_installed) _pushRow(out, r, "  not-installed");
+  }
+  return out.join("\n") + "\n";
+}
+function main2(argv) {
   const args = [...argv];
   const as_json = args.includes("--json");
   let files = [];
   let profile = "full";
+  let skillsTask = null;
+  let limit = DEFAULT_SUGGEST_LIMIT;
   const positional = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--json") continue;
-    if (a === "--files") {
+    if (a === "--skills") {
+      skillsTask = String(args[++i] ?? "");
+    } else if (a.startsWith("--skills=")) {
+      skillsTask = a.slice("--skills=".length);
+    } else if (a === "--limit") {
+      limit = Number.parseInt(String(args[++i] ?? ""), 10);
+    } else if (a.startsWith("--limit=")) {
+      limit = Number.parseInt(a.slice("--limit=".length), 10);
+    } else if (a === "--files") {
       files = String(args[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     } else if (a.startsWith("--files=")) {
       files = a.slice("--files=".length).split(",").map((s) => s.trim()).filter(Boolean);
@@ -247,13 +857,33 @@ function main(argv) {
       profile = a.slice("--profile=".length);
     } else if (a === "-h" || a === "--help") {
       process.stdout.write(
-        'usage: agent-config route:explain "<prompt>" [--files a,b] [--profile full|balanced] [--json]\n'
+        'usage: agent-config route:explain "<prompt>" [--files a,b] [--profile full|balanced] [--json]\n       agent-config route:explain --skills "<task>" [--limit N] [--json]\n'
       );
       return 0;
     } else {
       positional.push(a);
     }
   }
+  if (skillsTask !== null) {
+    const task = (skillsTask.trim() === "" ? positional.join(" ") : skillsTask).trim();
+    if (!task) {
+      process.stderr.write("route:explain: --skills needs a task description\n");
+      return 2;
+    }
+    if (!Number.isFinite(limit) || limit < 1) {
+      process.stderr.write("route:explain: --limit expects a positive integer\n");
+      return 2;
+    }
+    const report2 = build_skills_report(task, {
+      workspaceRoot: process.cwd(),
+      packageRoot: REPO_ROOT,
+      limit
+    });
+    process.stdout.write(
+      as_json ? JSON.stringify(report2, null, 2) + "\n" : render_skills_text(report2)
+    );
+    return report2.suggestions.length === 0 && report2.not_installed.length === 0 ? 1 : 0;
+  }
   const prompt = positional.join(" ").trim();
   if (!prompt) {
     process.stderr.write("route:explain: a prompt is required\n");
@@ -261,7 +891,7 @@ function main(argv) {
   }
   let router;
   try {
-    router = JSON.parse(fs.readFileSync(ROUTER_JSON, "utf-8"));
+    router = JSON.parse(fs2.readFileSync(ROUTER_JSON, "utf-8"));
   } catch (e) {
     process.stderr.write(`route:explain: cannot read ${ROUTER_JSON}: ${String(e)}
 `);
@@ -275,14 +905,17 @@ function main(argv) {
   }
   return report.matches.length === 0 ? 1 : 0;
 }
-var _HERE = fileURLToPath(import.meta.url);
-if (process.argv[1] && (import.meta.url === pathToFileURL(process.argv[1]).href || path.resolve(process.argv[1]) === _HERE)) {
-  process.exitCode = main(process.argv.slice(2));
+var _HERE2 = fileURLToPath2(import.meta.url);
+if (process.argv[1] && (import.meta.url === pathToFileURL2(process.argv[1]).href || path2.resolve(process.argv[1]) === _HERE2)) {
+  process.exitCode = main2(process.argv.slice(2));
 }
 export {
   MEASUREMENT_HEADER,
+  SKILLS_MEASUREMENT_HEADER,
   _projection_mode,
   build_report,
-  main,
+  build_skills_report,
+  main2 as main,
+  render_skills_text,
   render_text
 };