@sagargupta1610/skillcheck 0.2.0

package/dist/chunk-MGSKVMAQ.js

@@ -0,0 +1,1180 @@
+// src/evals/schema.ts
+import { z } from "zod";
+var triggerTypeSchema = z.enum([
+  "explicit",
+  "implicit",
+  "contextual",
+  "negative"
+]);
+var triggerSchema = z.object({
+  id: z.string().min(1),
+  type: triggerTypeSchema,
+  prompt: z.string().min(1),
+  should_trigger: z.boolean().optional()
+}).loose();
+var evalCaseSchema = z.object({
+  id: z.number().int(),
+  prompt: z.string().min(1),
+  expected_output: z.string().optional(),
+  files: z.array(z.string()).optional(),
+  expectations: z.array(z.string().min(1)).min(1)
+}).loose();
+var evalsFileSchema = z.object({
+  skill_name: z.string().min(1),
+  settings: z.object({
+    runs_per_prompt: z.number().int().min(1).optional(),
+    trigger_threshold: z.number().min(0).max(1).optional()
+  }).loose().optional(),
+  evals: z.array(evalCaseSchema).optional(),
+  triggers: z.array(triggerSchema).optional()
+}).loose();
+
+// src/evals/index.ts
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { basename, join } from "path";
+function finding(severity, message) {
+  return {
+    code: severity === "error" ? "SC401" : "SC402",
+    alias: severity === "error" ? "evals-invalid" : "evals-advisory",
+    severity,
+    message,
+    file: "evals/evals.json"
+  };
+}
+async function checkEvals(skillDir, skillName) {
+  const path = join(skillDir, "evals", "evals.json");
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return [];
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    return [
+      finding(
+        "error",
+        `evals.json is not valid JSON: ${err instanceof Error ? err.message : err}`
+      )
+    ];
+  }
+  const parsed = evalsFileSchema.safeParse(data);
+  if (!parsed.success) {
+    return parsed.error.issues.slice(0, 10).map(
+      (i) => finding(
+        "error",
+        `evals.json ${i.path.join(".") || "(root)"}: ${i.message}`
+      )
+    );
+  }
+  const out = [];
+  const evals = parsed.data;
+  if (skillName && evals.skill_name !== skillName) {
+    out.push(
+      finding(
+        "error",
+        `skill_name "${evals.skill_name}" does not match the skill's resolved name "${skillName}"`
+      )
+    );
+  }
+  const ids = (evals.evals ?? []).map((e) => e.id);
+  if (new Set(ids).size !== ids.length) {
+    out.push(finding("error", "evals[].id values must be unique"));
+  }
+  for (const e of evals.evals ?? []) {
+    for (const f of e.files ?? []) {
+      try {
+        await stat(join(skillDir, f));
+      } catch {
+        out.push(
+          finding(
+            "error",
+            `evals[${e.id}].files: "${f}" does not exist relative to the skill root`
+          )
+        );
+      }
+    }
+  }
+  const triggers = evals.triggers ?? [];
+  for (const t of triggers) {
+    const effective = t.should_trigger ?? t.type !== "negative";
+    if (t.type === "negative" && effective) {
+      out.push(
+        finding(
+          "error",
+          `triggers["${t.id}"]: type "negative" requires should_trigger: false`
+        )
+      );
+    }
+  }
+  const negatives = triggers.filter((t) => t.type === "negative").length;
+  if (triggers.length > 0 && negatives < 2) {
+    out.push(
+      finding(
+        "warning",
+        `only ${negatives} negative trigger(s) -- near-miss negatives are what catch over-triggering; aim for at least 2`
+      )
+    );
+  }
+  return out;
+}
+async function initEvals(skillDir, skillName) {
+  const name = skillName ?? basename(skillDir);
+  const path = join(skillDir, "evals", "evals.json");
+  try {
+    await stat(path);
+    throw new Error(`already exists: ${path}`);
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("already exists"))
+      throw err;
+  }
+  const scaffold = {
+    skill_name: name,
+    settings: { runs_per_prompt: 3, trigger_threshold: 0.8 },
+    evals: [
+      {
+        id: 1,
+        prompt: "REPLACE: a realistic user prompt this skill should handle end to end",
+        expected_output: "REPLACE: what a correct result looks like",
+        expectations: [
+          "REPLACE: a checkable statement about the output",
+          "REPLACE: another checkable statement"
+        ]
+      }
+    ],
+    triggers: [
+      {
+        id: "explicit-1",
+        type: "explicit",
+        prompt: `REPLACE: prompt naming ${name} directly`,
+        should_trigger: true
+      },
+      {
+        id: "explicit-2",
+        type: "explicit",
+        prompt: `REPLACE: /${name} slash invocation phrasing`,
+        should_trigger: true
+      },
+      {
+        id: "explicit-3",
+        type: "explicit",
+        prompt: "REPLACE: third explicit phrasing",
+        should_trigger: true
+      },
+      {
+        id: "implicit-1",
+        type: "implicit",
+        prompt: "REPLACE: describes the task without naming the skill",
+        should_trigger: true
+      },
+      {
+        id: "implicit-2",
+        type: "implicit",
+        prompt: "REPLACE: second implicit phrasing",
+        should_trigger: true
+      },
+      {
+        id: "implicit-3",
+        type: "implicit",
+        prompt: "REPLACE: third implicit phrasing",
+        should_trigger: true
+      },
+      {
+        id: "contextual-1",
+        type: "contextual",
+        prompt: "REPLACE: mid-conversation context where the skill should fire",
+        should_trigger: true
+      },
+      {
+        id: "contextual-2",
+        type: "contextual",
+        prompt: "REPLACE: second contextual phrasing",
+        should_trigger: true
+      },
+      {
+        id: "contextual-3",
+        type: "contextual",
+        prompt: "REPLACE: third contextual phrasing",
+        should_trigger: true
+      },
+      {
+        id: "negative-1",
+        type: "negative",
+        prompt: "REPLACE: same-domain near-miss that should NOT trigger",
+        should_trigger: false
+      },
+      {
+        id: "negative-2",
+        type: "negative",
+        prompt: "REPLACE: second same-domain near-miss",
+        should_trigger: false
+      },
+      {
+        id: "negative-3",
+        type: "negative",
+        prompt: "REPLACE: adjacent task that should NOT trigger",
+        should_trigger: false
+      },
+      {
+        id: "negative-4",
+        type: "negative",
+        prompt: "REPLACE: unrelated prompt that should NOT trigger",
+        should_trigger: false
+      }
+    ]
+  };
+  await mkdir(join(skillDir, "evals"), { recursive: true });
+  await writeFile(path, `${JSON.stringify(scaffold, null, 2)}
+`, "utf8");
+  return path;
+}
+
+// src/lint/parse.ts
+import { parse as parseYaml } from "yaml";
+function parseSkillMd(source) {
+  if (!source.startsWith("---")) {
+    return {
+      frontmatter: null,
+      parseError: "SKILL.md must start with YAML frontmatter (---)",
+      rawFrontmatter: "",
+      body: source,
+      bodyStartLine: 1
+    };
+  }
+  const parts = splitN(source, "---", 2);
+  if (parts.length < 3) {
+    return {
+      frontmatter: null,
+      parseError: "SKILL.md frontmatter not properly closed with ---",
+      rawFrontmatter: "",
+      body: source,
+      bodyStartLine: 1
+    };
+  }
+  const rawFrontmatter = parts[1] ?? "";
+  const body = (parts[2] ?? "").replace(/^\r?\n/, "");
+  const bodyStartLine = 3 + (rawFrontmatter.match(/\r?\n/g)?.length ?? 0);
+  const strictErr = strictYamlViolation(rawFrontmatter);
+  if (strictErr) {
+    return {
+      frontmatter: null,
+      parseError: `Invalid YAML in frontmatter: ${strictErr}`,
+      rawFrontmatter,
+      body,
+      bodyStartLine
+    };
+  }
+  let parsed;
+  try {
+    parsed = parseYaml(rawFrontmatter);
+  } catch (err) {
+    return {
+      frontmatter: null,
+      parseError: `Invalid YAML in frontmatter: ${err instanceof Error ? err.message : String(err)}`,
+      rawFrontmatter,
+      body,
+      bodyStartLine
+    };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      frontmatter: null,
+      parseError: "SKILL.md frontmatter must be a YAML mapping",
+      rawFrontmatter,
+      body,
+      bodyStartLine
+    };
+  }
+  return {
+    frontmatter: parsed,
+    parseError: null,
+    rawFrontmatter,
+    body,
+    bodyStartLine
+  };
+}
+function splitN(s, sep, maxsplit) {
+  const out = [];
+  let rest = s;
+  for (let i = 0; i < maxsplit; i++) {
+    const idx = rest.indexOf(sep);
+    if (idx === -1) break;
+    out.push(rest.slice(0, idx));
+    rest = rest.slice(idx + sep.length);
+  }
+  out.push(rest);
+  return out;
+}
+function strictYamlViolation(raw) {
+  const seenKeys = /* @__PURE__ */ new Set();
+  for (const line of raw.split(/\r?\n/)) {
+    const keyMatch = /^([A-Za-z0-9_-]+):(.*)$/.exec(line);
+    if (!keyMatch) continue;
+    const key = keyMatch[1] ?? "";
+    const value = (keyMatch[2] ?? "").trim();
+    if (seenKeys.has(key)) {
+      return `duplicate key "${key}" (strictyaml rejects duplicate keys)`;
+    }
+    seenKeys.add(key);
+    if (value.startsWith("{") || value.startsWith("[")) {
+      return `flow-style collection in "${key}" (strictyaml requires block style)`;
+    }
+    if (value.startsWith("!")) {
+      return `YAML tag in "${key}" (strictyaml rejects tags)`;
+    }
+  }
+  return null;
+}
+
+// src/lint/registry.ts
+var RULES = [
+  // --- Frontmatter (skills-ref parity = error) ---
+  {
+    code: "SC001",
+    alias: "skill-md-missing",
+    severity: "error",
+    fixable: null,
+    summary: "Skill directory must contain SKILL.md"
+  },
+  {
+    code: "SC002",
+    alias: "frontmatter-missing",
+    severity: "error",
+    fixable: null,
+    summary: "SKILL.md must start with YAML frontmatter"
+  },
+  {
+    code: "SC003",
+    alias: "frontmatter-unclosed",
+    severity: "error",
+    fixable: null,
+    summary: "Frontmatter must be closed with ---"
+  },
+  {
+    code: "SC004",
+    alias: "frontmatter-invalid-yaml",
+    severity: "error",
+    fixable: null,
+    summary: "Frontmatter must be valid strict YAML"
+  },
+  {
+    code: "SC005",
+    alias: "frontmatter-not-mapping",
+    severity: "error",
+    fixable: null,
+    summary: "Frontmatter must be a YAML mapping"
+  },
+  {
+    code: "SC006",
+    alias: "name-missing",
+    severity: "error",
+    fixable: null,
+    summary: "name is required"
+  },
+  {
+    code: "SC007",
+    alias: "description-missing",
+    severity: "error",
+    fixable: null,
+    summary: "description is required"
+  },
+  {
+    code: "SC008",
+    alias: "name-empty",
+    severity: "error",
+    fixable: null,
+    summary: "name must be a non-empty string"
+  },
+  {
+    code: "SC009",
+    alias: "name-too-long",
+    severity: "error",
+    lenientSeverity: "warning",
+    fixable: null,
+    summary: "name must be at most 64 characters"
+  },
+  {
+    code: "SC010",
+    alias: "name-not-lowercase",
+    severity: "error",
+    fixable: "safe",
+    summary: "name must be lowercase"
+  },
+  {
+    code: "SC011",
+    alias: "name-edge-hyphen",
+    severity: "error",
+    fixable: "safe",
+    summary: "name cannot start or end with a hyphen"
+  },
+  {
+    code: "SC012",
+    alias: "name-consecutive-hyphens",
+    severity: "error",
+    fixable: "safe",
+    summary: "name cannot contain consecutive hyphens"
+  },
+  {
+    code: "SC013",
+    alias: "name-invalid-chars",
+    severity: "error",
+    fixable: null,
+    summary: "name may only contain letters, digits, and hyphens"
+  },
+  {
+    code: "SC014",
+    alias: "name-dir-mismatch",
+    severity: "error",
+    lenientSeverity: "warning",
+    fixable: null,
+    summary: "directory name must match skill name"
+  },
+  {
+    code: "SC015",
+    alias: "description-empty",
+    severity: "error",
+    fixable: null,
+    summary: "description must be a non-empty string"
+  },
+  {
+    code: "SC016",
+    alias: "description-too-long",
+    severity: "error",
+    fixable: null,
+    summary: "description must be at most 1024 characters"
+  },
+  {
+    code: "SC017",
+    alias: "compatibility-invalid",
+    severity: "error",
+    fixable: null,
+    summary: "compatibility must be a string of at most 500 characters"
+  },
+  {
+    code: "SC018",
+    alias: "unknown-frontmatter-field",
+    severity: "error",
+    lenientSeverity: "warning",
+    fixable: null,
+    summary: "frontmatter field is not in the spec or a known extension"
+  },
+  {
+    code: "SC019",
+    alias: "metadata-not-string-map",
+    severity: "warning",
+    fixable: null,
+    summary: "metadata should be a string-to-string map"
+  },
+  {
+    code: "SC020",
+    alias: "skill-md-lowercase-filename",
+    severity: "warning",
+    fixable: "safe",
+    summary: "skill.md found; canonical filename is SKILL.md"
+  },
+  {
+    code: "SC021",
+    alias: "unquoted-colon-description",
+    severity: "warning",
+    fixable: "safe",
+    summary: "unquoted colon in name/description value breaks lenient parsers"
+  },
+  // --- Structure + references (beyond skills-ref: warning/info only) ---
+  {
+    code: "SC101",
+    alias: "broken-relative-reference",
+    severity: "warning",
+    fixable: null,
+    summary: "referenced bundled file does not exist"
+  },
+  {
+    code: "SC102",
+    alias: "absolute-path-reference",
+    severity: "warning",
+    fixable: null,
+    summary: "body references an absolute path"
+  },
+  {
+    code: "SC103",
+    alias: "deep-reference-chain",
+    severity: "info",
+    fixable: null,
+    summary: "bundled reference chains deeper than one level"
+  },
+  {
+    code: "SC104",
+    alias: "unreferenced-bundled-file",
+    severity: "info",
+    fixable: null,
+    summary: "bundled file never referenced from SKILL.md"
+  },
+  {
+    code: "SC105",
+    alias: "duplicate-skill-name",
+    severity: "warning",
+    fixable: null,
+    summary: "two skills resolve to the same name"
+  },
+  {
+    code: "SC106",
+    alias: "non-utf8-encoding",
+    severity: "warning",
+    fixable: null,
+    summary: "SKILL.md is not valid UTF-8"
+  },
+  {
+    code: "SC107",
+    alias: "hidden-unicode",
+    severity: "warning",
+    fixable: "unsafe",
+    summary: "zero-width or bidi control characters present"
+  },
+  {
+    code: "SC108",
+    alias: "legacy-basedir-placeholder",
+    severity: "warning",
+    fixable: "safe",
+    summary: "deprecated {baseDir} placeholder"
+  },
+  // --- Body (SC2xx) ---
+  {
+    code: "SC201",
+    alias: "body-empty",
+    severity: "warning",
+    fixable: null,
+    summary: "SKILL.md body is empty"
+  },
+  {
+    code: "SC202",
+    alias: "body-too-many-lines",
+    severity: "warning",
+    fixable: null,
+    summary: "body exceeds 500 lines"
+  },
+  {
+    code: "SC203",
+    alias: "body-too-many-tokens",
+    severity: "warning",
+    fixable: null,
+    summary: "body exceeds ~5000 tokens"
+  },
+  // --- Extensions / portability (SC3xx) ---
+  {
+    code: "SC301",
+    alias: "extension-field",
+    severity: "warning",
+    fixable: null,
+    summary: "client extension field (fails strict skills-ref validation)"
+  },
+  {
+    code: "SC302",
+    alias: "extension-invalid-value",
+    severity: "warning",
+    fixable: null,
+    summary: "extension field has an invalid value"
+  },
+  // --- Evals (SC4xx) ---
+  {
+    code: "SC401",
+    alias: "evals-invalid",
+    severity: "error",
+    fixable: null,
+    summary: "evals/evals.json fails schema or semantic validation"
+  },
+  {
+    code: "SC402",
+    alias: "evals-advisory",
+    severity: "warning",
+    fixable: null,
+    summary: "evals/evals.json advisory (coverage gaps)"
+  }
+];
+var byCode = new Map(RULES.map((r) => [r.code, r]));
+var byAlias = new Map(RULES.map((r) => [r.alias, r]));
+function getRule(codeOrAlias) {
+  return byCode.get(codeOrAlias.toUpperCase()) ?? byAlias.get(codeOrAlias.toLowerCase());
+}
+
+// src/extensions.ts
+var KNOWN_EXTENSIONS = {
+  when_to_use: { type: "string", runtimes: ["claude-code"] },
+  "argument-hint": { type: "string", runtimes: ["claude-code", "copilot"] },
+  arguments: { type: "string-or-array", runtimes: ["claude-code"] },
+  "disable-model-invocation": {
+    type: "boolean",
+    runtimes: ["claude-code", "cursor", "copilot"]
+  },
+  "user-invocable": { type: "boolean", runtimes: ["claude-code", "copilot"] },
+  "disallowed-tools": { type: "string-or-array", runtimes: ["claude-code"] },
+  model: { type: "string", runtimes: ["claude-code"] },
+  effort: {
+    type: "enum",
+    values: ["low", "medium", "high", "xhigh", "max"],
+    runtimes: ["claude-code"]
+  },
+  context: {
+    type: "enum",
+    values: ["fork"],
+    runtimes: ["claude-code", "copilot"]
+  },
+  agent: { type: "string", runtimes: ["claude-code"] },
+  hooks: { type: "object", runtimes: ["claude-code"] },
+  paths: { type: "string-or-array", runtimes: ["claude-code", "cursor"] },
+  globs: {
+    type: "string-or-array",
+    runtimes: ["cursor"],
+    deprecated: "Cursor legacy; use `paths`"
+  },
+  shell: {
+    type: "enum",
+    values: ["bash", "powershell"],
+    runtimes: ["claude-code"]
+  },
+  "display-name": { type: "string", runtimes: ["claude-code"] },
+  "default-enabled": { type: "boolean", runtimes: ["claude-code"] },
+  fallback: { type: "string", runtimes: ["claude-code"] },
+  version: { type: "string", runtimes: ["claude-code"] }
+};
+var SPEC_FIELDS = /* @__PURE__ */ new Set([
+  "name",
+  "description",
+  "license",
+  "allowed-tools",
+  "metadata",
+  "compatibility"
+]);
+function validateExtensionValue(key, value) {
+  const spec = KNOWN_EXTENSIONS[key];
+  if (!spec) return null;
+  switch (spec.type) {
+    case "string":
+      return typeof value === "string" ? null : `\`${key}\` must be a string`;
+    case "boolean":
+      return typeof value === "boolean" ? null : `\`${key}\` must be a boolean`;
+    case "string-or-array":
+      if (typeof value === "string") return null;
+      if (Array.isArray(value) && value.every((v) => typeof v === "string"))
+        return null;
+      return `\`${key}\` must be a string or an array of strings`;
+    case "object":
+      return value !== null && typeof value === "object" && !Array.isArray(value) ? null : `\`${key}\` must be a mapping`;
+    case "enum":
+      return typeof value === "string" && spec.values?.includes(value) ? null : `\`${key}\` must be one of: ${spec.values?.join(", ")}`;
+  }
+}
+
+// src/lint/index.ts
+import { readdir, readFile as readFile2 } from "fs/promises";
+import { basename as basename2, join as join2, relative, resolve } from "path";
+
+// src/lint/rules.ts
+var NAME_MAX = 64;
+var DESCRIPTION_MAX = 1024;
+var COMPATIBILITY_MAX = 500;
+var BODY_LINE_LIMIT = 500;
+var BODY_TOKEN_LIMIT = 5e3;
+var CHARS_PER_TOKEN = 4;
+var NAME_CHARS_RE = /^[\p{L}\p{N}-]*$/u;
+var HIDDEN_UNICODE_RE = /[​-‍⁠‪-‮⁦-⁩]/;
+function make(code, message, line, suggestion) {
+  const meta = getRule(code);
+  if (!meta) throw new Error(`unknown rule code ${code}`);
+  return {
+    code: meta.code,
+    alias: meta.alias,
+    severity: meta.severity,
+    message,
+    file: "SKILL.md",
+    ...line !== void 0 ? { line } : {},
+    ...suggestion !== void 0 ? { suggestion } : {}
+  };
+}
+function applyProfile(findings, profile) {
+  if (profile !== "lenient") return findings;
+  return findings.map((f) => {
+    const meta = getRule(f.code);
+    if (meta?.lenientSeverity && meta.lenientSeverity !== f.severity) {
+      return { ...f, severity: meta.lenientSeverity };
+    }
+    return f;
+  });
+}
+function runRules(ctx) {
+  const { parsed, dirName } = ctx;
+  const findings = [];
+  scanUnquotedColons(parsed, findings);
+  if (parsed.parseError !== null || parsed.frontmatter === null) {
+    const msg = parsed.parseError ?? "SKILL.md frontmatter unparseable";
+    let code = "SC004";
+    if (msg.startsWith("SKILL.md must start with")) code = "SC002";
+    else if (msg.includes("not properly closed")) code = "SC003";
+    else if (msg.includes("must be a YAML mapping")) code = "SC005";
+    findings.push(make(code, msg, 1));
+    return applyProfile(findings, ctx.profile);
+  }
+  const fm = parsed.frontmatter;
+  if (!("name" in fm)) {
+    findings.push(make("SC006", "Missing required field in frontmatter: name"));
+  } else if (typeof fm.name !== "string" || fm.name.trim().length === 0) {
+    findings.push(make("SC008", "Field 'name' must be a non-empty string"));
+  } else {
+    const name = fm.name.trim().normalize("NFKC");
+    if (name.length > NAME_MAX) {
+      findings.push(
+        make(
+          "SC009",
+          `Skill name '${name}' exceeds ${NAME_MAX} character limit (${name.length} chars)`
+        )
+      );
+    }
+    if (name !== name.toLowerCase()) {
+      findings.push(
+        make(
+          "SC010",
+          `Skill name '${name}' must be lowercase`,
+          void 0,
+          `rename to '${name.toLowerCase()}'`
+        )
+      );
+    }
+    if (name.startsWith("-") || name.endsWith("-")) {
+      findings.push(
+        make("SC011", "Skill name cannot start or end with a hyphen")
+      );
+    }
+    if (name.includes("--")) {
+      findings.push(
+        make("SC012", "Skill name cannot contain consecutive hyphens")
+      );
+    }
+    if (!NAME_CHARS_RE.test(name)) {
+      findings.push(
+        make(
+          "SC013",
+          `Skill name '${name}' contains invalid characters. Only letters, digits, and hyphens are allowed.`
+        )
+      );
+    }
+    const normalizedDir = dirName.normalize("NFKC");
+    if (name !== normalizedDir) {
+      findings.push(
+        make(
+          "SC014",
+          `Directory name '${normalizedDir}' must match skill name '${name}'`
+        )
+      );
+    }
+  }
+  if (!("description" in fm)) {
+    findings.push(
+      make("SC007", "Missing required field in frontmatter: description")
+    );
+  } else if (typeof fm.description !== "string" || fm.description.trim().length === 0) {
+    findings.push(
+      make("SC015", "Field 'description' must be a non-empty string")
+    );
+  } else if (fm.description.length > DESCRIPTION_MAX) {
+    findings.push(
+      make(
+        "SC016",
+        `Description exceeds ${DESCRIPTION_MAX} character limit (${fm.description.length} chars)`
+      )
+    );
+  }
+  if (fm.compatibility !== void 0) {
+    if (typeof fm.compatibility !== "string") {
+      findings.push(make("SC017", "Field 'compatibility' must be a string"));
+    } else if (fm.compatibility.length > COMPATIBILITY_MAX) {
+      findings.push(
+        make(
+          "SC017",
+          `Compatibility exceeds ${COMPATIBILITY_MAX} character limit (${fm.compatibility.length} chars)`
+        )
+      );
+    }
+  }
+  if (fm.metadata !== void 0) {
+    const md = fm.metadata;
+    const isStringMap = md !== null && typeof md === "object" && !Array.isArray(md) && Object.values(md).every(
+      (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean"
+    );
+    if (!isStringMap) {
+      findings.push(
+        make(
+          "SC019",
+          "`metadata` should be a map of string keys to string values"
+        )
+      );
+    }
+  }
+  if (fm["allowed-tools"] !== void 0 && typeof fm["allowed-tools"] !== "string") {
+    if (Array.isArray(fm["allowed-tools"]) && fm["allowed-tools"].every((v) => typeof v === "string")) {
+      findings.push(
+        make(
+          "SC302",
+          "`allowed-tools` is an array; the spec defines it as a space-separated string (arrays are a client extension)"
+        )
+      );
+    } else {
+      findings.push(
+        make("SC302", "`allowed-tools` must be a space-separated string")
+      );
+    }
+  }
+  const extras = [];
+  for (const key of Object.keys(fm)) {
+    if (SPEC_FIELDS.has(key)) continue;
+    if (key in KNOWN_EXTENSIONS) {
+      const ext = KNOWN_EXTENSIONS[key];
+      findings.push(
+        make(
+          "SC301",
+          `\`${key}\` is a client extension (${ext?.runtimes.join(", ")}), not in the Agent Skills spec -- fails strict skills-ref validation${ext?.deprecated ? `; ${ext.deprecated}` : ""}`
+        )
+      );
+      const valueErr = validateExtensionValue(key, fm[key]);
+      if (valueErr) findings.push(make("SC302", valueErr));
+    } else {
+      extras.push(key);
+    }
+  }
+  if (extras.length > 0) {
+    const allowed = [...SPEC_FIELDS].sort().join(", ");
+    findings.push(
+      // skills-ref verbatim: period before "Only", "are allowed."
+      make(
+        "SC018",
+        `Unexpected fields in frontmatter: ${extras.sort().join(", ")}. Only ${allowed} are allowed.`
+      )
+    );
+  }
+  const body = parsed.body;
+  if (body.trim().length === 0) {
+    findings.push(
+      make(
+        "SC201",
+        "SKILL.md body is empty; the skill provides no instructions"
+      )
+    );
+  } else {
+    const bodyLines = body.split(/\r?\n/).length;
+    if (bodyLines > BODY_LINE_LIMIT) {
+      findings.push(
+        make(
+          "SC202",
+          `body is ${bodyLines} lines; spec recommends under ${BODY_LINE_LIMIT}`
+        )
+      );
+    }
+    const approxTokens = Math.round(body.length / CHARS_PER_TOKEN);
+    if (approxTokens > BODY_TOKEN_LIMIT) {
+      findings.push(
+        make(
+          "SC203",
+          `body is ~${approxTokens} tokens; spec recommends under ${BODY_TOKEN_LIMIT} (move detail to references/)`
+        )
+      );
+    }
+  }
+  findings.push(...referenceChecks(parsed, ctx.bundledFiles ?? []));
+  if (HIDDEN_UNICODE_RE.test(body) || HIDDEN_UNICODE_RE.test(parsed.rawFrontmatter)) {
+    findings.push(
+      make(
+        "SC107",
+        "SKILL.md contains zero-width or bidi control characters (Trojan-Source risk)"
+      )
+    );
+  }
+  if (body.includes("{baseDir}")) {
+    findings.push(
+      make(
+        "SC108",
+        "deprecated `{baseDir}` placeholder found",
+        void 0,
+        "use relative paths from the skill root instead"
+      )
+    );
+  }
+  return applyProfile(findings, ctx.profile);
+}
+function scanUnquotedColons(parsed, findings) {
+  for (const line of parsed.rawFrontmatter.split(/\r?\n/)) {
+    const m = /^(name|description):\s+(?!['"|>])(.*: .*)$/.exec(line);
+    if (m) {
+      findings.push(
+        make(
+          "SC021",
+          `unquoted ': ' inside \`${m[1]}\` value -- lenient YAML parsers in some clients truncate here`,
+          void 0,
+          `quote the value: ${m[1]}: "${(m[2] ?? "").trim()}"`
+        )
+      );
+    }
+  }
+}
+function referenceChecks(parsed, bundledFiles) {
+  const findings = [];
+  const body = parsed.body;
+  const bundled = new Set(bundledFiles.map((f) => f.replace(/\\/g, "/")));
+  const referenced = /* @__PURE__ */ new Set();
+  for (const m of body.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+    const target = (m[1] ?? "").split(/[#?]/)[0]?.trim() ?? "";
+    if (target) referenced.add(target);
+  }
+  for (const m of body.matchAll(
+    /`((?:scripts|references|assets)\/[^\s`]+)`/g
+  )) {
+    referenced.add((m[1] ?? "").trim());
+  }
+  for (const target of referenced) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target) || target.startsWith("mailto:"))
+      continue;
+    if (target.startsWith("#")) continue;
+    if (target.includes("${") || target.includes("{{")) continue;
+    if (/^(\/|[A-Za-z]:[\\/]|~\/)/.test(target)) {
+      findings.push(
+        make(
+          "SC102",
+          `absolute path reference \`${target}\` -- skills must use paths relative to the skill root`
+        )
+      );
+      continue;
+    }
+    const normalized = target.replace(/^\.\//, "").replace(/\\/g, "/");
+    if (bundled.size > 0 && !bundled.has(normalized)) {
+      findings.push(
+        make(
+          "SC101",
+          `referenced file \`${target}\` does not exist in the skill directory`
+        )
+      );
+    }
+  }
+  for (const f of bundled) {
+    if (!/^(scripts|references|assets)\//.test(f)) continue;
+    const mentioned = body.includes(f) || referenced.has(f);
+    if (!mentioned) {
+      findings.push({
+        code: "SC104",
+        alias: "unreferenced-bundled-file",
+        severity: "info",
+        message: `bundled file \`${f}\` is never referenced from SKILL.md`,
+        file: f
+      });
+    }
+  }
+  return findings;
+}
+
+// src/lint/index.ts
+async function lintSkillDir(dir, options = {}) {
+  const skillDir = resolve(dir);
+  const dirName = basename2(skillDir);
+  let entries = [];
+  try {
+    entries = (await readdir(skillDir)).map(String);
+  } catch {
+  }
+  let source = null;
+  let usedLowercase = false;
+  for (const candidate of ["SKILL.md", "skill.md"]) {
+    if (!entries.includes(candidate)) continue;
+    try {
+      source = await readFile2(join2(skillDir, candidate));
+      usedLowercase = candidate === "skill.md";
+      break;
+    } catch {
+    }
+  }
+  if (source === null) {
+    return summarize(skillDir, null, [
+      {
+        code: "SC001",
+        alias: "skill-md-missing",
+        severity: "error",
+        message: "Missing required file: SKILL.md",
+        file: "SKILL.md"
+      }
+    ]);
+  }
+  const findings = [];
+  const text = source.toString("utf8");
+  if (text.includes("\uFFFD")) {
+    findings.push({
+      code: "SC106",
+      alias: "non-utf8-encoding",
+      severity: "warning",
+      message: "SKILL.md is not valid UTF-8 (replacement characters found on decode)",
+      file: "SKILL.md"
+    });
+  }
+  if (usedLowercase) {
+    findings.push({
+      code: "SC020",
+      alias: "skill-md-lowercase-filename",
+      severity: "warning",
+      message: "found skill.md; the canonical filename is SKILL.md (uppercase)",
+      file: "skill.md"
+    });
+  }
+  const parsed = parseSkillMd(text.replace(/^/, ""));
+  const bundledFiles = await listBundledFiles(skillDir);
+  findings.push(
+    ...runRules({
+      parsed,
+      dirName,
+      profile: options.profile ?? "strict",
+      bundledFiles
+    })
+  );
+  const skillName = parsed.frontmatter && typeof parsed.frontmatter.name === "string" ? parsed.frontmatter.name.trim().normalize("NFKC") : null;
+  return summarize(skillDir, skillName, applyOverrides(findings, options));
+}
+function crossSkillFindings(results) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    if (!r.skillName) continue;
+    const list = byName.get(r.skillName) ?? [];
+    list.push(r);
+    byName.set(r.skillName, list);
+  }
+  for (const [name, list] of byName) {
+    if (list.length < 2) continue;
+    for (const r of list) {
+      r.findings.push({
+        code: "SC105",
+        alias: "duplicate-skill-name",
+        severity: "warning",
+        message: `skill name '${name}' is used by ${list.length} skills in this tree (client-guide: collisions warn; project scope wins)`,
+        file: "SKILL.md"
+      });
+      recount(r);
+    }
+  }
+}
+function applyOverrides(findings, options) {
+  const overrides = options.ruleOverrides;
+  if (!overrides) return findings;
+  const resolved = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(overrides)) {
+    const meta = getRule(key);
+    if (!meta) continue;
+    resolved.set(meta.code, value === "warn" ? "warning" : value);
+  }
+  const out = [];
+  for (const f of findings) {
+    const o = resolved.get(f.code);
+    if (o === "off") continue;
+    out.push(o ? { ...f, severity: o } : f);
+  }
+  return out;
+}
+async function listBundledFiles(skillDir) {
+  const files = [];
+  async function walk(dir, depth) {
+    if (depth > 4) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const full = join2(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, depth + 1);
+      } else {
+        files.push(relative(skillDir, full).replace(/\\/g, "/"));
+      }
+    }
+  }
+  await walk(skillDir, 0);
+  return files;
+}
+function summarize(skillDir, skillName, findings) {
+  const result = {
+    skillDir,
+    skillName,
+    findings,
+    errorCount: 0,
+    warningCount: 0,
+    infoCount: 0
+  };
+  recount(result);
+  return result;
+}
+function recount(r) {
+  r.errorCount = r.findings.filter((f) => f.severity === "error").length;
+  r.warningCount = r.findings.filter((f) => f.severity === "warning").length;
+  r.infoCount = r.findings.filter((f) => f.severity === "info").length;
+}
+
+// src/output/sarif.ts
+import { relative as relative2 } from "path";
+var LEVEL = {
+  error: "error",
+  warning: "warning",
+  info: "note"
+};
+function toSarif(results, version, cwd = process.cwd()) {
+  const sarif = {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "skillcheck",
+            informationUri: "https://github.com/Sagargupta16/skillcheck",
+            version,
+            rules: RULES.map((r) => ({
+              id: r.code,
+              name: r.alias,
+              shortDescription: { text: r.summary.slice(0, 255) },
+              helpUri: `https://github.com/Sagargupta16/skillcheck/blob/main/docs/rules.md#${r.code.toLowerCase()}`,
+              defaultConfiguration: { level: LEVEL[r.severity] }
+            }))
+          }
+        },
+        results: results.flatMap(
+          (result) => result.findings.map((f) => ({
+            ruleId: f.code,
+            level: LEVEL[f.severity],
+            message: { text: f.message },
+            locations: [
+              {
+                physicalLocation: {
+                  artifactLocation: {
+                    uri: relative2(cwd, `${result.skillDir}/${f.file}`).replace(
+                      /\\/g,
+                      "/"
+                    )
+                  },
+                  region: { startLine: f.line ?? 1, startColumn: 1 }
+                }
+              }
+            ]
+          }))
+        )
+      }
+    ]
+  };
+  return JSON.stringify(sarif, null, 2);
+}
+
+export {
+  evalsFileSchema,
+  checkEvals,
+  initEvals,
+  parseSkillMd,
+  RULES,
+  getRule,
+  KNOWN_EXTENSIONS,
+  SPEC_FIELDS,
+  lintSkillDir,
+  crossSkillFindings,
+  toSarif
+};