skill-tools 0.2.0

package/dist/cli.js

@@ -0,0 +1,979 @@
+#!/usr/bin/env node
+import { resolveSkillFiles, parseSkill } from '@skill-tools/core';
+import { Command } from 'commander';
+import { readdirSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+
+// src/formatters/json.ts
+function formatValidationJson(results) {
+  return JSON.stringify(
+    results.map((r) => ({
+      filePath: r.filePath,
+      name: r.name,
+      valid: r.valid,
+      diagnostics: r.diagnostics
+    })),
+    null,
+    2
+  );
+}
+function formatLintJson(results) {
+  return JSON.stringify(
+    results.map((r) => ({
+      filePath: r.filePath,
+      name: r.name,
+      errorCount: r.errorCount,
+      warningCount: r.warningCount,
+      infoCount: r.infoCount,
+      diagnostics: r.diagnostics
+    })),
+    null,
+    2
+  );
+}
+function formatScoreJson(name, qualityScore) {
+  return JSON.stringify(
+    {
+      name,
+      score: qualityScore.score,
+      dimensions: qualityScore.dimensions,
+      suggestions: qualityScore.suggestions
+    },
+    null,
+    2
+  );
+}
+
+// src/formatters/text.ts
+var RESET = "\x1B[0m";
+var RED = "\x1B[31m";
+var YELLOW = "\x1B[33m";
+var GREEN = "\x1B[32m";
+var CYAN = "\x1B[36m";
+var DIM = "\x1B[2m";
+var BOLD = "\x1B[1m";
+function severityIcon(severity) {
+  switch (severity) {
+    case "error":
+      return `${RED}\u2717${RESET}`;
+    case "warning":
+      return `${YELLOW}\u26A0${RESET}`;
+    case "info":
+      return `${CYAN}\u2139${RESET}`;
+    default:
+      return " ";
+  }
+}
+function formatDiagnostic(diag) {
+  const icon = severityIcon(diag.severity);
+  const location = diag.line ? `${DIM}line ${diag.line}${RESET} ` : "";
+  const ruleId = `${DIM}(${diag.ruleId})${RESET}`;
+  let line = `  ${icon} ${location}${diag.message} ${ruleId}`;
+  if (diag.fix) {
+    line += `
+    ${DIM}\u2192 ${diag.fix}${RESET}`;
+  }
+  return line;
+}
+function formatValidation(results) {
+  const lines = [];
+  for (const result of results) {
+    const status = result.valid ? `${GREEN}\u2713 PASS${RESET}` : `${RED}\u2717 FAIL${RESET}`;
+    lines.push(`${BOLD}${result.name}${RESET} ${status}`);
+    lines.push(`  ${DIM}${result.filePath}${RESET}`);
+    if (result.diagnostics.length > 0) {
+      lines.push("");
+      for (const diag of result.diagnostics) {
+        lines.push(formatDiagnostic(diag));
+      }
+    }
+    lines.push("");
+  }
+  const total = results.length;
+  const passed = results.filter((r) => r.valid).length;
+  const failed = total - passed;
+  if (failed > 0) {
+    lines.push(`${RED}${failed} failed${RESET}, ${GREEN}${passed} passed${RESET} (${total} total)`);
+  } else {
+    lines.push(`${GREEN}All ${total} skill(s) passed validation${RESET}`);
+  }
+  return lines.join("\n");
+}
+function formatLint(results) {
+  const lines = [];
+  for (const result of results) {
+    lines.push(`${BOLD}${result.name}${RESET}`);
+    lines.push(`  ${DIM}${result.filePath}${RESET}`);
+    if (result.diagnostics.length > 0) {
+      lines.push("");
+      for (const diag of result.diagnostics) {
+        lines.push(formatDiagnostic(diag));
+      }
+    } else {
+      lines.push(`  ${GREEN}No lint issues${RESET}`);
+    }
+    lines.push("");
+  }
+  const totalErrors = results.reduce((sum, r) => sum + r.errorCount, 0);
+  const totalWarnings = results.reduce((sum, r) => sum + r.warningCount, 0);
+  const totalInfo = results.reduce((sum, r) => sum + r.infoCount, 0);
+  const parts = [];
+  if (totalErrors > 0) parts.push(`${RED}${totalErrors} error(s)${RESET}`);
+  if (totalWarnings > 0) parts.push(`${YELLOW}${totalWarnings} warning(s)${RESET}`);
+  if (totalInfo > 0) parts.push(`${CYAN}${totalInfo} info${RESET}`);
+  if (parts.length > 0) {
+    lines.push(parts.join(", "));
+  } else {
+    lines.push(`${GREEN}No lint issues found${RESET}`);
+  }
+  return lines.join("\n");
+}
+function formatScore(_name, qualityScore) {
+  const lines = [];
+  const stars = scoreToStars(qualityScore.score);
+  lines.push("");
+  lines.push(`  ${BOLD}Quality Score: ${qualityScore.score}/100${RESET}  ${stars}`);
+  lines.push("");
+  for (const [_key, dim] of Object.entries(qualityScore.dimensions)) {
+    const barWidth = 10;
+    const filled = Math.round(dim.score / dim.max * barWidth);
+    const empty = barWidth - filled;
+    const bar = `${GREEN}${"\u2588".repeat(filled)}${DIM}${"\u2591".repeat(empty)}${RESET}`;
+    const scoreStr = `${dim.score}/${dim.max}`.padStart(6);
+    lines.push(`  ${dim.label.padEnd(24)} ${bar}  ${scoreStr}`);
+  }
+  if (qualityScore.suggestions.length > 0) {
+    lines.push("");
+    lines.push(`  ${BOLD}Top suggestions:${RESET}`);
+    for (let i = 0; i < Math.min(5, qualityScore.suggestions.length); i++) {
+      const s = qualityScore.suggestions[i];
+      lines.push(`  ${i + 1}. ${s.message} ${DIM}(+${s.pointsGain} points)${RESET}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function scoreToStars(score2) {
+  if (score2 >= 90) return "\u2605\u2605\u2605\u2605\u2605";
+  if (score2 >= 75) return "\u2605\u2605\u2605\u2605";
+  if (score2 >= 60) return "\u2605\u2605\u2605";
+  if (score2 >= 40) return "\u2605\u2605";
+  if (score2 >= 20) return "\u2605";
+  return "";
+}
+
+// src/rules/consistent-headings.ts
+var consistentHeadings = {
+  id: "consistent-headings",
+  description: "Headings should follow a consistent hierarchy without skipping levels",
+  defaultSeverity: "info",
+  check(skill) {
+    const diagnostics = [];
+    const sections = skill.sections;
+    for (let i = 1; i < sections.length; i++) {
+      const prev = sections[i - 1];
+      const curr = sections[i];
+      if (curr.depth > prev.depth + 1) {
+        diagnostics.push({
+          ruleId: "consistent-headings",
+          severity: "info",
+          message: `Heading "${curr.heading}" (H${curr.depth}) skips levels from "${prev.heading}" (H${prev.depth})`,
+          file: skill.filePath,
+          line: curr.line,
+          fix: `Change to H${prev.depth + 1} for consistent hierarchy`
+        });
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/description-specificity.ts
+var GENERIC_VERBS = [
+  "manage",
+  "handle",
+  "process",
+  "deal with",
+  "work with",
+  "do stuff",
+  "help with",
+  "assist with",
+  "take care of"
+];
+var descriptionSpecificity = {
+  id: "description-specificity",
+  description: 'Description should contain specific nouns or action verbs, not generic phrases like "manages" or "handles"',
+  defaultSeverity: "warning",
+  check(skill) {
+    const desc = skill.metadata.description;
+    if (!desc) return [];
+    const diagnostics = [];
+    const lowerDesc = desc.toLowerCase();
+    const foundGeneric = GENERIC_VERBS.filter((verb) => lowerDesc.includes(verb));
+    if (foundGeneric.length > 0) {
+      diagnostics.push({
+        ruleId: "description-specificity",
+        severity: "warning",
+        message: `Description uses generic verbs: ${foundGeneric.map((v) => `"${v}"`).join(", ")}. Use specific action verbs instead`,
+        file: skill.filePath,
+        line: 1,
+        fix: 'Replace generic verbs with specific ones. E.g., "Deploy apps to Vercel" instead of "Handle Vercel deployments"'
+      });
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/description-trigger-keywords.ts
+var descriptionTriggerKeywords = {
+  id: "description-trigger-keywords",
+  description: "Description should contain words that a user would naturally type to trigger this skill",
+  defaultSeverity: "warning",
+  check(skill) {
+    const desc = skill.metadata.description;
+    if (!desc) return [];
+    const diagnostics = [];
+    const hasTriggerPhrase = /\buse when\b|\buse for\b|\buse this\b|\binvoke when\b|\btrigger when\b/i.test(desc);
+    const hasActionVerb = /\b(deploy|test|build|run|create|generate|analyze|review|format|lint|fix|check|commit|push|pull|fetch|install|configure|setup|search|find|list|delete|update|migrate|convert|export|import)\b/i.test(
+      desc
+    );
+    if (!hasTriggerPhrase && !hasActionVerb) {
+      diagnostics.push({
+        ruleId: "description-trigger-keywords",
+        severity: "warning",
+        message: 'Description lacks trigger keywords. Include "Use when..." or specific action verbs (deploy, test, build, etc.)',
+        file: skill.filePath,
+        line: 1,
+        fix: 'Add trigger context: "Deploy apps to Vercel. Use when the user wants to publish or ship a web app."'
+      });
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/instructions-has-error-handling.ts
+var instructionsHasErrorHandling = {
+  id: "instructions-has-error-handling",
+  description: "Instructions should mention what to do when things fail",
+  defaultSeverity: "info",
+  check(skill) {
+    const diagnostics = [];
+    const body = skill.body.toLowerCase();
+    const hasErrorSection = /#{1,3}\s+(?:error|troubleshoot|fail|issue|problem|debug)/i.test(
+      skill.body
+    );
+    const hasErrorKeywords = /\b(?:error|fail|troubleshoot|if .+ fails|when .+ fails|common issues|known issues)\b/.test(
+      body
+    );
+    if (!hasErrorSection && !hasErrorKeywords) {
+      diagnostics.push({
+        ruleId: "instructions-has-error-handling",
+        severity: "info",
+        message: "Instructions have no error handling guidance. Add a section about common failures",
+        file: skill.filePath,
+        fix: 'Add an "## Error Handling" section describing common failures and how to resolve them'
+      });
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/instructions-has-examples.ts
+var instructionsHasExamples = {
+  id: "instructions-has-examples",
+  description: "Skill instructions should include at least one concrete example",
+  defaultSeverity: "info",
+  check(skill) {
+    const diagnostics = [];
+    const body = skill.body;
+    const hasCodeBlock = /```[\s\S]*?```/.test(body);
+    const hasExampleSection = /^#{1,3}\s+(?:example|usage|demo)/im.test(body);
+    const hasInlineCode = /`[^`]+`/.test(body);
+    const hasNumberedSteps = /^\d+\.\s+/m.test(body);
+    if (!hasCodeBlock && !hasExampleSection && !hasInlineCode && !hasNumberedSteps) {
+      diagnostics.push({
+        ruleId: "instructions-has-examples",
+        severity: "info",
+        message: "Instructions have no examples. Add code blocks, numbered steps, or an Examples section",
+        file: skill.filePath,
+        fix: "Add a code block showing expected usage:\n```bash\nskill-tools check ./my-skill/\n```"
+      });
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/no-hardcoded-paths.ts
+var HARDCODED_PATH_PATTERN = /(?:\/Users\/\w+|\/home\/\w+|[A-Z]:\\\\?Users\\\\?\w+|\/var\/|\/tmp\/\w+)/;
+var noHardcodedPaths = {
+  id: "no-hardcoded-paths",
+  description: "Flag absolute filesystem paths that are machine-specific",
+  defaultSeverity: "error",
+  check(skill) {
+    const diagnostics = [];
+    const lines = skill.body.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (HARDCODED_PATH_PATTERN.test(line)) {
+        const match = HARDCODED_PATH_PATTERN.exec(line);
+        diagnostics.push({
+          ruleId: "no-hardcoded-paths",
+          severity: "error",
+          message: `Hardcoded path found: "${match?.[0]}". Use environment variables or relative paths`,
+          file: skill.filePath,
+          line: i + 1,
+          fix: "Replace with $HOME, relative paths, or environment variables"
+        });
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/no-secrets.ts
+var SECRET_PATTERNS = [
+  { pattern: /sk-[a-zA-Z0-9]{20,}/, label: "OpenAI API key" },
+  { pattern: /sk_live_[a-zA-Z0-9]{20,}/, label: "Stripe live key" },
+  { pattern: /sk_test_[a-zA-Z0-9]{20,}/, label: "Stripe test key" },
+  { pattern: /ghp_[a-zA-Z0-9]{36,}/, label: "GitHub personal access token" },
+  { pattern: /gho_[a-zA-Z0-9]{36,}/, label: "GitHub OAuth token" },
+  { pattern: /github_pat_[a-zA-Z0-9_]{20,}/, label: "GitHub fine-grained token" },
+  { pattern: /xoxb-[a-zA-Z0-9-]+/, label: "Slack bot token" },
+  { pattern: /xoxp-[a-zA-Z0-9-]+/, label: "Slack user token" },
+  { pattern: /AKIA[0-9A-Z]{16}/, label: "AWS access key ID" },
+  { pattern: /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/, label: "Private key" },
+  { pattern: /eyJ[a-zA-Z0-9_-]{20,500}\.[a-zA-Z0-9_-]{20,500}\./, label: "JWT token" }
+];
+var noSecrets = {
+  id: "no-secrets",
+  description: "Flag patterns that look like API keys, tokens, or passwords",
+  defaultSeverity: "error",
+  check(skill) {
+    const diagnostics = [];
+    const lines = skill.rawContent.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      for (const { pattern, label } of SECRET_PATTERNS) {
+        if (pattern.test(line)) {
+          diagnostics.push({
+            ruleId: "no-secrets",
+            severity: "error",
+            message: `Possible ${label} detected. Never embed secrets in SKILL.md files`,
+            file: skill.filePath,
+            line: i + 1,
+            fix: "Use environment variable references (e.g., $API_KEY) instead of actual secrets"
+          });
+          break;
+        }
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/progressive-disclosure.ts
+var DEFAULT_MAX_LINES = 500;
+var progressiveDisclosure = {
+  id: "progressive-disclosure",
+  description: "Large SKILL.md files should use references/ or scripts/ to keep the main file lean",
+  defaultSeverity: "warning",
+  check(skill) {
+    const diagnostics = [];
+    if (skill.lineCount > DEFAULT_MAX_LINES) {
+      const hasReferences = skill.fileReferences.some((r) => r.path.startsWith("references/"));
+      const hasScripts = skill.fileReferences.some((r) => r.path.startsWith("scripts/"));
+      if (!hasReferences && !hasScripts) {
+        diagnostics.push({
+          ruleId: "progressive-disclosure",
+          severity: "warning",
+          message: `SKILL.md is ${skill.lineCount} lines (recommended: <${DEFAULT_MAX_LINES}). Move detailed content to references/ or scripts/`,
+          file: skill.filePath,
+          fix: "Create a references/ directory and move detailed API docs, examples, or reference tables there. Link from SKILL.md: [See API reference](references/api.md)"
+        });
+      }
+    }
+    return diagnostics;
+  }
+};
+
+// src/rules/index.ts
+var builtinRules = /* @__PURE__ */ new Map([
+  [descriptionSpecificity.id, descriptionSpecificity],
+  [descriptionTriggerKeywords.id, descriptionTriggerKeywords],
+  [progressiveDisclosure.id, progressiveDisclosure],
+  [noHardcodedPaths.id, noHardcodedPaths],
+  [noSecrets.id, noSecrets],
+  [instructionsHasExamples.id, instructionsHasExamples],
+  [instructionsHasErrorHandling.id, instructionsHasErrorHandling],
+  [consistentHeadings.id, consistentHeadings]
+]);
+Object.fromEntries(
+  Array.from(builtinRules.values()).map((rule) => [rule.id, rule.defaultSeverity])
+);
+
+// src/linter.ts
+function lint(skill, rulesConfig) {
+  const diagnostics = [];
+  for (const [ruleId, rule] of builtinRules) {
+    const ruleDiagnostics = rule.check(skill);
+    const severity = rule.defaultSeverity;
+    for (const diag of ruleDiagnostics) {
+      diagnostics.push({
+        ...diag,
+        severity
+      });
+    }
+  }
+  return {
+    filePath: skill.filePath,
+    name: skill.metadata.name ?? "unknown",
+    diagnostics,
+    errorCount: diagnostics.filter((d) => d.severity === "error").length,
+    warningCount: diagnostics.filter((d) => d.severity === "warning").length,
+    infoCount: diagnostics.filter((d) => d.severity === "info").length
+  };
+}
+
+// src/scorer/description-quality.ts
+var MAX_POINTS = 30;
+function scoreDescriptionQuality(skill) {
+  const desc = skill.metadata.description;
+  if (!desc) {
+    return {
+      score: 0,
+      max: MAX_POINTS,
+      label: "Description Quality",
+      details: "No description provided"
+    };
+  }
+  let points = 0;
+  const details = [];
+  const len = desc.length;
+  if (len >= 50 && len <= 300) {
+    points += 8;
+  } else if (len >= 30 && len <= 400) {
+    points += 5;
+  } else if (len >= 10) {
+    points += 2;
+  }
+  details.push(`Length: ${len} chars`);
+  const actionVerbs = /\b(deploy|test|build|run|create|generate|analyze|review|format|lint|fix|check|commit|push|pull|fetch|install|configure|search|find|list|delete|update|migrate|convert|export|import)\b/gi;
+  const verbCount = (desc.match(actionVerbs) ?? []).length;
+  if (verbCount >= 2) {
+    points += 8;
+  } else if (verbCount === 1) {
+    points += 5;
+  }
+  details.push(`Action verbs: ${verbCount}`);
+  const hasTriggerContext = /\buse when\b|\buse for\b|\buse this\b|\binvoke when\b|\bwhen the user\b/i.test(desc);
+  if (hasTriggerContext) {
+    points += 8;
+    details.push("Has trigger context");
+  }
+  const name = skill.metadata.name ?? "";
+  const nameWords = name.split("-").filter((w) => w.length > 2);
+  const descLower = desc.toLowerCase();
+  const nameRepetitions = nameWords.filter((w) => descLower.includes(w)).length;
+  const ratio = nameWords.length > 0 ? nameRepetitions / nameWords.length : 0;
+  if (ratio < 0.5) {
+    points += 6;
+  } else if (ratio < 0.8) {
+    points += 3;
+  }
+  return {
+    score: Math.min(points, MAX_POINTS),
+    max: MAX_POINTS,
+    label: "Description Quality",
+    details: details.join(", ")
+  };
+}
+
+// src/scorer/instruction-clarity.ts
+var MAX_POINTS2 = 25;
+function scoreInstructionClarity(skill) {
+  const body = skill.body;
+  if (!body || body.trim().length === 0) {
+    return { score: 0, max: MAX_POINTS2, label: "Instruction Clarity", details: "No instructions" };
+  }
+  let points = 0;
+  const details = [];
+  const codeBlockCount = (body.match(/```[\s\S]*?```/g) ?? []).length;
+  if (codeBlockCount >= 2) {
+    points += 7;
+    details.push(`${codeBlockCount} code blocks`);
+  } else if (codeBlockCount === 1) {
+    points += 4;
+    details.push("1 code block");
+  }
+  const numberedSteps = (body.match(/^\d+\.\s+/gm) ?? []).length;
+  if (numberedSteps >= 3) {
+    points += 6;
+    details.push(`${numberedSteps} numbered steps`);
+  } else if (numberedSteps >= 1) {
+    points += 3;
+    details.push(`${numberedSteps} numbered steps`);
+  }
+  const hasErrorSection = /#{1,3}\s+(?:error|troubleshoot|fail|issue|problem|debug)/i.test(body);
+  const hasErrorKeywords = /\b(?:error|fail|troubleshoot|if .+ fails|when .+ fails|common issues)\b/i.test(body);
+  if (hasErrorSection) {
+    points += 6;
+    details.push("Error handling section");
+  } else if (hasErrorKeywords) {
+    points += 3;
+    details.push("Error mentions");
+  }
+  const wordCount = body.split(/\s+/).length;
+  if (wordCount >= 100) {
+    points += 6;
+  } else if (wordCount >= 50) {
+    points += 4;
+  } else if (wordCount >= 20) {
+    points += 2;
+  }
+  details.push(`${wordCount} words`);
+  return {
+    score: Math.min(points, MAX_POINTS2),
+    max: MAX_POINTS2,
+    label: "Instruction Clarity",
+    details: details.join(", ")
+  };
+}
+
+// src/scorer/progressive-disclosure-score.ts
+var MAX_POINTS3 = 15;
+function scoreProgressiveDisclosure(skill) {
+  let points = 0;
+  const details = [];
+  const isSmall = skill.lineCount <= 100;
+  const isMedium = skill.lineCount <= 500;
+  if (isSmall) {
+    points += 15;
+    details.push("Skill is compact");
+  } else if (isMedium) {
+    points += 8;
+    const hasRefs = skill.fileReferences.some(
+      (r) => r.path.startsWith("references/") || r.path.startsWith("scripts/")
+    );
+    if (hasRefs) {
+      points += 7;
+      details.push("Uses supporting files");
+    } else {
+      details.push("Could benefit from references/");
+    }
+  } else {
+    const hasRefs = skill.fileReferences.some(
+      (r) => r.path.startsWith("references/") || r.path.startsWith("scripts/")
+    );
+    if (hasRefs) {
+      points += 10;
+      details.push("Uses supporting files (recommended: further reduce main file)");
+    } else {
+      points += 2;
+      details.push("Large file without progressive disclosure");
+    }
+  }
+  return {
+    score: Math.min(points, MAX_POINTS3),
+    max: MAX_POINTS3,
+    label: "Progressive Disclosure",
+    details: details.join(", ")
+  };
+}
+
+// src/scorer/security-score.ts
+var MAX_POINTS4 = 10;
+function scoreSecurityScore(skill) {
+  let points = MAX_POINTS4;
+  const details = [];
+  const secretDiags = noSecrets.check(skill);
+  if (secretDiags.length > 0) {
+    points -= 10;
+    details.push(`${secretDiags.length} possible secret(s) found`);
+  }
+  const pathDiags = noHardcodedPaths.check(skill);
+  if (pathDiags.length > 0) {
+    points -= 3;
+    details.push(`${pathDiags.length} hardcoded path(s)`);
+  }
+  const body = skill.body;
+  const suspiciousPatterns = [
+    /\brm\s+-rf\s+\/(?!\s)/,
+    // rm -rf / (not followed by space)
+    /\bcurl\s+.*\|\s*(?:bash|sh)\b/,
+    // curl | bash
+    /\beval\s+\$/
+    // eval $
+  ];
+  for (const pattern of suspiciousPatterns) {
+    if (pattern.test(body)) {
+      points -= 2;
+      details.push("Suspicious shell pattern");
+      break;
+    }
+  }
+  if (details.length === 0) {
+    details.push("No security issues");
+  }
+  return {
+    score: Math.max(0, points),
+    max: MAX_POINTS4,
+    label: "Security",
+    details: details.join(", ")
+  };
+}
+
+// src/scorer/spec-compliance.ts
+var MAX_POINTS5 = 20;
+function scoreSpecCompliance(skill) {
+  let points = 0;
+  const details = [];
+  if (skill.metadata.name) {
+    points += 5;
+    details.push("Has name");
+  }
+  if (skill.metadata.description) {
+    points += 5;
+    details.push("Has description");
+  }
+  if (skill.tokenCount <= 5e3) {
+    points += 5;
+    details.push(`${skill.tokenCount} tokens (within budget)`);
+  } else if (skill.tokenCount <= 7500) {
+    points += 2;
+    details.push(`${skill.tokenCount} tokens (over budget)`);
+  } else {
+    details.push(`${skill.tokenCount} tokens (far over budget)`);
+  }
+  if (skill.lineCount <= 500) {
+    points += 5;
+    details.push(`${skill.lineCount} lines`);
+  } else if (skill.lineCount <= 750) {
+    points += 2;
+    details.push(`${skill.lineCount} lines (over recommendation)`);
+  } else {
+    details.push(`${skill.lineCount} lines (far over recommendation)`);
+  }
+  return {
+    score: Math.min(points, MAX_POINTS5),
+    max: MAX_POINTS5,
+    label: "Spec Compliance",
+    details: details.join(", ")
+  };
+}
+
+// src/scorer/index.ts
+function score(skill) {
+  const descriptionQuality = scoreDescriptionQuality(skill);
+  const instructionClarity = scoreInstructionClarity(skill);
+  const specCompliance = scoreSpecCompliance(skill);
+  const progressiveDisclosure2 = scoreProgressiveDisclosure(skill);
+  const security = scoreSecurityScore(skill);
+  const totalScore = descriptionQuality.score + instructionClarity.score + specCompliance.score + progressiveDisclosure2.score + security.score;
+  const dimensions = {
+    description_quality: descriptionQuality,
+    instruction_clarity: instructionClarity,
+    spec_compliance: specCompliance,
+    progressive_disclosure: progressiveDisclosure2,
+    security
+  };
+  const suggestions = generateSuggestions(skill, dimensions);
+  return {
+    score: totalScore,
+    dimensions,
+    suggestions
+  };
+}
+function generateSuggestions(skill, dimensions) {
+  const suggestions = [];
+  const descDim = dimensions.description_quality;
+  const instrDim = dimensions.instruction_clarity;
+  const progDim = dimensions.progressive_disclosure;
+  const secDim = dimensions.security;
+  if (!skill.metadata.description) {
+    suggestions.push({
+      message: "Add a description field to the frontmatter",
+      pointsGain: 15,
+      dimension: "description_quality"
+    });
+  } else {
+    if (descDim.score < descDim.max * 0.6) {
+      if (!/\buse when\b/i.test(skill.metadata.description)) {
+        suggestions.push({
+          message: 'Add "Use when..." to the description to clarify trigger conditions',
+          pointsGain: 8,
+          dimension: "description_quality"
+        });
+      }
+    }
+  }
+  if (instrDim.score < instrDim.max * 0.5) {
+    const hasCodeBlock = /```[\s\S]*?```/.test(skill.body);
+    if (!hasCodeBlock) {
+      suggestions.push({
+        message: "Add a concrete usage example with a code block",
+        pointsGain: 5,
+        dimension: "instruction_clarity"
+      });
+    }
+    const hasNumberedSteps = /^\d+\.\s+/m.test(skill.body);
+    if (!hasNumberedSteps) {
+      suggestions.push({
+        message: "Add numbered steps for the main workflow",
+        pointsGain: 4,
+        dimension: "instruction_clarity"
+      });
+    }
+    const hasErrorHandling = /#{1,3}\s+(?:error|troubleshoot)/i.test(skill.body);
+    if (!hasErrorHandling) {
+      suggestions.push({
+        message: 'Add an "## Error Handling" section',
+        pointsGain: 3,
+        dimension: "instruction_clarity"
+      });
+    }
+  }
+  if (!skill.metadata.name) {
+    suggestions.push({
+      message: "Add a name field to the frontmatter",
+      pointsGain: 5,
+      dimension: "spec_compliance"
+    });
+  }
+  if (skill.tokenCount > 5e3) {
+    suggestions.push({
+      message: `Reduce token count from ${skill.tokenCount} to under 5,000`,
+      pointsGain: 3,
+      dimension: "spec_compliance"
+    });
+  }
+  if (progDim.score < progDim.max * 0.5 && skill.lineCount > 200) {
+    suggestions.push({
+      message: "Move detailed reference content to a references/ directory",
+      pointsGain: 5,
+      dimension: "progressive_disclosure"
+    });
+  }
+  if (secDim.score < secDim.max) {
+    suggestions.push({
+      message: "Fix security issues (secrets, hardcoded paths, or suspicious patterns)",
+      pointsGain: secDim.max - secDim.score,
+      dimension: "security"
+    });
+  }
+  suggestions.sort((a, b) => b.pointsGain - a.pointsGain);
+  return suggestions;
+}
+async function validate(path) {
+  const locations = await resolveSkillFiles(path);
+  if (locations.length === 0) {
+    return [
+      {
+        filePath: path,
+        name: "unknown",
+        valid: false,
+        skill: null,
+        diagnostics: [
+          {
+            ruleId: "skill-not-found",
+            severity: "error",
+            message: `No SKILL.md file found at path: ${path}`,
+            file: path
+          }
+        ]
+      }
+    ];
+  }
+  const results = [];
+  for (const location of locations) {
+    const parseResult = await parseSkill(location.skillFile);
+    const extraDiagnostics = parseResult.ok ? validateStructure(parseResult.skill) : [];
+    const allDiagnostics = [...parseResult.diagnostics, ...extraDiagnostics];
+    const hasErrors = allDiagnostics.some((d) => d.severity === "error");
+    results.push({
+      filePath: location.skillFile,
+      name: parseResult.ok ? parseResult.skill.metadata.name ?? location.dirName : location.dirName,
+      valid: !hasErrors,
+      skill: parseResult.ok ? parseResult.skill : null,
+      diagnostics: allDiagnostics
+    });
+  }
+  return results;
+}
+function validateStructure(skill) {
+  const diagnostics = [];
+  const dirPath = skill.dirPath;
+  const expectedDirs = ["scripts", "references", "assets", "examples", "agents"];
+  const entries = safeReaddir(dirPath);
+  for (const entry of entries) {
+    if (entry === "SKILL.md" || entry.startsWith(".")) continue;
+    const entryPath = join(dirPath, entry);
+    const isDir = safeIsDirectory(entryPath);
+    if (isDir && !expectedDirs.includes(entry)) {
+      diagnostics.push({
+        ruleId: "unexpected-directory",
+        severity: "info",
+        message: `Unexpected directory "${entry}" in skill directory. Expected: ${expectedDirs.join(", ")}`,
+        file: skill.filePath
+      });
+    }
+  }
+  if (skill.rawContent.charCodeAt(0) === 65279) {
+    diagnostics.push({
+      ruleId: "no-bom",
+      severity: "warning",
+      message: "SKILL.md contains a UTF-8 BOM (byte order mark). Remove it for compatibility",
+      file: skill.filePath,
+      line: 1,
+      fix: "Save the file without BOM"
+    });
+  }
+  if (skill.rawContent.includes("\0")) {
+    diagnostics.push({
+      ruleId: "no-binary",
+      severity: "error",
+      message: "SKILL.md contains binary content (null bytes). It must be a text file",
+      file: skill.filePath
+    });
+  }
+  return diagnostics;
+}
+function safeReaddir(dirPath) {
+  try {
+    return readdirSync(dirPath).map(String);
+  } catch {
+    return [];
+  }
+}
+function safeIsDirectory(path) {
+  try {
+    return existsSync(path) && statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("skill-tools").description("Validate, lint, and score Agent Skills (SKILL.md) files").version("0.1.0");
+program.command("validate").alias("v").description("Validate SKILL.md files against the Agent Skills specification").argument("<path>", "Path to SKILL.md file, skill directory, or directory of skills").option("-f, --format <format>", "Output format: text or json", "text").action(async (path, opts) => {
+  const results = await validate(path);
+  const output = opts.format === "json" ? formatValidationJson(results) : formatValidation(results);
+  console.log(output);
+  const hasErrors = results.some((r) => !r.valid);
+  process.exitCode = hasErrors ? 1 : 0;
+});
+program.command("lint").alias("l").description("Lint SKILL.md files for quality issues beyond spec compliance").argument("<path>", "Path to SKILL.md file, skill directory, or directory of skills").option("-f, --format <format>", "Output format: text or json", "text").option(
+  "--fail-on <severity>",
+  "Fail if any diagnostic has this severity or higher: error, warning, info",
+  "error"
+).action(async (path, opts) => {
+  const locations = await resolveSkillFiles(path);
+  if (locations.length === 0) {
+    console.error(`No SKILL.md files found at: ${path}`);
+    process.exitCode = 1;
+    return;
+  }
+  const results = [];
+  for (const location of locations) {
+    const parseResult = await parseSkill(location.skillFile);
+    if (!parseResult.ok) {
+      console.error(
+        `Failed to parse ${location.skillFile}: ${parseResult.diagnostics.map((d) => d.message).join(", ")}`
+      );
+      continue;
+    }
+    results.push(lint(parseResult.skill));
+  }
+  const output = opts.format === "json" ? formatLintJson(results) : formatLint(results);
+  console.log(output);
+  const failSeverities = getFailSeverities(opts.failOn);
+  const hasFails = results.some((r) => r.diagnostics.some((d) => failSeverities.has(d.severity)));
+  process.exitCode = hasFails ? 1 : 0;
+});
+program.command("score").alias("s").description("Compute a quality score (0-100) for SKILL.md files").argument("<path>", "Path to SKILL.md file, skill directory, or directory of skills").option("-f, --format <format>", "Output format: text or json", "text").option("--min-score <score>", "Fail if any skill scores below this threshold", "0").action(async (path, opts) => {
+  const locations = await resolveSkillFiles(path);
+  const minScore = Number.parseInt(opts.minScore, 10);
+  if (Number.isNaN(minScore) || minScore < 0 || minScore > 100) {
+    console.error("--min-score must be a number between 0 and 100");
+    process.exitCode = 1;
+    return;
+  }
+  if (locations.length === 0) {
+    console.error(`No SKILL.md files found at: ${path}`);
+    process.exitCode = 1;
+    return;
+  }
+  let anyBelowMin = false;
+  for (const location of locations) {
+    const parseResult = await parseSkill(location.skillFile);
+    if (!parseResult.ok) {
+      console.error(
+        `Failed to parse ${location.skillFile}: ${parseResult.diagnostics.map((d) => d.message).join(", ")}`
+      );
+      anyBelowMin = true;
+      continue;
+    }
+    const qualityScore = score(parseResult.skill);
+    const name = parseResult.skill.metadata.name ?? location.dirName;
+    const output = opts.format === "json" ? formatScoreJson(name, qualityScore) : formatScore(name, qualityScore);
+    console.log(output);
+    if (qualityScore.score < minScore) {
+      anyBelowMin = true;
+    }
+  }
+  process.exitCode = anyBelowMin ? 1 : 0;
+});
+program.command("check").alias("c").description("Run validate + lint + score in a single pass").argument("<path>", "Path to SKILL.md file, skill directory, or directory of skills").option("-f, --format <format>", "Output format: text or json", "text").option(
+  "--fail-on <severity>",
+  "Fail if any diagnostic has this severity or higher: error, warning, info",
+  "error"
+).option("--min-score <score>", "Fail if any skill scores below this threshold", "0").action(async (path, opts) => {
+  const minScore = Number.parseInt(opts.minScore, 10);
+  const validationResults = await validate(path);
+  if (opts.format === "json") {
+    console.log(formatValidationJson(validationResults));
+  } else {
+    console.log(formatValidation(validationResults));
+  }
+  const validSkills = validationResults.filter((r) => r.valid && r.skill);
+  let anyBelowMin = false;
+  const failSeverities = getFailSeverities(opts.failOn);
+  let hasLintFails = false;
+  for (const result of validSkills) {
+    const skill = result.skill;
+    const lintResult = lint(skill);
+    if (opts.format === "json") {
+      console.log(formatLintJson([lintResult]));
+    } else {
+      console.log(formatLint([lintResult]));
+    }
+    if (lintResult.diagnostics.some((d) => failSeverities.has(d.severity))) {
+      hasLintFails = true;
+    }
+    const qualityScore = score(skill);
+    const name = skill.metadata.name ?? result.name;
+    if (opts.format === "json") {
+      console.log(formatScoreJson(name, qualityScore));
+    } else {
+      console.log(formatScore(name, qualityScore));
+    }
+    if (qualityScore.score < minScore) {
+      anyBelowMin = true;
+    }
+  }
+  const hasValidationErrors = validationResults.some((r) => !r.valid);
+  process.exitCode = hasValidationErrors || hasLintFails || anyBelowMin ? 1 : 0;
+});
+function getFailSeverities(failOn) {
+  switch (failOn) {
+    case "info":
+      return /* @__PURE__ */ new Set(["error", "warning", "info"]);
+    case "warning":
+      return /* @__PURE__ */ new Set(["error", "warning"]);
+    default:
+      return /* @__PURE__ */ new Set(["error"]);
+  }
+}
+program.parse();
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map