@cydm/pie 1.0.5 → 1.0.7

package/dist/builtin/skills/skill-creator/scripts/quick_validate.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { access } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { parseSkillFile, validateFrontmatter } from "./skill_metadata.mjs";
+
+export async function validateSkill(skillPath) {
+  const resolved = path.resolve(skillPath);
+  const skillMdPath = path.join(resolved, "SKILL.md");
+
+  try {
+    await access(skillMdPath);
+  } catch {
+    return { valid: false, message: "SKILL.md not found" };
+  }
+
+  try {
+    const { frontmatter } = await parseSkillFile(resolved);
+    return validateFrontmatter(frontmatter);
+  } catch (error) {
+    return { valid: false, message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+async function main(argv = process.argv) {
+  if (argv.length !== 3) {
+    process.stderr.write("Usage: node quick_validate.mjs <skill_directory>\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = await validateSkill(argv[2]);
+  process.stdout.write(`${result.message}\n`);
+  process.exitCode = result.valid ? 0 : 1;
+}
+
+const entryPath = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === entryPath) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/dist/builtin/skills/skill-creator/scripts/run_eval.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSkillFile, resolveSkillPath } from "./skill_metadata.mjs";
+import { callPieText, findProjectRoot, uuidFragment } from "./pie_runner.mjs";
+
+export async function runSingleQuery(query, skillName, skillDescription, timeout, projectRoot, model) {
+  const cleanName = `${skillName}-skill-${uuidFragment()}`.toLowerCase().replace(/[^a-z0-9-_]/g, "-");
+  const triggerToken = `PIE_SKILL_TRIGGERED_${uuidFragment().toUpperCase()}`;
+  const tempProject = await mkdtemp(path.join(os.tmpdir(), "pie-skill-eval-"));
+  const skillDir = path.join(tempProject, ".pie", "skills", cleanName);
+  await mkdir(skillDir, { recursive: true });
+  const instrumentedDescription = `${skillDescription} For evaluation only: if you decide this skill applies to the user's request, append this exact marker on its own final line: ${triggerToken}`;
+  await writeFile(
+    path.join(skillDir, "SKILL.md"),
+    `---\nname: ${cleanName}\ndescription: ${instrumentedDescription}\n---\n\n# ${skillName}\n\nThis temporary skill exists only to evaluate whether the description triggers in Pie.\n`,
+    "utf8",
+  );
+
+  try {
+    const response = await callPieText(query, {
+      cwd: tempProject,
+      timeout: timeout * 1000,
+      sessionId: `skill-eval-${uuidFragment()}`,
+    });
+    return response.includes(triggerToken);
+  } finally {
+    await rm(tempProject, { recursive: true, force: true });
+  }
+}
+
+export async function runEval(evalSet, skillName, description, numWorkers, timeout, projectRoot, runsPerQuery = 1, triggerThreshold = 0.5, model = null) {
+  const tasks = [];
+  for (const item of evalSet) {
+    for (let runIdx = 0; runIdx < runsPerQuery; runIdx += 1) {
+      tasks.push({ item, runIdx });
+    }
+  }
+
+  const queryTriggers = new Map();
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < tasks.length) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+      const { item } = tasks[currentIndex];
+      const query = item.query;
+      if (!queryTriggers.has(query)) {
+        queryTriggers.set(query, { item, triggers: [] });
+      }
+      try {
+        const result = await runSingleQuery(query, skillName, description, timeout, projectRoot, model);
+        queryTriggers.get(query).triggers.push(!!result);
+      } catch (error) {
+        process.stderr.write(`Warning: query failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        queryTriggers.get(query).triggers.push(false);
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.max(1, numWorkers) }, () => worker()));
+
+  const results = [];
+  for (const [query, payload] of queryTriggers.entries()) {
+    const { item, triggers } = payload;
+    const triggerCount = triggers.filter(Boolean).length;
+    const triggerRate = triggers.length > 0 ? triggerCount / triggers.length : 0;
+    const didPass = item.should_trigger ? triggerRate >= triggerThreshold : triggerRate < triggerThreshold;
+    results.push({
+      query,
+      should_trigger: item.should_trigger,
+      trigger_rate: triggerRate,
+      triggers: triggerCount,
+      runs: triggers.length,
+      pass: didPass,
+    });
+  }
+
+  const passed = results.filter((item) => item.pass).length;
+  return {
+    skill_name: skillName,
+    description,
+    results,
+    summary: {
+      total: results.length,
+      passed,
+      failed: results.length - passed,
+    },
+  };
+}
+
+async function main(argv = process.argv) {
+  const args = parseArgs(argv.slice(2));
+  if (args.help || args.h) {
+    printHelp();
+    return;
+  }
+  if (!args["skill-path"] || !args["eval-set"]) {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+  const evalSet = JSON.parse(await readFile(args["eval-set"], "utf8"));
+  const skillPath = resolveSkillPath(args["skill-path"]);
+  const { name } = await parseSkillFile(skillPath);
+  const description = args.description ?? (await parseSkillFile(skillPath)).description;
+
+  const output = await runEval(
+    evalSet,
+    name,
+    description,
+    Number(args["num-workers"] ?? 10),
+    Number(args.timeout ?? 30),
+    findProjectRoot(),
+    Number(args["runs-per-query"] ?? 1),
+    Number(args["trigger-threshold"] ?? 0.5),
+    args.model ?? null,
+  );
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      "Usage: node run_eval.mjs --skill-path <skill-dir|SKILL.md> --eval-set <eval-set.json> [options]",
+      "",
+      "Options:",
+      "  --description <text>         Override the skill description for evaluation",
+      "  --num-workers <n>            Number of concurrent workers (default: 10)",
+      "  --timeout <seconds>          Timeout per query (default: 30)",
+      "  --runs-per-query <n>         Number of runs per query (default: 1)",
+      "  --trigger-threshold <ratio>  Pass threshold for positive prompts (default: 0.5)",
+      "  --model <id>                 Optional model override",
+      "  -h, --help                   Show this help",
+      "",
+      "The --skill-path argument may point to either the skill directory or its SKILL.md file.",
+      "",
+    ].join("\n"),
+  );
+}
+
+function parseArgs(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const value = args[i];
+    if (!value.startsWith("--")) continue;
+    const key = value.slice(2);
+    const next = args[i + 1];
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    i += 1;
+  }
+  return flags;
+}
+
+const entryPath = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === entryPath) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/dist/builtin/skills/skill-creator/scripts/run_loop.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+
+import os from "node:os";
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { generateHtml } from "./generate_report.mjs";
+import { improveDescription } from "./improve_description.mjs";
+import { findProjectRoot, openInBrowser } from "./claude_cli.mjs";
+import { runEval } from "./run_eval.mjs";
+import { parseSkillFile, resolveSkillPath } from "./skill_metadata.mjs";
+
+function seededShuffle(values, seed) {
+  let state = seed >>> 0;
+  const random = () => {
+    state = (1664525 * state + 1013904223) >>> 0;
+    return state / 0x100000000;
+  };
+  const items = [...values];
+  for (let i = items.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(random() * (i + 1));
+    [items[i], items[j]] = [items[j], items[i]];
+  }
+  return items;
+}
+
+export function splitEvalSet(evalSet, holdout, seed = 42) {
+  const trigger = seededShuffle(evalSet.filter((item) => item.should_trigger), seed);
+  const noTrigger = seededShuffle(evalSet.filter((item) => !item.should_trigger), seed + 1);
+  const triggerTestCount = Math.max(1, Math.floor(trigger.length * holdout));
+  const noTriggerTestCount = Math.max(1, Math.floor(noTrigger.length * holdout));
+  return {
+    trainSet: [...trigger.slice(triggerTestCount), ...noTrigger.slice(noTriggerTestCount)],
+    testSet: [...trigger.slice(0, triggerTestCount), ...noTrigger.slice(0, noTriggerTestCount)],
+  };
+}
+
+function summarizeResults(results) {
+  const passed = results.filter((item) => item.pass).length;
+  return { passed, failed: results.length - passed, total: results.length };
+}
+
+function aggregateRuns(results) {
+  let correct = 0;
+  let total = 0;
+  for (const result of results) {
+    const runs = Number(result.runs ?? 0);
+    const triggers = Number(result.triggers ?? 0);
+    total += runs;
+    correct += result.should_trigger ? triggers : runs - triggers;
+  }
+  return { correct, total };
+}
+
+function printEvalStats(label, results, elapsedSeconds = 0) {
+  const pos = results.filter((item) => item.should_trigger);
+  const neg = results.filter((item) => !item.should_trigger);
+  const tp = pos.reduce((sum, item) => sum + Number(item.triggers ?? 0), 0);
+  const posRuns = pos.reduce((sum, item) => sum + Number(item.runs ?? 0), 0);
+  const fn = posRuns - tp;
+  const fp = neg.reduce((sum, item) => sum + Number(item.triggers ?? 0), 0);
+  const negRuns = neg.reduce((sum, item) => sum + Number(item.runs ?? 0), 0);
+  const tn = negRuns - fp;
+  const total = tp + tn + fp + fn;
+  const precision = (tp + fp) > 0 ? tp / (tp + fp) : 1;
+  const recall = (tp + fn) > 0 ? tp / (tp + fn) : 1;
+  const accuracy = total > 0 ? (tp + tn) / total : 0;
+  process.stderr.write(`${label}: ${tp + tn}/${total} correct, precision=${Math.round(precision * 100)}% recall=${Math.round(recall * 100)}% accuracy=${Math.round(accuracy * 100)}% (${elapsedSeconds.toFixed(1)}s)\n`);
+  for (const result of results) {
+    process.stderr.write(`  [${result.pass ? "PASS" : "FAIL"}] rate=${result.triggers}/${result.runs} expected=${result.should_trigger}: ${String(result.query).slice(0, 60)}\n`);
+  }
+}
+
+export async function runLoop({
+  evalSet,
+  skillPath,
+  descriptionOverride = null,
+  numWorkers = 10,
+  timeout = 30,
+  maxIterations = 5,
+  runsPerQuery = 3,
+  triggerThreshold = 0.5,
+  holdout = 0.4,
+  model,
+  verbose = false,
+  liveReportPath = null,
+  logDir = null,
+}) {
+  const { name, description: originalDescription, content } = await parseSkillFile(skillPath);
+  let currentDescription = descriptionOverride ?? originalDescription;
+  const { trainSet, testSet } = holdout > 0 ? splitEvalSet(evalSet, holdout) : { trainSet: evalSet, testSet: [] };
+  const history = [];
+  let exitReason = "unknown";
+
+  for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+    if (verbose) {
+      process.stderr.write(`\n${"=".repeat(60)}\nIteration ${iteration}/${maxIterations}\nDescription: ${currentDescription}\n${"=".repeat(60)}\n`);
+    }
+    const allQueries = [...trainSet, ...testSet];
+    const evalStart = Date.now();
+    const allResults = await runEval(
+      allQueries,
+      name,
+      currentDescription,
+      numWorkers,
+      timeout,
+      findProjectRoot(),
+      runsPerQuery,
+      triggerThreshold,
+      model ?? null,
+    );
+    const evalElapsed = (Date.now() - evalStart) / 1000;
+    const trainQuerySet = new Set(trainSet.map((item) => item.query));
+    const trainResultList = allResults.results.filter((item) => trainQuerySet.has(item.query));
+    const testResultList = allResults.results.filter((item) => !trainQuerySet.has(item.query));
+    const trainSummary = summarizeResults(trainResultList);
+    const testSummary = testSet.length > 0 ? summarizeResults(testResultList) : null;
+    history.push({
+      iteration,
+      description: currentDescription,
+      train_passed: trainSummary.passed,
+      train_failed: trainSummary.failed,
+      train_total: trainSummary.total,
+      train_results: trainResultList,
+      test_passed: testSummary?.passed ?? null,
+      test_failed: testSummary?.failed ?? null,
+      test_total: testSummary?.total ?? null,
+      test_results: testSummary ? testResultList : null,
+      passed: trainSummary.passed,
+      failed: trainSummary.failed,
+      total: trainSummary.total,
+      results: trainResultList,
+    });
+    if (liveReportPath) {
+      const partialOutput = {
+        original_description: originalDescription,
+        best_description: currentDescription,
+        best_score: "in progress",
+        iterations_run: history.length,
+        holdout,
+        train_size: trainSet.length,
+        test_size: testSet.length,
+        history,
+      };
+      await writeFile(liveReportPath, generateHtml(partialOutput, { autoRefresh: true, skillName: name }));
+    }
+    if (verbose) {
+      printEvalStats("Train", trainResultList, evalElapsed);
+      if (testSummary) {
+        printEvalStats("Test ", testResultList, 0);
+      }
+    }
+    if (trainSummary.failed === 0) {
+      exitReason = `all_passed (iteration ${iteration})`;
+      break;
+    }
+    if (iteration === maxIterations) {
+      exitReason = `max_iterations (${maxIterations})`;
+      break;
+    }
+    const blindedHistory = history.map((item) => Object.fromEntries(Object.entries(item).filter(([key]) => !key.startsWith("test_"))));
+    currentDescription = await improveDescription({
+      skillName: name,
+      skillContent: content,
+      currentDescription,
+      evalResults: { results: trainResultList, summary: trainSummary },
+      history: blindedHistory,
+      model,
+      logDir,
+      iteration,
+    });
+  }
+
+  const best = testSet.length > 0
+    ? history.reduce((bestItem, item) => ((item.test_passed ?? -1) > (bestItem?.test_passed ?? -1) ? item : bestItem), null)
+    : history.reduce((bestItem, item) => ((item.train_passed ?? -1) > (bestItem?.train_passed ?? -1) ? item : bestItem), null);
+  const bestScore = testSet.length > 0 ? `${best?.test_passed}/${best?.test_total}` : `${best?.train_passed}/${best?.train_total}`;
+  return {
+    exit_reason: exitReason,
+    original_description: originalDescription,
+    best_description: best?.description ?? currentDescription,
+    best_score: bestScore,
+    best_train_score: `${best?.train_passed ?? 0}/${best?.train_total ?? 0}`,
+    best_test_score: testSet.length > 0 ? `${best?.test_passed ?? 0}/${best?.test_total ?? 0}` : null,
+    final_description: currentDescription,
+    iterations_run: history.length,
+    holdout,
+    train_size: trainSet.length,
+    test_size: testSet.length,
+    history,
+  };
+}
+
+function parseArgs(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const value = args[i];
+    if (!value.startsWith("--")) continue;
+    const key = value.slice(2);
+    const next = args[i + 1];
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    i += 1;
+  }
+  return flags;
+}
+
+async function main(argv = process.argv) {
+  const args = parseArgs(argv.slice(2));
+  if (args.help || args.h) {
+    printHelp();
+    return;
+  }
+  if (!args["skill-path"] || !args["eval-set"]) {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+  const evalSet = JSON.parse(await readFile(args["eval-set"], "utf8"));
+  const skillPath = resolveSkillPath(args["skill-path"]);
+  const { name } = await parseSkillFile(skillPath);
+  const reportMode = args.report ?? "auto";
+  let liveReportPath = null;
+  if (reportMode !== "none") {
+    liveReportPath = reportMode === "auto"
+      ? path.join(os.tmpdir(), `skill_description_report_${path.basename(skillPath)}_${Date.now()}.html`)
+      : path.resolve(reportMode);
+    await writeFile(liveReportPath, "<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>");
+    await openInBrowser(liveReportPath);
+  }
+  const resultsDir = args["results-dir"] ? path.join(path.resolve(args["results-dir"]), new Date().toISOString().replaceAll(":", "-")) : null;
+  if (resultsDir) {
+    await mkdir(resultsDir, { recursive: true });
+  }
+  const output = await runLoop({
+    evalSet,
+    skillPath,
+    descriptionOverride: args.description ?? null,
+    numWorkers: Number(args["num-workers"] ?? 10),
+    timeout: Number(args.timeout ?? 30),
+    maxIterations: Number(args["max-iterations"] ?? 5),
+    runsPerQuery: Number(args["runs-per-query"] ?? 3),
+    triggerThreshold: Number(args["trigger-threshold"] ?? 0.5),
+    holdout: Number(args.holdout ?? 0.4),
+    model: args.model,
+    verbose: Boolean(args.verbose),
+    liveReportPath,
+    logDir: resultsDir ? path.join(resultsDir, "logs") : null,
+  });
+  const outputJson = `${JSON.stringify(output, null, 2)}\n`;
+  process.stdout.write(outputJson);
+  if (resultsDir) {
+    await writeFile(path.join(resultsDir, "results.json"), outputJson);
+  }
+  if (liveReportPath) {
+    await writeFile(liveReportPath, generateHtml(output, { autoRefresh: false, skillName: name }));
+  }
+  if (resultsDir) {
+    await writeFile(path.join(resultsDir, "report.html"), `${generateHtml(output, { autoRefresh: false, skillName: name })}\n`);
+  }
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      "Usage: node run_loop.mjs --skill-path <skill-dir|SKILL.md> --eval-set <eval-set.json> [options]",
+      "",
+      "Options:",
+      "  --description <text>         Override the initial description",
+      "  --num-workers <n>            Number of concurrent workers (default: 10)",
+      "  --timeout <seconds>          Timeout per query (default: 30)",
+      "  --max-iterations <n>         Maximum optimization iterations (default: 5)",
+      "  --runs-per-query <n>         Number of runs per query (default: 3)",
+      "  --trigger-threshold <ratio>  Pass threshold for positive prompts (default: 0.5)",
+      "  --holdout <ratio>            Fraction reserved for test set (default: 0.4)",
+      "  --report <auto|none|path>    Live report mode or output path (default: auto)",
+      "  --results-dir <dir>          Directory for loop artifacts",
+      "  --model <id>                 Optional model override",
+      "  --verbose                    Print per-iteration stats",
+      "  -h, --help                   Show this help",
+      "",
+      "The --skill-path argument may point to either the skill directory or its SKILL.md file.",
+      "",
+    ].join("\n"),
+  );
+}
+
+const entryPath = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === entryPath) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/dist/builtin/skills/skill-creator/scripts/skill_metadata.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+const ALLOWED_PROPERTIES = new Set([
+  "name",
+  "description",
+  "license",
+  "allowed-tools",
+  "metadata",
+  "compatibility",
+]);
+
+export async function readSkillMarkdown(skillPath) {
+  const skillMdPath = path.join(skillPath, "SKILL.md");
+  return readFile(skillMdPath, "utf8");
+}
+
+export function resolveSkillPath(skillPath) {
+  const resolved = path.resolve(skillPath);
+  if (path.basename(resolved).toLowerCase() === "skill.md") {
+    return path.dirname(resolved);
+  }
+  return resolved;
+}
+
+export function parseSkillFrontmatter(content) {
+  if (!content.startsWith("---")) {
+    throw new Error("No YAML frontmatter found");
+  }
+
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) {
+    throw new Error("Invalid frontmatter format");
+  }
+
+  const frontmatter = YAML.parse(match[1]);
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    throw new Error("Frontmatter must be a YAML dictionary");
+  }
+
+  return frontmatter;
+}
+
+export async function parseSkillFile(skillPath) {
+  const resolvedSkillPath = resolveSkillPath(skillPath);
+  const content = await readSkillMarkdown(resolvedSkillPath);
+  const frontmatter = parseSkillFrontmatter(content);
+  return {
+    content,
+    frontmatter,
+    name: typeof frontmatter.name === "string" ? frontmatter.name : "",
+    description: typeof frontmatter.description === "string" ? frontmatter.description : "",
+  };
+}
+
+export function validateFrontmatter(frontmatter) {
+  const unexpectedKeys = Object.keys(frontmatter).filter((key) => !ALLOWED_PROPERTIES.has(key));
+  if (unexpectedKeys.length > 0) {
+    return {
+      valid: false,
+      message:
+        `Unexpected key(s) in SKILL.md frontmatter: ${unexpectedKeys.sort().join(", ")}. ` +
+        `Allowed properties are: ${Array.from(ALLOWED_PROPERTIES).sort().join(", ")}`,
+    };
+  }
+
+  if (!("name" in frontmatter)) {
+    return { valid: false, message: "Missing 'name' in frontmatter" };
+  }
+  if (!("description" in frontmatter)) {
+    return { valid: false, message: "Missing 'description' in frontmatter" };
+  }
+
+  const name = frontmatter.name;
+  if (typeof name !== "string") {
+    return { valid: false, message: `Name must be a string, got ${typeof name}` };
+  }
+  const trimmedName = name.trim();
+  if (trimmedName) {
+    if (!/^[a-z0-9-]+$/.test(trimmedName)) {
+      return {
+        valid: false,
+        message: `Name '${trimmedName}' should be kebab-case (lowercase letters, digits, and hyphens only)`,
+      };
+    }
+    if (trimmedName.startsWith("-") || trimmedName.endsWith("-") || trimmedName.includes("--")) {
+      return {
+        valid: false,
+        message: `Name '${trimmedName}' cannot start/end with hyphen or contain consecutive hyphens`,
+      };
+    }
+    if (trimmedName.length > 64) {
+      return {
+        valid: false,
+        message: `Name is too long (${trimmedName.length} characters). Maximum is 64 characters.`,
+      };
+    }
+  }
+
+  const description = frontmatter.description;
+  if (typeof description !== "string") {
+    return { valid: false, message: `Description must be a string, got ${typeof description}` };
+  }
+  const trimmedDescription = description.trim();
+  if (trimmedDescription) {
+    if (trimmedDescription.includes("<") || trimmedDescription.includes(">")) {
+      return { valid: false, message: "Description cannot contain angle brackets (< or >)" };
+    }
+    if (trimmedDescription.length > 1024) {
+      return {
+        valid: false,
+        message: `Description is too long (${trimmedDescription.length} characters). Maximum is 1024 characters.`,
+      };
+    }
+  }
+
+  const compatibility = frontmatter.compatibility;
+  if (compatibility !== undefined && compatibility !== null && compatibility !== "") {
+    if (typeof compatibility !== "string") {
+      return { valid: false, message: `Compatibility must be a string, got ${typeof compatibility}` };
+    }
+    if (compatibility.length > 500) {
+      return {
+        valid: false,
+        message: `Compatibility is too long (${compatibility.length} characters). Maximum is 500 characters.`,
+      };
+    }
+  }
+
+  return { valid: true, message: "Skill is valid!" };
+}