skill-guide 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to skill-guide will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-05-17
+
+### Fixed
+- `--skill <name>` now resolves shorthand skill names such as `tdd` to the best matching installed skill, preferring name prefixes like `tdd-workflow`.
+- Missing skill lookups in HTML mode now print a terminal error and exit without generating an empty HTML guide.
+- Missing skill JSON output now preserves scan counts, source counts, and close-match suggestions.
+
 ## [0.2.0] - 2026-05-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-guide",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Scan 6+ skill directories across Claude Code, Codex, and cc-switch, then generate beautiful HTML slide presentations.",
   "license": "MIT",
   "type": "commonjs",

package/scan-skills.js

@@ -492,6 +492,47 @@ function cleanSkill(skill, includeFull) {
   return base;
 }
 
+function normalizeSkillName(name) {
+  return String(name || '').replace(/^[^:]+:/, '').toLowerCase();
+}
+
+function findSkill(skills, requestedName) {
+  const requested = String(requestedName || '').toLowerCase();
+  const bareRequested = normalizeSkillName(requestedName);
+
+  const exact = skills.find((skill) => {
+    const name = skill.name.toLowerCase();
+    const bareName = normalizeSkillName(skill.name);
+    return name === requested || bareName === bareRequested;
+  });
+  if (exact) return exact;
+
+  const prefixMatches = skills
+    .filter((skill) => normalizeSkillName(skill.name).startsWith(bareRequested))
+    .sort((a, b) => normalizeSkillName(a.name).length - normalizeSkillName(b.name).length
+      || a.name.localeCompare(b.name));
+  if (prefixMatches.length > 0) return prefixMatches[0];
+
+  const containsMatches = skills
+    .filter((skill) => normalizeSkillName(skill.name).includes(bareRequested))
+    .sort((a, b) => normalizeSkillName(a.name).length - normalizeSkillName(b.name).length
+      || a.name.localeCompare(b.name));
+  return containsMatches[0] || null;
+}
+
+function suggestSkills(skills, requestedName) {
+  const requested = normalizeSkillName(requestedName);
+  return skills
+    .filter((skill) => {
+      const name = normalizeSkillName(skill.name);
+      const description = String(skill.description || '').toLowerCase();
+      const triggers = (skill.triggers || []).join(' ').toLowerCase();
+      return name.includes(requested) || description.includes(requested) || triggers.includes(requested);
+    })
+    .slice(0, 8)
+    .map((skill) => cleanSkill(skill, false));
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -536,12 +577,16 @@ function main() {
       skills: skills.map(s => cleanSkill(s, false)),
     };
   } else if (mode === 'skill') {
-    // Strip plugin prefix (e.g. "everything-claude-code:tdd-workflow" → "tdd-workflow")
-    const bareName = skillName.replace(/^[^:]+:/, '');
-    const found = skills.find(s => s.name.toLowerCase() === bareName.toLowerCase()
-      || s.name.toLowerCase() === skillName.toLowerCase());
+    const found = findSkill(skills, skillName);
     if (!found) {
-      output = { error: `Skill "${skillName}" not found`, skills: [] };
+      output = {
+        error: `Skill "${skillName}" not found`,
+        scanDate: scanResult.scanDate,
+        totalCount: skills.length,
+        sources: sourceCounts,
+        skills: [],
+        suggestions: suggestSkills(skills, skillName),
+      };
     } else {
       output = {
         scanDate: scanResult.scanDate,

package/skill-guide.js

@@ -738,6 +738,23 @@ function printDoctor(data) {
   return lines.join('\n');
 }
 
+function formatScannerError(data) {
+  const lines = [
+    data.error || 'Skill not found',
+    `Scanned ${data.totalCount || 0} skills.`,
+  ];
+  if ((data.suggestions || []).length > 0) {
+    lines.push('Possible matches:');
+    for (const skill of data.suggestions) {
+      const sources = (skill.sources || []).join(', ');
+      lines.push(`  - ${skill.name}${sources ? ` (${sources})` : ''}`);
+    }
+  } else {
+    lines.push('No close matches found. Try --search <query> to search descriptions and triggers.');
+  }
+  return lines.join('\n');
+}
+
 function main() {
   const mode = parseMode();
   if (mode.mode === 'help') {
@@ -771,6 +788,11 @@ function main() {
     return;
   }
 
+  if (data.error) {
+    process.stderr.write(`${formatScannerError(data)}\n`);
+    process.exit(1);
+  }
+
   const output = path.resolve(getArgValue('--output') || defaultOutputPath(mode));
   fs.mkdirSync(path.dirname(output), { recursive: true });
   fs.writeFileSync(output, renderHtml(data, mode), 'utf8');