@hasna/skills 0.10.74 → 0.10.75

package/bin/index.js

@@ -36888,7 +36888,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.74",
+    version: "0.10.75",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -60988,6 +60988,118 @@ var init_skillinfo = __esm(() => {
   GENERIC_ENV_PATTERN = /\b((?:OPENAI|ANTHROPIC|GEMINI|XAI|ELEVENLABS|DEEPGRAM|REPLICATE|FAL|STABILITY|EXA|FIRECRAWL|TWILIO|SENDGRID|RESEND|SLACK|DISCORD|NOTION|LINEAR|GITHUB|AWS|GOOGLE|CLOUDFLARE|VERCEL|SUPABASE|STRIPE)_[A-Z_]+)\b/g;
 });
 
+// src/lib/search.ts
+function editDistance(a, b) {
+  if (a === b)
+    return 0;
+  if (a.length === 0)
+    return b.length;
+  if (b.length === 0)
+    return a.length;
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = new Array(b.length + 1);
+  for (let i = 1;i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1;j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length];
+}
+function fuzzyMatchScore(word, target) {
+  if (target.includes(word))
+    return 1;
+  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (token.startsWith(word))
+      return 0.6;
+  }
+  if (word.length >= 3) {
+    const maxDist = word.length <= 3 ? 1 : 2;
+    for (const token of tokens) {
+      if (Math.abs(token.length - word.length) <= maxDist) {
+        const dist = editDistance(word, token);
+        if (dist <= maxDist)
+          return 0.4;
+      }
+    }
+  }
+  return 0;
+}
+function searchSkills(query, registry = loadRegistry()) {
+  const words2 = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words2.length === 0)
+    return [];
+  const scored = [];
+  for (const skill of registry) {
+    const nameLower = skill.name.toLowerCase();
+    const displayNameLower = skill.displayName.toLowerCase();
+    const descriptionLower = skill.description.toLowerCase();
+    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
+    const tagsCombined = tagsLower.join(" ");
+    let score = 0;
+    let allWordsMatch = true;
+    for (const word of words2) {
+      let wordScore = 0;
+      const nameMatch = fuzzyMatchScore(word, nameLower);
+      if (nameMatch > 0)
+        wordScore += 10 * nameMatch;
+      const displayMatch = fuzzyMatchScore(word, displayNameLower);
+      if (displayMatch > 0)
+        wordScore += 7 * displayMatch;
+      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
+      if (tagMatch > 0)
+        wordScore += 5 * tagMatch;
+      const descMatch = fuzzyMatchScore(word, descriptionLower);
+      if (descMatch > 0)
+        wordScore += 2 * descMatch;
+      if (wordScore === 0) {
+        allWordsMatch = false;
+        break;
+      }
+      score += wordScore;
+    }
+    if (allWordsMatch && score > 0) {
+      scored.push({ skill, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => s.skill);
+}
+function findCloseSkillNames(query, names, maxResults = 3) {
+  if (maxResults <= 0)
+    return [];
+  const q = query.trim().toLowerCase();
+  if (q.length === 0)
+    return [];
+  const tokens = q.split("-").filter(Boolean);
+  const ranked = [];
+  if (q.length >= 3) {
+    for (const name of names) {
+      const candidate = name.toLowerCase();
+      const rank = candidate === q ? 0 : candidate.endsWith(`-${q}`) || candidate.startsWith(`${q}-`) ? 1 : tokens.length > 1 && tokens.every((token) => candidate.split("-").includes(token)) ? 2 : undefined;
+      if (rank !== undefined)
+        ranked.push([name, rank]);
+    }
+  }
+  ranked.sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]));
+  const found = ranked.slice(0, maxResults).map(([name]) => name);
+  if (found.length === maxResults)
+    return found;
+  const taken = new Set(found);
+  const threshold = Math.max(3, Math.floor(q.length / 2));
+  const byDistance = names.filter((name) => !taken.has(name)).map((name) => ({ name, distance: editDistance(q, name.toLowerCase()) })).filter((entry) => entry.distance <= threshold).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+  return [...found, ...byDistance.slice(0, maxResults - found.length).map((entry) => entry.name)];
+}
+function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
+  return findCloseSkillNames(query, registry.map((skill) => skill.name), maxResults);
+}
+var init_search = __esm(() => {
+  init_registry();
+});
+
 // src/lib/selected-document.ts
 function readSelectedDocument(entries, file) {
   const entry = file !== undefined ? entries.find((candidate) => candidate.path === file) : DOCUMENT_PATHS.map((path) => entries.find((candidate) => candidate.path === path && candidate.bytes.length > 0)).find(Boolean);
@@ -61108,11 +61220,30 @@ function exactProfileSelection(spec, profile) {
   const at2 = spec.lastIndexOf("@");
   const slug = at2 > 0 ? spec.slice(0, at2) : spec;
   const version = at2 > 0 ? spec.slice(at2 + 1) : undefined;
-  const selection = profile.selections.find((entry) => (entry.slug === slug || entry.aliases?.includes(slug)) && (version === undefined || version === entry.version));
-  if (!selection || version === "")
-    throw new SkillSelectionError("SKILL_NOT_SELECTED", "The requested exact skill version is not selected by this profile or project lock.");
+  const named = profile.selections.filter((entry) => entry.slug === slug || entry.aliases?.includes(slug));
+  if (version === "")
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", emptyVersionRefusal(spec));
+  if (named.length === 0)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", unknownNameRefusal(slug, profile));
+  const selection = version === undefined ? named[0] : named.find((entry) => entry.version === version);
+  if (!selection)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", wrongVersionRefusal(slug, version, named));
   return selection;
 }
+function emptyVersionRefusal(spec) {
+  return `The requested name '${spec}' has an empty version. ${ACCEPTED_FORM}`;
+}
+function wrongVersionRefusal(slug, version, named) {
+  const versions = [...new Set(named.map((entry) => entry.version))].sort();
+  const canonical9 = named[0].slug;
+  return `Skill '${slug}' is selected at version '${versions.join("', '")}', but '${version}' was requested. ` + `Accepted form: '${canonical9}@${versions[0]}'.`;
+}
+function unknownNameRefusal(slug, profile) {
+  const names = profile.selections.flatMap((entry) => [entry.slug, ...entry.aliases ?? []]);
+  const close = findCloseSkillNames(slug, names);
+  const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
+  return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
+}
 async function loadSelectedSkill(spec, profileId, options = {}) {
   const context = await resolveSelectionContext(profileId, options);
   const selection = exactProfileSelection(spec, context.receipt.profile);
@@ -61157,9 +61288,11 @@ async function selectedSkillRequirements(spec, profileId, options = {}) {
   }
   return { ...getSkillRequirementsFromContent(selection.slug, texts, dependencies), selection };
 }
+var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.";
 var init_selection_resolver = __esm(() => {
   init_profile_client();
   init_skillinfo();
+  init_search();
   init_selected_document();
   init_selection_cache();
 });
@@ -63981,95 +64114,6 @@ var init_registry_types = __esm(() => {
   BASIC_SKILL_NAMES = [];
 });
 
-// src/lib/search.ts
-function editDistance(a, b) {
-  if (a === b)
-    return 0;
-  if (a.length === 0)
-    return b.length;
-  if (b.length === 0)
-    return a.length;
-  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-  const curr = new Array(b.length + 1);
-  for (let i = 1;i <= a.length; i++) {
-    curr[0] = i;
-    for (let j = 1;j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
-    }
-    prev.splice(0, prev.length, ...curr);
-  }
-  return prev[b.length];
-}
-function fuzzyMatchScore(word, target) {
-  if (target.includes(word))
-    return 1;
-  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
-  for (const token of tokens) {
-    if (token.startsWith(word))
-      return 0.6;
-  }
-  if (word.length >= 3) {
-    const maxDist = word.length <= 3 ? 1 : 2;
-    for (const token of tokens) {
-      if (Math.abs(token.length - word.length) <= maxDist) {
-        const dist = editDistance(word, token);
-        if (dist <= maxDist)
-          return 0.4;
-      }
-    }
-  }
-  return 0;
-}
-function searchSkills(query, registry = loadRegistry()) {
-  const words2 = query.toLowerCase().split(/\s+/).filter(Boolean);
-  if (words2.length === 0)
-    return [];
-  const scored = [];
-  for (const skill of registry) {
-    const nameLower = skill.name.toLowerCase();
-    const displayNameLower = skill.displayName.toLowerCase();
-    const descriptionLower = skill.description.toLowerCase();
-    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
-    const tagsCombined = tagsLower.join(" ");
-    let score = 0;
-    let allWordsMatch = true;
-    for (const word of words2) {
-      let wordScore = 0;
-      const nameMatch = fuzzyMatchScore(word, nameLower);
-      if (nameMatch > 0)
-        wordScore += 10 * nameMatch;
-      const displayMatch = fuzzyMatchScore(word, displayNameLower);
-      if (displayMatch > 0)
-        wordScore += 7 * displayMatch;
-      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
-      if (tagMatch > 0)
-        wordScore += 5 * tagMatch;
-      const descMatch = fuzzyMatchScore(word, descriptionLower);
-      if (descMatch > 0)
-        wordScore += 2 * descMatch;
-      if (wordScore === 0) {
-        allWordsMatch = false;
-        break;
-      }
-      score += wordScore;
-    }
-    if (allWordsMatch && score > 0) {
-      scored.push({ skill, score });
-    }
-  }
-  scored.sort((a, b) => b.score - a.score);
-  return scored.map((s) => s.skill);
-}
-function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
-  const q = query.toLowerCase();
-  const scored = registry.map((s) => ({ name: s.name, dist: editDistance(q, s.name.toLowerCase()) })).filter((s) => s.dist <= Math.max(3, Math.floor(q.length / 2))).sort((a, b) => a.dist - b.dist);
-  return scored.slice(0, maxResults).map((s) => s.name);
-}
-var init_search = __esm(() => {
-  init_registry();
-});
-
 // src/lib/registry.ts
 var exports_registry = {};
 __export(exports_registry, {
@@ -88771,6 +88815,24 @@ function optionPrefix(program2, args) {
   return { indices, separator: -1 };
 }
 
+// src/cli/stray-arguments.ts
+function permitStrayArguments(command) {
+  selfRefusing.add(command);
+  return command.allowExcessArguments(true);
+}
+function rejectStrayArguments(command) {
+  for (const child2 of command.commands) {
+    if (child2.registeredArguments.length === 0 && !selfRefusing.has(child2)) {
+      child2.allowExcessArguments(false);
+    }
+    rejectStrayArguments(child2);
+  }
+}
+var selfRefusing;
+var init_stray_arguments = __esm(() => {
+  selfRefusing = new WeakSet;
+});
+
 // src/lib/revision.ts
 import { createHash as createHash33 } from "crypto";
 function revisionIdOf(content) {
@@ -90820,7 +90882,13 @@ function handleReadRefusal(error61) {
 async function handleInfoError(name, options, error61) {
   if (isSkillsFleetCredentialError(error61))
     return handleReadRefusal(error61);
-  const notFound = await resolveRemoteNotFound(name, options.remote, error61.message);
+  let remote = options.remote === true;
+  if (!remote) {
+    try {
+      remote = (await requireSkillsReadAccess()).mode === "hosted";
+    } catch {}
+  }
+  const notFound = await resolveRemoteNotFound(name, remote, error61.message);
   if (options.json)
     console.log(JSON.stringify(notFound));
   else
@@ -117271,14 +117339,14 @@ function registerRuntime(parent) {
   const exportsCommand = parent.command("exports").description("Inspect or open skill run exports");
   exportsCommand.command("open").argument("<run-id>", "Run id").option("--json", "Output as JSON", false).description("Open the export directory for a run").action((runId2, options) => handleExportsOpen(runId2, options));
   exportsCommand.command("download").argument("<run-id>", "Remote run id").option("--json", "Output as JSON", false).description("Download remote run artifacts into .skills/exports").action((runId2, options) => handleExportsDownload(runId2, options));
-  parent.command("mcp").option("--register <agent>", "Register MCP server with agent").option("--json", "Output registration result as JSON", false).allowExcessArguments(true).description("Start MCP server (stdio) or register with an agent").action(async (options, command) => {
+  permitStrayArguments(parent.command("mcp").option("--register <agent>", "Register MCP server with agent").option("--json", "Output registration result as JSON", false).description("Start MCP server (stdio) or register with an agent").action(async (options, command) => {
     const stray = command.args[0];
     if (stray !== undefined) {
       console.error(source_default.red(`error: unknown argument '${stray}'. 'skills mcp' takes no positional arguments. ` + `Valid forms: 'skills mcp' (start the MCP stdio server), ` + `'skills mcp --register <agent>', 'skills mcp --register all'`));
       process.exit(1);
     }
     await handleMcp(options);
-  });
+  }));
   const setup = parent.command("setup").description("Point this CLI at a Skills API server, or register agent integrations").option("--api-url <url>", "Skills API origin to send remote work to").option("--global", "Accepted for compatibility; the API origin is always per-user", false).option("--json", "Output setup result as JSON", false).action(async (options) => handleSetup(options));
   setup.command("agents").option("--json", "Output registration result as JSON", false).description("Register the Skills MCP server with all supported agents").action(async (options) => handleMcp({ register: "all", json: options.json }));
   parent.command("self-update").description("Update @hasna/skills to the latest version").option("--json", "Output result as JSON", false).option("--version <version>", "Install this exact @hasna/skills version as a staged copyfile runtime").option("--min-release-age <days>", "Require a positive integer dependency release age in days for an exact-version update").option("--min-release-age-exclude <pattern>", "Exclude matching package identities from the release-age policy (repeatable)", (pattern, prior) => [...prior, pattern], []).option("--reviewed-lock <path>", "Install from this private absolute package-lock.json path without resolving dependency ranges").option("--reviewed-lock-sha256 <sha256>", "Exact reviewed SHA-256 of the supplied package-lock.json").option("--rollback <receipt-id>", "Restore launcher links from an exact copyfile rollout receipt").option("--adopt-aliases", "Switch verified legacy @hasna/skills aliases to the active copyfile runtime").option("--rollback-aliases <receipt-id>", "Restore aliases from an exact adoption receipt").action(async (options) => {
@@ -118373,6 +118441,7 @@ var init_runtime = __esm(() => {
   init_execution_secrets();
   init_context();
   init_registry();
+  init_stray_arguments();
   init_skillinfo();
   init_skill_contract();
   init_blog_article();
@@ -134114,6 +134183,7 @@ init_registry();
 init_discovery();
 init_fleet_credentials();
 init_read_access();
+init_stray_arguments();
 var jsx_dev_runtime8 = __toESM(require_jsx_dev_runtime(), 1);
 var isTTY2 = (process.stdout.isTTY ?? false) && (process.stdin.isTTY ?? false);
 var program2 = new Command;
@@ -134123,7 +134193,7 @@ program2.hook("preAction", () => {
   recordEnvironmentProfile(process.env.HASNA_PROFILE);
   selectCliSkillsCredentialProfile(profile);
 });
-program2.command("interactive", { isDefault: true }).alias("i").allowExcessArguments(true).description("Interactive skill browser (TUI)").action(async (_options, command) => {
+permitStrayArguments(program2.command("interactive", { isDefault: true }).alias("i").description("Interactive skill browser (TUI)").action(async (_options, command) => {
   const stray = command.args[0];
   if (stray !== undefined) {
     const verbs = program2.commands.map((c) => c.name()).filter((n2) => n2 !== "interactive").sort();
@@ -134150,7 +134220,7 @@ program2.command("interactive", { isDefault: true }).alias("i").allowExcessArgum
   render_default(/* @__PURE__ */ jsx_dev_runtime8.jsxDEV(App2, {
     initialAccess: access
   }, undefined, false, undefined, this));
-});
+}));
 var { registerInstall: registerInstall2 } = await Promise.resolve().then(() => (init_install(), exports_install));
 registerInstall2(program2);
 var { registerBrowse: registerBrowse2 } = await Promise.resolve().then(() => (init_list(), exports_list));
@@ -134212,6 +134282,7 @@ registerStorage2(program2);
 var { registerRegistryReconcile: registerRegistryReconcile2 } = await Promise.resolve().then(() => (init_registry_reconcile2(), exports_registry_reconcile));
 registerRegistryReconcile2(program2);
 registerEventsCommands(program2, { source: "skills" });
+rejectStrayArguments(program2);
 var cliArgs = process.argv.slice(2);
 var colorFlag = optionPrefix(program2, cliArgs).indices.find((index) => cliArgs[index] === "--no-color");
 if (colorFlag !== undefined) {

package/bin/mcp.js

@@ -23,7 +23,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.10.74",
+    version: "0.10.75",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -36452,6 +36452,118 @@ var init_skillinfo = __esm(() => {
   GENERIC_ENV_PATTERN = /\b((?:OPENAI|ANTHROPIC|GEMINI|XAI|ELEVENLABS|DEEPGRAM|REPLICATE|FAL|STABILITY|EXA|FIRECRAWL|TWILIO|SENDGRID|RESEND|SLACK|DISCORD|NOTION|LINEAR|GITHUB|AWS|GOOGLE|CLOUDFLARE|VERCEL|SUPABASE|STRIPE)_[A-Z_]+)\b/g;
 });
 
+// src/lib/search.ts
+function editDistance(a, b) {
+  if (a === b)
+    return 0;
+  if (a.length === 0)
+    return b.length;
+  if (b.length === 0)
+    return a.length;
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = new Array(b.length + 1);
+  for (let i = 1;i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1;j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length];
+}
+function fuzzyMatchScore(word, target) {
+  if (target.includes(word))
+    return 1;
+  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (token.startsWith(word))
+      return 0.6;
+  }
+  if (word.length >= 3) {
+    const maxDist = word.length <= 3 ? 1 : 2;
+    for (const token of tokens) {
+      if (Math.abs(token.length - word.length) <= maxDist) {
+        const dist = editDistance(word, token);
+        if (dist <= maxDist)
+          return 0.4;
+      }
+    }
+  }
+  return 0;
+}
+function searchSkills(query, registry2 = loadRegistry()) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0)
+    return [];
+  const scored = [];
+  for (const skill of registry2) {
+    const nameLower = skill.name.toLowerCase();
+    const displayNameLower = skill.displayName.toLowerCase();
+    const descriptionLower = skill.description.toLowerCase();
+    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
+    const tagsCombined = tagsLower.join(" ");
+    let score = 0;
+    let allWordsMatch = true;
+    for (const word of words) {
+      let wordScore = 0;
+      const nameMatch = fuzzyMatchScore(word, nameLower);
+      if (nameMatch > 0)
+        wordScore += 10 * nameMatch;
+      const displayMatch = fuzzyMatchScore(word, displayNameLower);
+      if (displayMatch > 0)
+        wordScore += 7 * displayMatch;
+      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
+      if (tagMatch > 0)
+        wordScore += 5 * tagMatch;
+      const descMatch = fuzzyMatchScore(word, descriptionLower);
+      if (descMatch > 0)
+        wordScore += 2 * descMatch;
+      if (wordScore === 0) {
+        allWordsMatch = false;
+        break;
+      }
+      score += wordScore;
+    }
+    if (allWordsMatch && score > 0) {
+      scored.push({ skill, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => s.skill);
+}
+function findCloseSkillNames(query, names, maxResults = 3) {
+  if (maxResults <= 0)
+    return [];
+  const q = query.trim().toLowerCase();
+  if (q.length === 0)
+    return [];
+  const tokens = q.split("-").filter(Boolean);
+  const ranked = [];
+  if (q.length >= 3) {
+    for (const name of names) {
+      const candidate = name.toLowerCase();
+      const rank = candidate === q ? 0 : candidate.endsWith(`-${q}`) || candidate.startsWith(`${q}-`) ? 1 : tokens.length > 1 && tokens.every((token) => candidate.split("-").includes(token)) ? 2 : undefined;
+      if (rank !== undefined)
+        ranked.push([name, rank]);
+    }
+  }
+  ranked.sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]));
+  const found = ranked.slice(0, maxResults).map(([name]) => name);
+  if (found.length === maxResults)
+    return found;
+  const taken = new Set(found);
+  const threshold = Math.max(3, Math.floor(q.length / 2));
+  const byDistance = names.filter((name) => !taken.has(name)).map((name) => ({ name, distance: editDistance(q, name.toLowerCase()) })).filter((entry) => entry.distance <= threshold).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+  return [...found, ...byDistance.slice(0, maxResults - found.length).map((entry) => entry.name)];
+}
+function findSimilarSkills(query, maxResults = 3, registry2 = loadRegistry()) {
+  return findCloseSkillNames(query, registry2.map((skill) => skill.name), maxResults);
+}
+var init_search = __esm(() => {
+  init_registry();
+});
+
 // src/lib/selected-document.ts
 function readSelectedDocument(entries, file2) {
   const entry = file2 !== undefined ? entries.find((candidate) => candidate.path === file2) : DOCUMENT_PATHS.map((path) => entries.find((candidate) => candidate.path === path && candidate.bytes.length > 0)).find(Boolean);
@@ -36532,11 +36644,30 @@ function exactProfileSelection(spec, profile) {
   const at = spec.lastIndexOf("@");
   const slug = at > 0 ? spec.slice(0, at) : spec;
   const version2 = at > 0 ? spec.slice(at + 1) : undefined;
-  const selection = profile.selections.find((entry) => (entry.slug === slug || entry.aliases?.includes(slug)) && (version2 === undefined || version2 === entry.version));
-  if (!selection || version2 === "")
-    throw new SkillSelectionError("SKILL_NOT_SELECTED", "The requested exact skill version is not selected by this profile or project lock.");
+  const named = profile.selections.filter((entry) => entry.slug === slug || entry.aliases?.includes(slug));
+  if (version2 === "")
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", emptyVersionRefusal(spec));
+  if (named.length === 0)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", unknownNameRefusal(slug, profile));
+  const selection = version2 === undefined ? named[0] : named.find((entry) => entry.version === version2);
+  if (!selection)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", wrongVersionRefusal(slug, version2, named));
   return selection;
 }
+function emptyVersionRefusal(spec) {
+  return `The requested name '${spec}' has an empty version. ${ACCEPTED_FORM}`;
+}
+function wrongVersionRefusal(slug, version2, named) {
+  const versions2 = [...new Set(named.map((entry) => entry.version))].sort();
+  const canonical9 = named[0].slug;
+  return `Skill '${slug}' is selected at version '${versions2.join("', '")}', but '${version2}' was requested. ` + `Accepted form: '${canonical9}@${versions2[0]}'.`;
+}
+function unknownNameRefusal(slug, profile) {
+  const names = profile.selections.flatMap((entry) => [entry.slug, ...entry.aliases ?? []]);
+  const close = findCloseSkillNames(slug, names);
+  const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
+  return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
+}
 async function loadSelectedSkill(spec, profileId, options = {}) {
   const context = await resolveSelectionContext(profileId, options);
   const selection = exactProfileSelection(spec, context.receipt.profile);
@@ -36581,9 +36712,11 @@ async function selectedSkillRequirements(spec, profileId, options = {}) {
   }
   return { ...getSkillRequirementsFromContent(selection.slug, texts, dependencies), selection };
 }
+var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.";
 var init_selection_resolver = __esm(() => {
   init_profile_client();
   init_skillinfo();
+  init_search();
   init_selected_document();
   init_selection_cache();
 });
@@ -38615,95 +38748,6 @@ var init_registry_types = __esm(() => {
   ];
 });
 
-// src/lib/search.ts
-function editDistance(a, b) {
-  if (a === b)
-    return 0;
-  if (a.length === 0)
-    return b.length;
-  if (b.length === 0)
-    return a.length;
-  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-  const curr = new Array(b.length + 1);
-  for (let i = 1;i <= a.length; i++) {
-    curr[0] = i;
-    for (let j = 1;j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
-    }
-    prev.splice(0, prev.length, ...curr);
-  }
-  return prev[b.length];
-}
-function fuzzyMatchScore(word, target) {
-  if (target.includes(word))
-    return 1;
-  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
-  for (const token of tokens) {
-    if (token.startsWith(word))
-      return 0.6;
-  }
-  if (word.length >= 3) {
-    const maxDist = word.length <= 3 ? 1 : 2;
-    for (const token of tokens) {
-      if (Math.abs(token.length - word.length) <= maxDist) {
-        const dist = editDistance(word, token);
-        if (dist <= maxDist)
-          return 0.4;
-      }
-    }
-  }
-  return 0;
-}
-function searchSkills(query, registry2 = loadRegistry()) {
-  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
-  if (words.length === 0)
-    return [];
-  const scored = [];
-  for (const skill of registry2) {
-    const nameLower = skill.name.toLowerCase();
-    const displayNameLower = skill.displayName.toLowerCase();
-    const descriptionLower = skill.description.toLowerCase();
-    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
-    const tagsCombined = tagsLower.join(" ");
-    let score = 0;
-    let allWordsMatch = true;
-    for (const word of words) {
-      let wordScore = 0;
-      const nameMatch = fuzzyMatchScore(word, nameLower);
-      if (nameMatch > 0)
-        wordScore += 10 * nameMatch;
-      const displayMatch = fuzzyMatchScore(word, displayNameLower);
-      if (displayMatch > 0)
-        wordScore += 7 * displayMatch;
-      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
-      if (tagMatch > 0)
-        wordScore += 5 * tagMatch;
-      const descMatch = fuzzyMatchScore(word, descriptionLower);
-      if (descMatch > 0)
-        wordScore += 2 * descMatch;
-      if (wordScore === 0) {
-        allWordsMatch = false;
-        break;
-      }
-      score += wordScore;
-    }
-    if (allWordsMatch && score > 0) {
-      scored.push({ skill, score });
-    }
-  }
-  scored.sort((a, b) => b.score - a.score);
-  return scored.map((s) => s.skill);
-}
-function findSimilarSkills(query, maxResults = 3, registry2 = loadRegistry()) {
-  const q = query.toLowerCase();
-  const scored = registry2.map((s) => ({ name: s.name, dist: editDistance(q, s.name.toLowerCase()) })).filter((s) => s.dist <= Math.max(3, Math.floor(q.length / 2))).sort((a, b) => a.dist - b.dist);
-  return scored.slice(0, maxResults).map((s) => s.name);
-}
-var init_search = __esm(() => {
-  init_registry();
-});
-
 // src/lib/registry.ts
 import { existsSync as existsSync13, readFileSync as readFileSync18, readdirSync as readdirSync10 } from "fs";
 import { join as join33 } from "path";

package/bin/migrate.js

@@ -25,7 +25,7 @@ import { join as join5 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.74",
+  version: "0.10.75",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -24140,7 +24140,7 @@ restoreLaunchCwd();
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.74",
+  version: "0.10.75",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -24143,7 +24143,7 @@ import { randomUUID as randomUUID6 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.10.74",
+  version: "0.10.75",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/cli/stray-arguments.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stray positionals on a verb that declares none are a phantom verb, not a
+ * no-op. Commander's `allowExcessArguments` defaults to true (12.1.0,
+ * `lib/command.js:28`), so `skills categories typo` exited 0 with the ordinary
+ * output and `skills list typo` printed the whole catalogue: a caller reading
+ * the exit code is told the word was understood (BUG e3997558).
+ *
+ * The default command refuses by hand so it can name the verbs that exist, and
+ * `skills mcp` refuses by hand so it can name its three forms. Those two keep
+ * their own, better sentences. Every other command that declares no argument of
+ * its own is closed here in one pass, so the next command added gets the
+ * refusal without its author having to remember the hole exists.
+ */
+import type { Command } from "commander";
+/**
+ * Opt a command out of the pass because it owns a more precise refusal than
+ * commander's. Chainable, and it keeps `allowExcessArguments(true)` so the
+ * command still receives the stray word it wants to report.
+ */
+export declare function permitStrayArguments(command: Command): Command;
+/**
+ * Refuse positionals on every command that declares no argument of its own.
+ *
+ * A command that declares arguments keeps commander's own arity check, and a
+ * command with subcommands never reaches the excess check for a word that names
+ * a child (commander dispatches the subcommand first). Commands without an
+ * action handler reach it only with zero operands, so the flag is inert there.
+ */
+export declare function rejectStrayArguments(command: Command): void;

package/dist/index.js

@@ -15144,7 +15144,7 @@ import { basename as basename13, dirname as dirname24, isAbsolute as isAbsolute2
 import { homedir as homedir5 } from "os";
 import { isAbsolute as isAbsolute25, join as join36, resolve as resolve24 } from "path";
 // package.json
-var version = "0.10.74";
+var version = "0.10.75";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -22727,6 +22727,115 @@ function readIfExists(path) {
   return null;
 }
 
+// src/lib/search.ts
+function editDistance(a, b) {
+  if (a === b)
+    return 0;
+  if (a.length === 0)
+    return b.length;
+  if (b.length === 0)
+    return a.length;
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = new Array(b.length + 1);
+  for (let i = 1;i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1;j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length];
+}
+function fuzzyMatchScore(word, target) {
+  if (target.includes(word))
+    return 1;
+  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (token.startsWith(word))
+      return 0.6;
+  }
+  if (word.length >= 3) {
+    const maxDist = word.length <= 3 ? 1 : 2;
+    for (const token of tokens) {
+      if (Math.abs(token.length - word.length) <= maxDist) {
+        const dist = editDistance(word, token);
+        if (dist <= maxDist)
+          return 0.4;
+      }
+    }
+  }
+  return 0;
+}
+function searchSkills(query, registry = loadRegistry()) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0)
+    return [];
+  const scored = [];
+  for (const skill of registry) {
+    const nameLower = skill.name.toLowerCase();
+    const displayNameLower = skill.displayName.toLowerCase();
+    const descriptionLower = skill.description.toLowerCase();
+    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
+    const tagsCombined = tagsLower.join(" ");
+    let score = 0;
+    let allWordsMatch = true;
+    for (const word of words) {
+      let wordScore = 0;
+      const nameMatch = fuzzyMatchScore(word, nameLower);
+      if (nameMatch > 0)
+        wordScore += 10 * nameMatch;
+      const displayMatch = fuzzyMatchScore(word, displayNameLower);
+      if (displayMatch > 0)
+        wordScore += 7 * displayMatch;
+      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
+      if (tagMatch > 0)
+        wordScore += 5 * tagMatch;
+      const descMatch = fuzzyMatchScore(word, descriptionLower);
+      if (descMatch > 0)
+        wordScore += 2 * descMatch;
+      if (wordScore === 0) {
+        allWordsMatch = false;
+        break;
+      }
+      score += wordScore;
+    }
+    if (allWordsMatch && score > 0) {
+      scored.push({ skill, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => s.skill);
+}
+function findCloseSkillNames(query, names, maxResults = 3) {
+  if (maxResults <= 0)
+    return [];
+  const q = query.trim().toLowerCase();
+  if (q.length === 0)
+    return [];
+  const tokens = q.split("-").filter(Boolean);
+  const ranked = [];
+  if (q.length >= 3) {
+    for (const name of names) {
+      const candidate = name.toLowerCase();
+      const rank = candidate === q ? 0 : candidate.endsWith(`-${q}`) || candidate.startsWith(`${q}-`) ? 1 : tokens.length > 1 && tokens.every((token) => candidate.split("-").includes(token)) ? 2 : undefined;
+      if (rank !== undefined)
+        ranked.push([name, rank]);
+    }
+  }
+  ranked.sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]));
+  const found = ranked.slice(0, maxResults).map(([name]) => name);
+  if (found.length === maxResults)
+    return found;
+  const taken = new Set(found);
+  const threshold = Math.max(3, Math.floor(q.length / 2));
+  const byDistance = names.filter((name) => !taken.has(name)).map((name) => ({ name, distance: editDistance(q, name.toLowerCase()) })).filter((entry) => entry.distance <= threshold).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+  return [...found, ...byDistance.slice(0, maxResults - found.length).map((entry) => entry.name)];
+}
+function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
+  return findCloseSkillNames(query, registry.map((skill) => skill.name), maxResults);
+}
+
 // src/lib/selected-document.ts
 var DOCUMENT_PATHS = ["SKILL.md", "README.md", "CLAUDE.md"];
 function readSelectedDocument(entries, file) {
@@ -22843,11 +22952,31 @@ function exactProfileSelection(spec, profile) {
   const at = spec.lastIndexOf("@");
   const slug = at > 0 ? spec.slice(0, at) : spec;
   const version2 = at > 0 ? spec.slice(at + 1) : undefined;
-  const selection = profile.selections.find((entry) => (entry.slug === slug || entry.aliases?.includes(slug)) && (version2 === undefined || version2 === entry.version));
-  if (!selection || version2 === "")
-    throw new SkillSelectionError("SKILL_NOT_SELECTED", "The requested exact skill version is not selected by this profile or project lock.");
+  const named = profile.selections.filter((entry) => entry.slug === slug || entry.aliases?.includes(slug));
+  if (version2 === "")
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", emptyVersionRefusal(spec));
+  if (named.length === 0)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", unknownNameRefusal(slug, profile));
+  const selection = version2 === undefined ? named[0] : named.find((entry) => entry.version === version2);
+  if (!selection)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", wrongVersionRefusal(slug, version2, named));
   return selection;
 }
+var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.";
+function emptyVersionRefusal(spec) {
+  return `The requested name '${spec}' has an empty version. ${ACCEPTED_FORM}`;
+}
+function wrongVersionRefusal(slug, version2, named) {
+  const versions = [...new Set(named.map((entry) => entry.version))].sort();
+  const canonical9 = named[0].slug;
+  return `Skill '${slug}' is selected at version '${versions.join("', '")}', but '${version2}' was requested. ` + `Accepted form: '${canonical9}@${versions[0]}'.`;
+}
+function unknownNameRefusal(slug, profile) {
+  const names = profile.selections.flatMap((entry) => [entry.slug, ...entry.aliases ?? []]);
+  const close = findCloseSkillNames(slug, names);
+  const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
+  return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
+}
 
 // src/lib/selected-manifest.ts
 function jsonEntry(entries, path) {
@@ -25354,92 +25483,6 @@ var CATEGORIES = [
   "Event Management"
 ];
 var BASIC_SKILL_NAMES = [];
-
-// src/lib/search.ts
-function editDistance(a, b) {
-  if (a === b)
-    return 0;
-  if (a.length === 0)
-    return b.length;
-  if (b.length === 0)
-    return a.length;
-  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
-  const curr = new Array(b.length + 1);
-  for (let i = 1;i <= a.length; i++) {
-    curr[0] = i;
-    for (let j = 1;j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
-    }
-    prev.splice(0, prev.length, ...curr);
-  }
-  return prev[b.length];
-}
-function fuzzyMatchScore(word, target) {
-  if (target.includes(word))
-    return 1;
-  const tokens = target.split(/[\s\-_]+/).filter(Boolean);
-  for (const token of tokens) {
-    if (token.startsWith(word))
-      return 0.6;
-  }
-  if (word.length >= 3) {
-    const maxDist = word.length <= 3 ? 1 : 2;
-    for (const token of tokens) {
-      if (Math.abs(token.length - word.length) <= maxDist) {
-        const dist = editDistance(word, token);
-        if (dist <= maxDist)
-          return 0.4;
-      }
-    }
-  }
-  return 0;
-}
-function searchSkills(query, registry = loadRegistry()) {
-  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
-  if (words.length === 0)
-    return [];
-  const scored = [];
-  for (const skill of registry) {
-    const nameLower = skill.name.toLowerCase();
-    const displayNameLower = skill.displayName.toLowerCase();
-    const descriptionLower = skill.description.toLowerCase();
-    const tagsLower = skill.tags.map((t2) => t2.toLowerCase());
-    const tagsCombined = tagsLower.join(" ");
-    let score = 0;
-    let allWordsMatch = true;
-    for (const word of words) {
-      let wordScore = 0;
-      const nameMatch = fuzzyMatchScore(word, nameLower);
-      if (nameMatch > 0)
-        wordScore += 10 * nameMatch;
-      const displayMatch = fuzzyMatchScore(word, displayNameLower);
-      if (displayMatch > 0)
-        wordScore += 7 * displayMatch;
-      const tagMatch = Math.max(...tagsLower.map((t2) => fuzzyMatchScore(word, t2)), fuzzyMatchScore(word, tagsCombined));
-      if (tagMatch > 0)
-        wordScore += 5 * tagMatch;
-      const descMatch = fuzzyMatchScore(word, descriptionLower);
-      if (descMatch > 0)
-        wordScore += 2 * descMatch;
-      if (wordScore === 0) {
-        allWordsMatch = false;
-        break;
-      }
-      score += wordScore;
-    }
-    if (allWordsMatch && score > 0) {
-      scored.push({ skill, score });
-    }
-  }
-  scored.sort((a, b) => b.score - a.score);
-  return scored.map((s) => s.skill);
-}
-function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
-  const q = query.toLowerCase();
-  const scored = registry.map((s) => ({ name: s.name, dist: editDistance(q, s.name.toLowerCase()) })).filter((s) => s.dist <= Math.max(3, Math.floor(q.length / 2))).sort((a, b) => a.dist - b.dist);
-  return scored.slice(0, maxResults).map((s) => s.name);
-}
 // src/lib/registry.ts
 function isBasicSkillName(name) {
   return BASIC_SKILL_NAMES.includes(name);

package/dist/lib/search.d.ts

@@ -11,6 +11,24 @@ export declare function editDistance(a: string, b: string): number;
  * Search skills by name, description, and tags using fuzzy matching.
  */
 export declare function searchSkills(query: string, registry?: SkillMeta[]): SkillMeta[];
+/**
+ * Bounded close canonical names for a refused name, strongest evidence first:
+ *
+ *  0. the exact name;
+ *  1. a hyphen-delimited containment — the candidate owns the query as a whole
+ *     leading or trailing segment (`fleet-refresh` → `instructions-fleet-refresh`);
+ *  2. a multi-word token subset of the candidate;
+ *  3. the edit-distance rule that was the only signal before.
+ *
+ * Containment is what edit distance cannot see, and it is the case that cost
+ * real time: the canonical name that owns a shorter name as its trailing
+ * segment is 13 edits from the short name, so a caller naming the procedure by
+ * its last words was told the procedure did not exist (Agents Audit A27). The
+ * distance pass still runs and fills any slots containment leaves, so a
+ * distance-only miss — including every query under three characters — keeps the
+ * answer it has always had.
+ */
+export declare function findCloseSkillNames(query: string, names: readonly string[], maxResults?: number): string[];
 /**
  * Find skills with names similar to the given query (for "did you mean?" suggestions).
  */

package/dist/runtime-prerequisites.js

@@ -49,7 +49,7 @@ var __require = import.meta.require;
 // src/runtime-prerequisites.ts
 import { isAbsolute as isAbsolute7 } from "path";
 // package.json
-var version = "0.10.74";
+var version = "0.10.75";
 var package_default = {
   name: "@hasna/skills",
   version,

package/dist/sdk/index.js

@@ -32371,7 +32371,7 @@ var init_event_sink = __esm(() => {
   init_dist();
 });
 // package.json
-var version = "0.10.74";
+var version = "0.10.75";
 var package_default = {
   name: "@hasna/skills",
   version,
@@ -51913,10 +51913,33 @@ function searchSkills(query, registry = loadRegistry()) {
   scored.sort((a, b) => b.score - a.score);
   return scored.map((s) => s.skill);
 }
+function findCloseSkillNames(query, names, maxResults = 3) {
+  if (maxResults <= 0)
+    return [];
+  const q = query.trim().toLowerCase();
+  if (q.length === 0)
+    return [];
+  const tokens = q.split("-").filter(Boolean);
+  const ranked = [];
+  if (q.length >= 3) {
+    for (const name of names) {
+      const candidate2 = name.toLowerCase();
+      const rank = candidate2 === q ? 0 : candidate2.endsWith(`-${q}`) || candidate2.startsWith(`${q}-`) ? 1 : tokens.length > 1 && tokens.every((token) => candidate2.split("-").includes(token)) ? 2 : undefined;
+      if (rank !== undefined)
+        ranked.push([name, rank]);
+    }
+  }
+  ranked.sort((a, b) => a[1] - b[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]));
+  const found = ranked.slice(0, maxResults).map(([name]) => name);
+  if (found.length === maxResults)
+    return found;
+  const taken = new Set(found);
+  const threshold = Math.max(3, Math.floor(q.length / 2));
+  const byDistance = names.filter((name) => !taken.has(name)).map((name) => ({ name, distance: editDistance(q, name.toLowerCase()) })).filter((entry) => entry.distance <= threshold).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+  return [...found, ...byDistance.slice(0, maxResults - found.length).map((entry) => entry.name)];
+}
 function findSimilarSkills(query, maxResults = 3, registry = loadRegistry()) {
-  const q = query.toLowerCase();
-  const scored = registry.map((s) => ({ name: s.name, dist: editDistance(q, s.name.toLowerCase()) })).filter((s) => s.dist <= Math.max(3, Math.floor(q.length / 2))).sort((a, b) => a.dist - b.dist);
-  return scored.slice(0, maxResults).map((s) => s.name);
+  return findCloseSkillNames(query, registry.map((skill) => skill.name), maxResults);
 }
 // src/lib/registry.ts
 function isBasicSkillName(name) {
@@ -52937,11 +52960,31 @@ function exactProfileSelection(spec, profile) {
   const at = spec.lastIndexOf("@");
   const slug = at > 0 ? spec.slice(0, at) : spec;
   const version2 = at > 0 ? spec.slice(at + 1) : undefined;
-  const selection2 = profile.selections.find((entry) => (entry.slug === slug || entry.aliases?.includes(slug)) && (version2 === undefined || version2 === entry.version));
-  if (!selection2 || version2 === "")
-    throw new SkillSelectionError("SKILL_NOT_SELECTED", "The requested exact skill version is not selected by this profile or project lock.");
+  const named = profile.selections.filter((entry) => entry.slug === slug || entry.aliases?.includes(slug));
+  if (version2 === "")
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", emptyVersionRefusal(spec));
+  if (named.length === 0)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", unknownNameRefusal(slug, profile));
+  const selection2 = version2 === undefined ? named[0] : named.find((entry) => entry.version === version2);
+  if (!selection2)
+    throw new SkillSelectionError("SKILL_NOT_SELECTED", wrongVersionRefusal(slug, version2, named));
   return selection2;
 }
+var ACCEPTED_FORM = "Accepted form: '<slug>' or '<slug>@<version>'.";
+function emptyVersionRefusal(spec) {
+  return `The requested name '${spec}' has an empty version. ${ACCEPTED_FORM}`;
+}
+function wrongVersionRefusal(slug, version2, named) {
+  const versions = [...new Set(named.map((entry) => entry.version))].sort();
+  const canonical9 = named[0].slug;
+  return `Skill '${slug}' is selected at version '${versions.join("', '")}', but '${version2}' was requested. ` + `Accepted form: '${canonical9}@${versions[0]}'.`;
+}
+function unknownNameRefusal(slug, profile) {
+  const names = profile.selections.flatMap((entry) => [entry.slug, ...entry.aliases ?? []]);
+  const close = findCloseSkillNames(slug, names);
+  const hint = close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : "";
+  return `Skill '${slug}' is not selected by this Skills profile or project lock.${hint} ` + `Read the accepted names with 'skills search <term>' or 'skills list --all --json'; accept one with 'skills pin <name>'. ${ACCEPTED_FORM}`;
+}
 
 // src/lib/selected-run.ts
 async function resolveSelectedRun(spec, profileId, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.10.74",
+  "version": "0.10.75",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {