skill-guide 0.2.1 → 0.3.1

package/scan-skills.js

@@ -122,7 +122,7 @@ function parseFrontmatter(content) {
         continue;
       }
       // End of multiline block
-      if (multilineType === '|' || multilineType === '>') {
+      if (/^[>|]/.test(multilineType)) {
         if (multilineValue && !Array.isArray(result[currentKey])) {
           result[currentKey] = multilineValue.trim();
         }
@@ -137,8 +137,9 @@ function parseFrontmatter(content) {
       currentKey = kvMatch[1];
       let val = kvMatch[2].trim();
 
-      // Multi-line indicators
-      if (val === '|' || val === '>') {
+      // Multi-line indicators — skip if value is quoted
+      const isQuoted = (val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"));
+      if (!isQuoted && /^[>|](-|\+)?$/.test(val)) {
         inMultiline = true;
         multilineType = val;
         multilineValue = '';
@@ -202,7 +203,16 @@ const CATEGORY_MAP = [
   { category: 'development',   keywords: /\b(develop|build|debug|investigate|plan|brainstorm|feature|implement)\b/i },
 ];
 
-function categorize(name, description, triggers) {
+function categorize(name, description, triggers, tags) {
+  // Priority 1: tags match
+  if (tags && tags.length > 0) {
+    const tagText = tags.join(' ');
+    for (const { category, keywords } of CATEGORY_MAP) {
+      if (keywords.test(tagText)) return category;
+    }
+  }
+
+  // Priority 2: description match
   const text = [name, description, ...(triggers || [])].join(' ');
   for (const { category, keywords } of CATEGORY_MAP) {
     if (keywords.test(text)) return category;
@@ -220,6 +230,26 @@ function smartTruncate(text, maxLen) {
   return truncated + '...';
 }
 
+// ---------------------------------------------------------------------------
+// Layer 1.5: Extract summary (first body paragraph before headings)
+// ---------------------------------------------------------------------------
+function extractSummary(bodyContent) {
+  const paragraphs = bodyContent.split(/\n\s*\n/);
+  for (const para of paragraphs) {
+    const trimmed = para.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith('##')) break;
+    if (trimmed.startsWith('```')) continue;
+    if (trimmed.match(/^!\[/)) continue;
+    if (trimmed.startsWith('|')) continue;
+    const text = trimmed.replace(/\s+/g, ' ').trim();
+    if (text.length >= 20) {
+      return smartTruncate(text, 200);
+    }
+  }
+  return '';
+}
+
 // ---------------------------------------------------------------------------
 // Layer 2: Extract sections (## headings with first paragraph)
 // ---------------------------------------------------------------------------
@@ -392,12 +422,16 @@ function loadSkill(dir, mdFile) {
   let allowedTools = fm['allowed-tools'] || fm.allowedTools || [];
   if (typeof allowedTools === 'string') allowedTools = [allowedTools];
 
+  let tags = fm.tags || [];
+  if (typeof tags === 'string') tags = [tags];
+
   return {
     name,
     description,
-    category: categorize(name, description, triggers),
+    category: categorize(name, description, triggers, tags),
     triggers,
     allowedTools,
+    tags,
     version: fm.version || '',
     dir,
     _mdFile: mdFile,
@@ -454,18 +488,70 @@ function loadFullData(skill) {
     } catch (_) { content = ''; }
   }
 
-  const sections = extractSections(content);
-  const contextual = extractContextual(content);
+  // Strip frontmatter before body extraction
+  const bodyContent = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+
+  const sections = extractSections(bodyContent);
+  const contextual = extractContextual(bodyContent);
+  const summary = extractSummary(bodyContent);
 
   return {
     ...skill,
     sections,
+    summary,
     howItWorks: contextual.howItWorks,
     whenToUse: contextual.whenToUse,
     limitations: contextual.limitations,
   };
 }
 
+// ---------------------------------------------------------------------------
+// Compute completeness score (0-100) for documentation quality
+// ---------------------------------------------------------------------------
+const GARBAGE_PATTERNS = /^[>|](-|\+)?$|^---|^\s*$|^category:|^tags:/;
+
+function computeCompleteness(skill, full) {
+  let score = 0;
+
+  // description: 20 points — non-empty and not a YAML artifact
+  if (skill.description && skill.description.length > 2 && !GARBAGE_PATTERNS.test(skill.description)) {
+    score += 20;
+  }
+
+  // summary: 20 points — non-empty and not a YAML artifact
+  if (full && full.summary && full.summary.length > 0 && !GARBAGE_PATTERNS.test(full.summary)) {
+    score += 20;
+  }
+
+  // whenToUse: 20 points — non-empty and no YAML leakage
+  if (full && full.whenToUse && full.whenToUse.length > 20 && !full.whenToUse.startsWith('---')) {
+    score += 20;
+  }
+
+  // howItWorks: 10 points — no YAML metadata
+  if (full && full.howItWorks && full.howItWorks.length > 20 &&
+      !/^---/.test(full.howItWorks) && !/^category:/.test(full.howItWorks) && !/^tags:/.test(full.howItWorks)) {
+    score += 10;
+  }
+
+  // tags: 10 points
+  if (skill.tags && skill.tags.length > 0) {
+    score += 10;
+  }
+
+  // triggers: 10 points
+  if (skill.triggers && skill.triggers.length > 0) {
+    score += 10;
+  }
+
+  // limitations: 10 points
+  if (full && full.limitations && full.limitations.length > 10) {
+    score += 10;
+  }
+
+  return score;
+}
+
 // ---------------------------------------------------------------------------
 // Clean skill for output (remove internal fields)
 // ---------------------------------------------------------------------------
@@ -476,22 +562,107 @@ function cleanSkill(skill, includeFull) {
     category: skill.category,
     sources: skill.sources,
     triggers: skill.triggers,
+    tags: skill.tags,
     allowedTools: skill.allowedTools,
     version: skill.version,
     dir: skill.dir.replace(HOME, '~'),
+    tokenCost: estimateTokens(skill.description),
   };
 
   if (includeFull) {
     const full = loadFullData(skill);
     base.sections = full.sections;
+    base.summary = full.summary;
     base.howItWorks = full.howItWorks;
     base.whenToUse = full.whenToUse;
     base.limitations = full.limitations;
+    base.completeness = computeCompleteness(skill, full);
   }
 
   return base;
 }
 
+function estimateTokens(text) {
+  if (!text) return 0;
+  // Rough estimate: ~4 characters per token for English text
+  // This is conservative; actual tokenization varies by model
+  return Math.ceil(text.length / 4);
+}
+
+function computeHealthStats(skills) {
+  const CONTEXT_WINDOW = 200_000; // Claude's context window
+  const DESCRIPTION_BUDGET = 16_000; // ~1% of context for skill descriptions
+  const STALE_DAYS = 30;
+
+  let totalDescriptionLength = 0;
+  let totalTokenEstimate = 0;
+  const staleSkills = [];
+  const securityFlags = [];
+  const duplicates = new Map();
+
+  for (const skill of skills) {
+    // Token cost
+    const descLen = (skill.description || '').length;
+    totalDescriptionLength += descLen;
+    totalTokenEstimate += estimateTokens(skill.description);
+
+    // Stale detection (based on file mtime)
+    try {
+      const stat = fs.statSync(skill._mdFile);
+      const daysSinceModified = (Date.now() - stat.mtimeMs) / (1000 * 60 * 60 * 24);
+      if (daysSinceModified > STALE_DAYS) {
+        staleSkills.push({
+          name: skill.name,
+          daysSinceModified: Math.floor(daysSinceModified),
+          lastModified: stat.mtime.toISOString().slice(0, 10),
+        });
+      }
+    } catch (_) { /* ignore stat errors */ }
+
+    // Security red flags (simple patterns)
+    const content = (skill._content || '').toLowerCase();
+    const flags = [];
+    if (content.includes('curl ') && content.includes(' | ')) flags.push('pipe-from-curl');
+    if (content.includes('eval(') || content.includes('exec(')) flags.push('eval-exec');
+    if (content.includes('api_key') || content.includes('apikey') || content.includes('token')) flags.push('handles-secrets');
+    if (content.includes('rm -rf') || content.includes('rmdir /s')) flags.push('destructive-commands');
+    if (flags.length > 0) {
+      securityFlags.push({ name: skill.name, flags });
+    }
+
+    // Duplicate detection (by normalized name)
+    const normalizedName = skill.name.toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (duplicates.has(normalizedName)) {
+      duplicates.get(normalizedName).push(skill.name);
+    } else {
+      duplicates.set(normalizedName, [skill.name]);
+    }
+  }
+
+  // Filter out non-duplicates
+  const duplicateGroups = [...duplicates.entries()]
+    .filter(([, names]) => names.length > 1)
+    .map(([normalized, names]) => ({ normalized, names }));
+
+  // Hidden skills calculation
+  const hiddenCount = DESCRIPTION_BUDGET > 0
+    ? Math.max(0, Math.floor((totalDescriptionLength - DESCRIPTION_BUDGET) / 100))
+    : 0;
+
+  return {
+    totalSkills: skills.length,
+    totalDescriptionLength,
+    totalTokenEstimate,
+    descriptionBudget: DESCRIPTION_BUDGET,
+    budgetUsedPercent: Math.round((totalDescriptionLength / DESCRIPTION_BUDGET) * 100),
+    hiddenSkillEstimate: Math.min(hiddenCount, skills.length),
+    staleSkills: staleSkills.sort((a, b) => b.daysSinceModified - a.daysSinceModified),
+    securityFlags,
+    duplicateGroups,
+    contextWindowPercent: Math.round((totalTokenEstimate / CONTEXT_WINDOW) * 100 * 100) / 100,
+  };
+}
+
 function normalizeSkillName(name) {
   return String(name || '').replace(/^[^:]+:/, '').toLowerCase();
 }