skill-tools 0.2.0

package/dist/index.js

@@ -0,0 +1,709 @@
+import { readdirSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { resolveSkillFiles, parseSkill } from '@skill-tools/core';
+
+// 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]
+]);
+var recommendedConfig = 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 configuredSeverity = rulesConfig?.[ruleId];
+    if (configuredSeverity === "off") continue;
+    const ruleDiagnostics = rule.check(skill);
+    const severity = configuredSeverity ?? 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
+  };
+}
+function parseRulesConfig(raw) {
+  const config = {};
+  const validSeverities = /* @__PURE__ */ new Set(["error", "warning", "info", "off"]);
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === "string" && validSeverities.has(value)) {
+      config[key] = value;
+    }
+  }
+  return config;
+}
+
+// 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;
+  }
+}
+
+export { builtinRules, lint, parseRulesConfig, recommendedConfig, score, validate };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map