skilltest 0.1.0

package/dist/index.js

@@ -0,0 +1,1626 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs5 from "node:fs";
+import path5 from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+
+// src/core/skill-parser.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import yaml from "js-yaml";
+import { z } from "zod";
+var frontmatterSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  license: z.string().optional()
+}).passthrough();
+var FRONTMATTER_BLOCK_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+async function resolveSkillPath(inputPath) {
+  const absoluteInput = path.resolve(inputPath);
+  let stat;
+  try {
+    stat = await fs.stat(absoluteInput);
+  } catch {
+    throw new Error(`Path not found: ${inputPath}`);
+  }
+  if (stat.isDirectory()) {
+    const skillFile = path.join(absoluteInput, "SKILL.md");
+    try {
+      const skillStat = await fs.stat(skillFile);
+      if (!skillStat.isFile()) {
+        throw new Error();
+      }
+    } catch {
+      throw new Error(`No SKILL.md found in directory: ${inputPath}`);
+    }
+    return { skillRoot: absoluteInput, skillFile };
+  }
+  if (!stat.isFile()) {
+    throw new Error(`Path is not a file or directory: ${inputPath}`);
+  }
+  if (path.basename(absoluteInput) !== "SKILL.md") {
+    throw new Error(`Expected SKILL.md or a directory containing SKILL.md. Received: ${inputPath}`);
+  }
+  return { skillRoot: path.dirname(absoluteInput), skillFile: absoluteInput };
+}
+async function loadSkillFile(inputPath) {
+  const { skillRoot, skillFile } = await resolveSkillPath(inputPath);
+  const raw = await fs.readFile(skillFile, "utf8");
+  const lineCount = raw === "" ? 0 : raw.split(/\r?\n/).length;
+  return { skillRoot, skillFile, raw, lineCount };
+}
+function parseFrontmatter(rawSkill) {
+  const blockMatch = rawSkill.match(FRONTMATTER_BLOCK_REGEX);
+  const rawFrontmatter = blockMatch?.[1] ?? null;
+  if (!rawFrontmatter) {
+    return {
+      hasFrontmatter: false,
+      rawFrontmatter: null,
+      data: null,
+      content: rawSkill,
+      error: null
+    };
+  }
+  try {
+    const parsedByYaml = yaml.load(rawFrontmatter);
+    if (parsedByYaml === null || typeof parsedByYaml !== "object" || Array.isArray(parsedByYaml)) {
+      return {
+        hasFrontmatter: true,
+        rawFrontmatter,
+        data: null,
+        content: rawSkill.replace(FRONTMATTER_BLOCK_REGEX, ""),
+        error: "Frontmatter must parse into a YAML object."
+      };
+    }
+    const parsedByMatter = matter(rawSkill);
+    return {
+      hasFrontmatter: true,
+      rawFrontmatter,
+      data: parsedByMatter.data,
+      content: parsedByMatter.content,
+      error: null
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown frontmatter parse error";
+    return {
+      hasFrontmatter: true,
+      rawFrontmatter,
+      data: null,
+      content: rawSkill.replace(FRONTMATTER_BLOCK_REGEX, ""),
+      error: message
+    };
+  }
+}
+async function parseSkillStrict(inputPath) {
+  const skillContext = await loadSkillFile(inputPath);
+  const parsedFrontmatter = parseFrontmatter(skillContext.raw);
+  if (!parsedFrontmatter.hasFrontmatter) {
+    throw new Error("SKILL.md is missing YAML frontmatter.");
+  }
+  if (parsedFrontmatter.error) {
+    throw new Error(`Invalid frontmatter: ${parsedFrontmatter.error}`);
+  }
+  const validation = frontmatterSchema.safeParse(parsedFrontmatter.data ?? {});
+  if (!validation.success) {
+    const issue = validation.error.issues[0];
+    throw new Error(`Invalid frontmatter field '${issue.path.join(".")}': ${issue.message}`);
+  }
+  return {
+    skillRoot: skillContext.skillRoot,
+    skillFile: skillContext.skillFile,
+    raw: skillContext.raw,
+    content: parsedFrontmatter.content,
+    frontmatterRaw: parsedFrontmatter.rawFrontmatter,
+    frontmatter: validation.data
+  };
+}
+var RELATIVE_LINK_PREFIXES = ["./", "../", "scripts/", "references/", "assets/"];
+function extractRelativeFileReferences(markdown) {
+  const references = /* @__PURE__ */ new Set();
+  const markdownLinkRegex = /\[[^\]]+\]\(([^)]+)\)/g;
+  for (const match of markdown.matchAll(markdownLinkRegex)) {
+    const rawTarget = (match[1] ?? "").trim();
+    const cleaned = cleanReferenceTarget(rawTarget);
+    if (cleaned && isLikelyRelativePath(cleaned)) {
+      references.add(cleaned);
+    }
+  }
+  const inlineCodeRegex = /`([^`]+)`/g;
+  for (const match of markdown.matchAll(inlineCodeRegex)) {
+    const candidate = (match[1] ?? "").trim();
+    if (isLikelyRelativePath(candidate)) {
+      references.add(cleanReferenceTarget(candidate));
+    }
+  }
+  const barePathRegex = /\b(?:scripts|references|assets)\/[A-Za-z0-9._\-/]+/g;
+  for (const match of markdown.matchAll(barePathRegex)) {
+    const candidate = match[0];
+    if (candidate) {
+      references.add(cleanReferenceTarget(candidate));
+    }
+  }
+  return Array.from(references);
+}
+function cleanReferenceTarget(target) {
+  if (!target) {
+    return null;
+  }
+  let cleaned = target.trim();
+  if (cleaned.startsWith("<") && cleaned.endsWith(">")) {
+    cleaned = cleaned.slice(1, -1).trim();
+  }
+  if (cleaned === "" || cleaned.startsWith("#")) {
+    return null;
+  }
+  if (/^(https?:|mailto:|tel:)/i.test(cleaned)) {
+    return null;
+  }
+  const hashIndex = cleaned.indexOf("#");
+  if (hashIndex >= 0) {
+    cleaned = cleaned.slice(0, hashIndex).trim();
+  }
+  return cleaned || null;
+}
+function isLikelyRelativePath(candidate) {
+  if (!candidate) {
+    return false;
+  }
+  if (candidate.startsWith("/")) {
+    return false;
+  }
+  if (/^[A-Za-z]:\\/.test(candidate)) {
+    return false;
+  }
+  if (/^(https?:|mailto:|tel:)/i.test(candidate)) {
+    return false;
+  }
+  if (RELATIVE_LINK_PREFIXES.some((prefix) => candidate.startsWith(prefix))) {
+    return true;
+  }
+  return /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+$/.test(candidate);
+}
+
+// src/core/linter/compat.ts
+function runCompatibilityChecks(context) {
+  const issues = [];
+  const frontmatter = context.frontmatter.data ?? {};
+  const body = context.frontmatter.content;
+  const hasAllowedTools = Object.prototype.hasOwnProperty.call(frontmatter, "allowed-tools");
+  const mentionsClaudeOnly = /\bclaude code\b/i.test(body);
+  const mentionsCodexOnly = /\bcodex\b/i.test(body) && !/\bopenai\b/i.test(body);
+  if (hasAllowedTools) {
+    issues.push({
+      id: "compat.allowed-tools",
+      title: "Platform-Specific Frontmatter",
+      status: "warn",
+      message: "Frontmatter includes allowed-tools, which is typically Claude-specific.",
+      suggestion: "Document fallback behavior for platforms that ignore allowed-tools."
+    });
+  } else {
+    issues.push({
+      id: "compat.allowed-tools",
+      title: "Platform-Specific Frontmatter",
+      status: "pass",
+      message: "No known provider-specific frontmatter keys detected."
+    });
+  }
+  if (mentionsClaudeOnly || mentionsCodexOnly) {
+    const platform = mentionsClaudeOnly ? "Claude" : "Codex";
+    issues.push({
+      id: "compat.provider-phrasing",
+      title: "Provider-Specific Language",
+      status: "warn",
+      message: `Skill body appears tuned to ${platform}-specific behavior.`,
+      suggestion: "Add neutral instructions or an explicit compatibility note for other agents."
+    });
+  } else {
+    issues.push({
+      id: "compat.provider-phrasing",
+      title: "Provider-Specific Language",
+      status: "pass",
+      message: "Skill body appears provider-neutral."
+    });
+  }
+  const likelyCompatibility = hasAllowedTools || mentionsClaudeOnly || mentionsCodexOnly ? "Likely compatible with some agents, but includes platform-specific assumptions." : "Likely broadly compatible across Anthropic, OpenAI/Codex-style, and other markdown skill runners.";
+  issues.push({
+    id: "compat.summary",
+    title: "Compatibility Hint",
+    status: hasAllowedTools || mentionsClaudeOnly || mentionsCodexOnly ? "warn" : "pass",
+    message: likelyCompatibility
+  });
+  return issues;
+}
+
+// src/core/linter/content.ts
+var VAGUE_PATTERNS = [
+  /\bdo something appropriate\b/i,
+  /\bhandle as needed\b/i,
+  /\buse best judgment\b/i,
+  /\bif possible\b/i,
+  /\bwhen relevant\b/i,
+  /\bdo what seems right\b/i
+];
+var SECRET_PATTERNS = [
+  { label: "OpenAI key", regex: /\bsk-[A-Za-z0-9]{20,}\b/ },
+  { label: "AWS access key", regex: /\bAKIA[0-9A-Z]{16}\b/ },
+  { label: "GitHub token", regex: /\bghp_[A-Za-z0-9]{20,}\b/ },
+  { label: "Slack token", regex: /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/ },
+  { label: "Generic private key header", regex: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/ }
+];
+function runContentChecks(context) {
+  const issues = [];
+  const body = context.frontmatter.content;
+  const bodyLines = body.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  const description = typeof context.frontmatter.data?.description === "string" ? context.frontmatter.data.description : "";
+  if (!/^#{1,6}\s+\S+/m.test(body)) {
+    issues.push({
+      id: "content.headers",
+      title: "Section Headers",
+      status: "warn",
+      message: "No markdown headers found in SKILL.md body.",
+      suggestion: "Add section headers to improve scannability and maintenance."
+    });
+  } else {
+    issues.push({
+      id: "content.headers",
+      title: "Section Headers",
+      status: "pass",
+      message: "SKILL.md contains markdown section headers."
+    });
+  }
+  const hasExamples = /example/i.test(body) || /```[\s\S]*?```/.test(body);
+  if (!hasExamples) {
+    issues.push({
+      id: "content.examples",
+      title: "Examples",
+      status: "warn",
+      message: "No examples detected in SKILL.md body.",
+      suggestion: "Add at least one concrete example to guide usage."
+    });
+  } else {
+    issues.push({
+      id: "content.examples",
+      title: "Examples",
+      status: "pass",
+      message: "Examples were detected in SKILL.md."
+    });
+  }
+  const vagueMatches = VAGUE_PATTERNS.filter((pattern) => pattern.test(body));
+  if (vagueMatches.length > 0) {
+    issues.push({
+      id: "content.vagueness",
+      title: "Instruction Specificity",
+      status: "warn",
+      message: "Potentially vague instruction phrases detected.",
+      suggestion: "Replace vague guidance with explicit decision rules or step-by-step instructions."
+    });
+  } else {
+    issues.push({
+      id: "content.vagueness",
+      title: "Instruction Specificity",
+      status: "pass",
+      message: "No obvious vague placeholder phrasing found."
+    });
+  }
+  if (context.frontmatter.rawFrontmatter && /[<>]/.test(context.frontmatter.rawFrontmatter)) {
+    issues.push({
+      id: "content.frontmatter-angle-brackets",
+      title: "Frontmatter Angle Brackets",
+      status: "warn",
+      message: "Frontmatter contains angle bracket characters (< or >), which can be misinterpreted in some agents.",
+      suggestion: "Remove XML-like tags from frontmatter values when possible."
+    });
+  } else {
+    issues.push({
+      id: "content.frontmatter-angle-brackets",
+      title: "Frontmatter Angle Brackets",
+      status: "pass",
+      message: "No angle bracket tokens detected in frontmatter."
+    });
+  }
+  const secretHits = /* @__PURE__ */ new Set();
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.regex.test(context.skill.raw)) {
+      secretHits.add(pattern.label);
+    }
+  }
+  if (secretHits.size > 0) {
+    issues.push({
+      id: "content.secrets",
+      title: "Hardcoded Secrets",
+      status: "fail",
+      message: `Potential secrets detected (${Array.from(secretHits).join(", ")}).`,
+      suggestion: "Remove secrets from skill files and use environment variables or secret managers."
+    });
+  } else {
+    issues.push({
+      id: "content.secrets",
+      title: "Hardcoded Secrets",
+      status: "pass",
+      message: "No obvious API keys or secrets patterns were detected."
+    });
+  }
+  if (bodyLines.length < 10) {
+    issues.push({
+      id: "content.body-length",
+      title: "Body Completeness",
+      status: "warn",
+      message: `SKILL.md body has only ${bodyLines.length} non-empty lines.`,
+      suggestion: "Add more detailed instructions; short bodies are often incomplete."
+    });
+  } else {
+    issues.push({
+      id: "content.body-length",
+      title: "Body Completeness",
+      status: "pass",
+      message: `SKILL.md body has ${bodyLines.length} non-empty lines.`
+    });
+  }
+  if (description && description.length < 50) {
+    issues.push({
+      id: "content.description-length",
+      title: "Description Specificity",
+      status: "warn",
+      message: `Description length is ${description.length} characters, which may be too vague for reliable triggering.`,
+      suggestion: "Expand description with concrete scope and activation conditions."
+    });
+  } else if (description) {
+    issues.push({
+      id: "content.description-length",
+      title: "Description Specificity",
+      status: "pass",
+      message: "Description length is sufficient for triggerability heuristics."
+    });
+  }
+  return issues;
+}
+
+// src/core/linter/disclosure.ts
+import fs3 from "node:fs/promises";
+import path3 from "node:path";
+
+// src/utils/fs.ts
+import fs2 from "node:fs/promises";
+import path2 from "node:path";
+async function pathExists(targetPath) {
+  try {
+    await fs2.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function listFilesRecursive(directory) {
+  const entries = await fs2.readdir(directory, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const absolutePath = path2.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFilesRecursive(absolutePath));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(absolutePath);
+    }
+  }
+  return files;
+}
+async function readJsonFile(filePath) {
+  const raw = await fs2.readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+async function writeJsonFile(filePath, data) {
+  const absolute = path2.resolve(filePath);
+  await fs2.mkdir(path2.dirname(absolute), { recursive: true });
+  await fs2.writeFile(absolute, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+}
+function toPosixPath(inputPath) {
+  return inputPath.split(path2.sep).join("/");
+}
+
+// src/core/linter/disclosure.ts
+function isPathInsideRoot(root, candidate) {
+  const relative = path3.relative(root, candidate);
+  return !relative.startsWith("..") && !path3.isAbsolute(relative);
+}
+async function detectNestedReferenceChain(skillRoot, rootContent) {
+  const initialReferences = extractRelativeFileReferences(rootContent);
+  let maxDepth = 0;
+  for (const reference of initialReferences) {
+    const firstLevelPath = path3.resolve(skillRoot, reference);
+    if (!await pathExists(firstLevelPath)) {
+      continue;
+    }
+    const firstLevelRaw = await fs3.readFile(firstLevelPath, "utf8");
+    const secondLevelRefs = extractRelativeFileReferences(firstLevelRaw);
+    if (secondLevelRefs.length > 0) {
+      maxDepth = Math.max(maxDepth, 1);
+    }
+    for (const secondLevelReference of secondLevelRefs) {
+      const secondLevelPath = path3.resolve(path3.dirname(firstLevelPath), secondLevelReference);
+      if (!await pathExists(secondLevelPath)) {
+        continue;
+      }
+      const secondLevelRaw = await fs3.readFile(secondLevelPath, "utf8");
+      const thirdLevelRefs = extractRelativeFileReferences(secondLevelRaw);
+      if (thirdLevelRefs.length > 0) {
+        maxDepth = Math.max(maxDepth, 2);
+      }
+    }
+  }
+  return maxDepth;
+}
+async function runDisclosureChecks(context) {
+  const issues = [];
+  const references = extractRelativeFileReferences(context.skill.raw);
+  const referencesDir = path3.join(context.skill.skillRoot, "references");
+  if (context.skill.lineCount > 200 && !await pathExists(referencesDir)) {
+    issues.push({
+      id: "disclosure.skill-split",
+      title: "Progressive Disclosure",
+      status: "warn",
+      message: "SKILL.md exceeds 200 lines and no references/ directory is present.",
+      suggestion: "Move detailed material into references/ files and keep SKILL.md focused."
+    });
+  } else {
+    issues.push({
+      id: "disclosure.skill-split",
+      title: "Progressive Disclosure",
+      status: "pass",
+      message: "Top-level file length and references/ usage look reasonable."
+    });
+  }
+  const nonRelativeOrEscaping = [];
+  for (const rawReference of references) {
+    const cleaned = cleanReferenceTarget(rawReference);
+    if (!cleaned) {
+      continue;
+    }
+    if (path3.isAbsolute(cleaned) || /^[A-Za-z]:\\/.test(cleaned) || cleaned.startsWith("~")) {
+      nonRelativeOrEscaping.push(cleaned);
+      continue;
+    }
+    if (!isLikelyRelativePath(cleaned)) {
+      nonRelativeOrEscaping.push(cleaned);
+      continue;
+    }
+    const resolved = path3.resolve(context.skill.skillRoot, cleaned);
+    if (!isPathInsideRoot(context.skill.skillRoot, resolved)) {
+      nonRelativeOrEscaping.push(cleaned);
+    }
+  }
+  if (nonRelativeOrEscaping.length > 0) {
+    issues.push({
+      id: "disclosure.relative-path-root",
+      title: "Reference Path Scope",
+      status: "fail",
+      message: `Found non-relative or out-of-root references: ${nonRelativeOrEscaping.join(", ")}`,
+      suggestion: "Use relative paths that stay within the skill root directory."
+    });
+  } else {
+    issues.push({
+      id: "disclosure.relative-path-root",
+      title: "Reference Path Scope",
+      status: "pass",
+      message: "All detected file references are relative and scoped to skill root."
+    });
+  }
+  const chainDepth = await detectNestedReferenceChain(context.skill.skillRoot, context.skill.raw);
+  if (chainDepth > 1) {
+    issues.push({
+      id: "disclosure.reference-depth",
+      title: "Reference Chain Depth",
+      status: "warn",
+      message: "Deep reference chains detected (>1 level).",
+      suggestion: "Avoid linking from references to more nested references where possible."
+    });
+  } else {
+    issues.push({
+      id: "disclosure.reference-depth",
+      title: "Reference Chain Depth",
+      status: "pass",
+      message: "Reference depth is shallow and easy to navigate."
+    });
+  }
+  const normalizedReferences = references.map((item) => toPosixPath(item));
+  if (normalizedReferences.some((item) => item.includes("../"))) {
+    issues.push({
+      id: "disclosure.parent-traversal",
+      title: "Parent Traversal",
+      status: "warn",
+      message: "References include parent-directory traversal (../).",
+      suggestion: "Prefer references rooted within the skill directory for portability."
+    });
+  } else {
+    issues.push({
+      id: "disclosure.parent-traversal",
+      title: "Parent Traversal",
+      status: "pass",
+      message: "No parent-directory traversal references detected."
+    });
+  }
+  return issues;
+}
+
+// src/core/linter/frontmatter.ts
+var SKILL_NAME_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function getStringField(data, key) {
+  if (!data) {
+    return null;
+  }
+  const value = data[key];
+  if (typeof value !== "string") {
+    return null;
+  }
+  return value;
+}
+function descriptionLooksActionable(description) {
+  const whatPattern = /\b(create|build|generate|analyze|test|validate|review|refactor|debug|audit|compose|transform|summari[sz]e|plan)\b/i;
+  const whenPattern = /\b(when|if|for|whenever|use this|ideal for|best for|should use)\b/i;
+  return whatPattern.test(description) && whenPattern.test(description);
+}
+function runFrontmatterChecks(context) {
+  const issues = [];
+  if (!context.frontmatter.hasFrontmatter) {
+    issues.push({
+      id: "frontmatter.exists",
+      title: "Frontmatter Presence",
+      status: "fail",
+      message: "SKILL.md is missing YAML frontmatter delimited by --- blocks.",
+      suggestion: "Add YAML frontmatter at the top with at least name and description."
+    });
+    return issues;
+  }
+  if (context.frontmatter.error) {
+    issues.push({
+      id: "frontmatter.valid-yaml",
+      title: "Frontmatter YAML",
+      status: "fail",
+      message: `Frontmatter is not valid YAML: ${context.frontmatter.error}`,
+      suggestion: "Fix YAML syntax so the frontmatter parses as an object."
+    });
+    return issues;
+  }
+  issues.push({
+    id: "frontmatter.valid-yaml",
+    title: "Frontmatter YAML",
+    status: "pass",
+    message: "Frontmatter exists and parses correctly."
+  });
+  const data = context.frontmatter.data ?? {};
+  const name = getStringField(data, "name");
+  if (!name) {
+    issues.push({
+      id: "frontmatter.name.required",
+      title: "Frontmatter Name",
+      status: "fail",
+      message: "Missing required frontmatter field: name.",
+      suggestion: "Set name to lowercase words separated by single hyphens."
+    });
+  } else if (name.length > 64) {
+    issues.push({
+      id: "frontmatter.name.length",
+      title: "Frontmatter Name Length",
+      status: "fail",
+      message: `name is too long (${name.length} chars, max 64).`,
+      suggestion: "Shorten the skill name to 64 characters or fewer."
+    });
+  } else if (!SKILL_NAME_REGEX.test(name)) {
+    issues.push({
+      id: "frontmatter.name.format",
+      title: "Frontmatter Name Format",
+      status: "fail",
+      message: "name must be lowercase alphanumeric with single hyphen separators only.",
+      suggestion: "Use format like 'api-tester' or 'code-review'."
+    });
+  } else {
+    issues.push({
+      id: "frontmatter.name.valid",
+      title: "Frontmatter Name",
+      status: "pass",
+      message: "name is present and follows naming conventions."
+    });
+  }
+  const description = getStringField(data, "description");
+  if (!description || description.trim() === "") {
+    issues.push({
+      id: "frontmatter.description.required",
+      title: "Frontmatter Description",
+      status: "fail",
+      message: "Missing required frontmatter field: description.",
+      suggestion: "Add a clear description of what the skill does and when to use it."
+    });
+  } else if (description.length > 1024) {
+    issues.push({
+      id: "frontmatter.description.length",
+      title: "Frontmatter Description Length",
+      status: "fail",
+      message: `description is too long (${description.length} chars, max 1024).`,
+      suggestion: "Keep description concise while still specific."
+    });
+  } else {
+    issues.push({
+      id: "frontmatter.description.valid",
+      title: "Frontmatter Description",
+      status: "pass",
+      message: "description is present and within allowed length."
+    });
+  }
+  const license = getStringField(data, "license");
+  if (!license || license.trim() === "") {
+    issues.push({
+      id: "frontmatter.license.recommended",
+      title: "Frontmatter License",
+      status: "warn",
+      message: "No license field found in frontmatter.",
+      suggestion: "Add a license (for example: MIT) to clarify reuse terms."
+    });
+  } else {
+    issues.push({
+      id: "frontmatter.license.present",
+      title: "Frontmatter License",
+      status: "pass",
+      message: "license field is present."
+    });
+  }
+  if (description && description.trim() !== "" && !descriptionLooksActionable(description)) {
+    issues.push({
+      id: "frontmatter.description.triggerability",
+      title: "Description Trigger Clarity",
+      status: "warn",
+      message: "Description should explain both what the skill does and when it should be used.",
+      suggestion: "Include explicit 'use when...' language plus concrete capability wording."
+    });
+  } else if (description) {
+    issues.push({
+      id: "frontmatter.description.triggerability",
+      title: "Description Trigger Clarity",
+      status: "pass",
+      message: "Description appears to cover both capability and usage context."
+    });
+  }
+  return issues;
+}
+
+// src/core/linter/structure.ts
+import fs4 from "node:fs/promises";
+import path4 from "node:path";
+function hasTableOfContents(content) {
+  if (/^#{1,6}\s+table of contents\b/im.test(content)) {
+    return true;
+  }
+  return /^\s*[-*]\s+\[[^\]]+\]\(#[^)]+\)/im.test(content);
+}
+function classifyReferencePath(relativePath) {
+  const normalized = toPosixPath(relativePath).replace(/^\.\//, "");
+  if (normalized.startsWith("scripts/")) {
+    return "scripts";
+  }
+  if (normalized.startsWith("references/")) {
+    return "references";
+  }
+  if (normalized.startsWith("assets/")) {
+    return "assets";
+  }
+  return "other";
+}
+async function runStructureChecks(context) {
+  const issues = [];
+  const references = extractRelativeFileReferences(context.skill.raw);
+  if (context.skill.lineCount > 500) {
+    issues.push({
+      id: "structure.skill-size",
+      title: "SKILL.md Size",
+      status: "warn",
+      message: `SKILL.md is ${context.skill.lineCount} lines (recommended max is 500).`,
+      suggestion: "Split detailed guidance into references/ files."
+    });
+  } else {
+    issues.push({
+      id: "structure.skill-size",
+      title: "SKILL.md Size",
+      status: "pass",
+      message: `SKILL.md length is ${context.skill.lineCount} lines.`
+    });
+  }
+  const referencesDir = path4.join(context.skill.skillRoot, "references");
+  if (await pathExists(referencesDir)) {
+    const files = await listFilesRecursive(referencesDir);
+    let oversizedWithoutToc = 0;
+    for (const file of files) {
+      const raw = await fs4.readFile(file, "utf8");
+      const lineCount = raw === "" ? 0 : raw.split(/\r?\n/).length;
+      if (lineCount > 300 && !hasTableOfContents(raw)) {
+        oversizedWithoutToc += 1;
+        issues.push({
+          id: `structure.references.toc.${toPosixPath(path4.relative(context.skill.skillRoot, file))}`,
+          title: "Reference File Navigation",
+          status: "warn",
+          message: `${toPosixPath(path4.relative(context.skill.skillRoot, file))} is ${lineCount} lines and has no table of contents.`,
+          suggestion: "Add a table of contents for long reference files."
+        });
+      }
+    }
+    if (oversizedWithoutToc === 0) {
+      issues.push({
+        id: "structure.references.toc",
+        title: "Reference File Navigation",
+        status: "pass",
+        message: "No oversized reference files missing a table of contents."
+      });
+    }
+  } else {
+    issues.push({
+      id: "structure.references.toc",
+      title: "Reference File Navigation",
+      status: "pass",
+      message: "No references/ directory found, so no long reference files to validate."
+    });
+  }
+  const missingByType = {
+    scripts: [],
+    references: [],
+    assets: [],
+    other: []
+  };
+  for (const reference of references) {
+    const resolved = path4.resolve(context.skill.skillRoot, reference);
+    if (!await pathExists(resolved)) {
+      const kind = classifyReferencePath(reference);
+      missingByType[kind].push(reference);
+    }
+  }
+  const categories = [
+    { key: "scripts", title: "Script References" },
+    { key: "references", title: "Reference File Links" },
+    { key: "assets", title: "Asset References" }
+  ];
+  for (const category of categories) {
+    const missing = missingByType[category.key];
+    if (missing.length > 0) {
+      issues.push({
+        id: `structure.${category.key}.exists`,
+        title: category.title,
+        status: "fail",
+        message: `Missing referenced ${category.key} file(s): ${missing.join(", ")}`,
+        suggestion: "Create the files or fix the paths in SKILL.md."
+      });
+    } else {
+      issues.push({
+        id: `structure.${category.key}.exists`,
+        title: category.title,
+        status: "pass",
+        message: `All referenced ${category.key} files exist.`
+      });
+    }
+  }
+  const missingGeneric = missingByType.other;
+  if (missingGeneric.length > 0) {
+    issues.push({
+      id: "structure.relative-links.broken",
+      title: "Relative Links",
+      status: "fail",
+      message: `Broken relative path reference(s): ${missingGeneric.join(", ")}`,
+      suggestion: "Fix or remove broken file links."
+    });
+  } else {
+    issues.push({
+      id: "structure.relative-links.broken",
+      title: "Relative Links",
+      status: "pass",
+      message: "No broken generic relative file references were found."
+    });
+  }
+  return issues;
+}
+
+// src/core/linter/index.ts
+function summarizeIssues(issues) {
+  const summary = {
+    total: issues.length,
+    passed: 0,
+    warnings: 0,
+    failures: 0
+  };
+  for (const issue of issues) {
+    if (issue.status === "pass") {
+      summary.passed += 1;
+      continue;
+    }
+    if (issue.status === "warn") {
+      summary.warnings += 1;
+      continue;
+    }
+    summary.failures += 1;
+  }
+  return summary;
+}
+async function runLinter(inputPath) {
+  const skill = await loadSkillFile(inputPath);
+  const frontmatter = parseFrontmatter(skill.raw);
+  const context = {
+    skill,
+    frontmatter
+  };
+  const issues = [];
+  issues.push(...runFrontmatterChecks(context));
+  issues.push(...await runStructureChecks(context));
+  issues.push(...runContentChecks(context));
+  issues.push(...await runDisclosureChecks(context));
+  issues.push(...runCompatibilityChecks(context));
+  return {
+    target: inputPath,
+    issues,
+    summary: summarizeIssues(issues)
+  };
+}
+
+// src/reporters/terminal.ts
+import { Chalk } from "chalk";
+function getChalkInstance(enableColor) {
+  return new Chalk({ level: enableColor ? 1 : 0 });
+}
+function renderIssueLine(issue, c) {
+  const label = issue.status === "pass" ? c.green("PASS") : issue.status === "warn" ? c.yellow("WARN") : c.red("FAIL");
+  const detail = issue.suggestion ? `
+      suggestion: ${issue.suggestion}` : "";
+  return `  ${label} ${issue.title}
+      ${issue.message}${detail}`;
+}
+function renderLintReport(report, enableColor) {
+  const c = getChalkInstance(enableColor);
+  const { passed, warnings, failures, total } = report.summary;
+  const headerLines = [
+    `\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510`,
+    `\u2502 skilltest lint                                                \u2502`,
+    `\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524`,
+    `\u2502 target: ${report.target}`,
+    `\u2502 summary: ${passed}/${total} checks passed, ${warnings} warnings, ${failures} failures`,
+    `\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518`
+  ];
+  const renderedIssues = report.issues.map((issue) => renderIssueLine(issue, c)).join("\n");
+  return `${headerLines.join("\n")}
+${renderedIssues}`;
+}
+function formatPercent(value) {
+  return `${(value * 100).toFixed(1)}%`;
+}
+function renderTriggerReport(result, enableColor, verbose) {
+  const c = getChalkInstance(enableColor);
+  const lines = [];
+  lines.push("\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+  lines.push("\u2502 skilltest trigger                                             \u2502");
+  lines.push("\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+  lines.push(`\u2502 skill: ${result.skillName}`);
+  lines.push(`\u2502 provider/model: ${result.provider}/${result.model}`);
+  lines.push(
+    `\u2502 precision: ${formatPercent(result.metrics.precision)}  recall: ${formatPercent(result.metrics.recall)}  f1: ${formatPercent(result.metrics.f1)}`
+  );
+  lines.push(
+    `\u2502 TP ${result.metrics.truePositives}  TN ${result.metrics.trueNegatives}  FP ${result.metrics.falsePositives}  FN ${result.metrics.falseNegatives}`
+  );
+  lines.push("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
+  for (const [index, testCase] of result.cases.entries()) {
+    const status = testCase.matched ? c.green("PASS") : c.red("FAIL");
+    lines.push(`${index + 1}. ${status} query: ${testCase.query}`);
+    lines.push(`   expected: ${testCase.expected} | actual: ${testCase.actual}`);
+    if (verbose && testCase.rawModelResponse) {
+      lines.push(`   model: ${testCase.rawModelResponse.replace(/\s+/g, " ").trim()}`);
+    }
+  }
+  lines.push("Suggestions:");
+  for (const suggestion of result.suggestions) {
+    lines.push(`- ${suggestion}`);
+  }
+  return lines.join("\n");
+}
+function renderEvalReport(result, enableColor, verbose) {
+  const c = getChalkInstance(enableColor);
+  const lines = [];
+  lines.push("\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510");
+  lines.push("\u2502 skilltest eval                                                \u2502");
+  lines.push("\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524");
+  lines.push(`\u2502 skill: ${result.skillName}`);
+  lines.push(`\u2502 provider/model: ${result.provider}/${result.model}`);
+  lines.push(`\u2502 grader model: ${result.graderModel}`);
+  lines.push(`\u2502 assertions passed: ${result.summary.passedAssertions}/${result.summary.totalAssertions}`);
+  lines.push("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518");
+  for (const [index, promptResult] of result.results.entries()) {
+    lines.push(`${index + 1}. prompt: ${promptResult.prompt}`);
+    lines.push(`   response summary: ${promptResult.responseSummary.replace(/\s+/g, " ").trim()}`);
+    for (const assertion of promptResult.assertions) {
+      const status = assertion.passed ? c.green("PASS") : c.red("FAIL");
+      lines.push(`   ${status} ${assertion.assertion}`);
+      lines.push(`      evidence: ${assertion.evidence}`);
+    }
+    if (verbose) {
+      lines.push(`   full response: ${promptResult.response}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/reporters/json.ts
+function renderJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+// src/commands/common.ts
+function getGlobalCliOptions(command) {
+  const options = command.optsWithGlobals();
+  return {
+    json: Boolean(options.json),
+    color: options.color !== false
+  };
+}
+function writeResult(value, asJson) {
+  if (asJson) {
+    process.stdout.write(`${renderJson(value)}
+`);
+    return;
+  }
+  process.stdout.write(`${String(value)}
+`);
+}
+function writeError(error, asJson) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (asJson) {
+    process.stdout.write(`${renderJson({ error: message })}
+`);
+    return;
+  }
+  process.stderr.write(`Error: ${message}
+`);
+}
+
+// src/commands/lint.ts
+function registerLintCommand(program) {
+  program.command("lint").description("Run static lint checks against a SKILL.md file or skill directory.").argument("<path-to-skill>", "Path to SKILL.md or skill directory").action(async (targetPath, _commandOptions, command) => {
+    const globalOptions = getGlobalCliOptions(command);
+    try {
+      const report = await runLinter(targetPath);
+      if (globalOptions.json) {
+        writeResult(report, true);
+      } else {
+        writeResult(renderLintReport(report, globalOptions.color), false);
+      }
+      if (report.summary.failures > 0) {
+        process.exitCode = 1;
+      }
+    } catch (error) {
+      writeError(error, globalOptions.json);
+      process.exitCode = 2;
+    }
+  });
+}
+
+// src/commands/trigger.ts
+import ora from "ora";
+import { z as z3 } from "zod";
+
+// src/core/trigger-tester.ts
+import { z as z2 } from "zod";
+var triggerQuerySchema = z2.object({
+  query: z2.string().min(1),
+  should_trigger: z2.boolean()
+});
+var triggerQueryArraySchema = z2.array(triggerQuerySchema);
+var FAKE_SKILLS = [
+  { name: "code-review", description: "Reviews code changes for bugs, regressions, and maintainability issues." },
+  { name: "api-tester", description: "Designs and runs REST API tests, validating status codes and response shapes." },
+  { name: "db-migrator", description: "Plans and generates safe database migration scripts with rollback guidance." },
+  { name: "bug-repro", description: "Reproduces reported bugs by building deterministic minimal test cases." },
+  { name: "release-notes", description: "Drafts release notes from commits and PR metadata for stakeholders." },
+  { name: "log-analyzer", description: "Analyzes service logs to identify error clusters and likely root causes." },
+  { name: "performance-audit", description: "Finds hotspots in runtime and suggests profiling-driven optimizations." },
+  { name: "security-audit", description: "Checks code and config for common security vulnerabilities and risky defaults." },
+  { name: "refactor-planner", description: "Breaks large refactors into safe incremental steps with validation plans." },
+  { name: "schema-designer", description: "Designs JSON schemas and validates data contracts for integrations." },
+  { name: "docs-writer", description: "Writes developer documentation, tutorials, and API usage examples." },
+  { name: "cli-scaffolder", description: "Creates CLI project skeletons with argument parsing and help text." },
+  { name: "incident-triage", description: "Triage production incidents with severity tagging and next-action checklists." },
+  { name: "test-generator", description: "Generates unit and integration test cases from feature requirements." },
+  { name: "prompt-tuner", description: "Improves prompts for reliability, formatting, and failure handling." }
+];
+function shuffle(values) {
+  const copy = [...values];
+  for (let index = copy.length - 1; index > 0; index -= 1) {
+    const swapIndex = Math.floor(Math.random() * (index + 1));
+    [copy[index], copy[swapIndex]] = [copy[swapIndex], copy[index]];
+  }
+  return copy;
+}
+function sample(values, count) {
+  return shuffle(values).slice(0, Math.max(0, Math.min(count, values.length)));
+}
+function parseJsonArrayFromModelOutput(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return JSON.parse(trimmed);
+  }
+  const start = trimmed.indexOf("[");
+  const end = trimmed.lastIndexOf("]");
+  if (start >= 0 && end > start) {
+    const possibleJson = trimmed.slice(start, end + 1);
+    return JSON.parse(possibleJson);
+  }
+  throw new Error("Model did not return a JSON array.");
+}
+async function generateQueriesWithModel(skill, provider, model, numQueries) {
+  const shouldTriggerCount = Math.floor(numQueries / 2);
+  const shouldNotTriggerCount = numQueries - shouldTriggerCount;
+  const systemPrompt = [
+    "You generate realistic user prompts to test whether a specific agent skill triggers.",
+    "Return JSON only. No markdown, no comments.",
+    'Each entry must be an object: {"query": string, "should_trigger": boolean}.',
+    "Create substantive prompts, not toy one-liners."
+  ].join(" ");
+  const userPrompt = [
+    `Skill name: ${skill.frontmatter.name}`,
+    `Skill description: ${skill.frontmatter.description}`,
+    `Generate ${numQueries} prompts total.`,
+    `Exactly ${shouldTriggerCount} should have should_trigger=true.`,
+    `Exactly ${shouldNotTriggerCount} should have should_trigger=false.`,
+    "Prompts should look like real user requests with enough context to drive a trigger decision."
+  ].join("\n");
+  const raw = await provider.sendMessage(systemPrompt, userPrompt, { model });
+  const parsed = triggerQueryArraySchema.safeParse(parseJsonArrayFromModelOutput(raw));
+  if (!parsed.success) {
+    throw new Error(`Failed to parse generated queries: ${parsed.error.issues[0]?.message ?? "invalid format"}`);
+  }
+  const trueCount = parsed.data.filter((item) => item.should_trigger).length;
+  const falseCount = parsed.data.length - trueCount;
+  if (parsed.data.length !== numQueries || trueCount !== shouldTriggerCount || falseCount !== shouldNotTriggerCount) {
+    throw new Error(
+      `Generated query split mismatch. Expected ${numQueries} (${shouldTriggerCount}/${shouldNotTriggerCount}), got ${parsed.data.length} (${trueCount}/${falseCount}).`
+    );
+  }
+  return parsed.data;
+}
+function parseDecision(rawResponse, skillNames) {
+  const normalized = rawResponse.trim().toLowerCase();
+  if (normalized === "none" || normalized.startsWith("none")) {
+    return "none";
+  }
+  for (const skillName of skillNames) {
+    const escaped = skillName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`\\b${escaped}\\b`, "i");
+    if (regex.test(rawResponse)) {
+      return skillName;
+    }
+  }
+  return "unrecognized";
+}
+function calculateMetrics(skillName, cases) {
+  let truePositives = 0;
+  let trueNegatives = 0;
+  let falsePositives = 0;
+  let falseNegatives = 0;
+  for (const testCase of cases) {
+    const choseTargetSkill = testCase.actual === skillName;
+    if (testCase.shouldTrigger && choseTargetSkill) {
+      truePositives += 1;
+      continue;
+    }
+    if (testCase.shouldTrigger && !choseTargetSkill) {
+      falseNegatives += 1;
+      continue;
+    }
+    if (!testCase.shouldTrigger && choseTargetSkill) {
+      falsePositives += 1;
+      continue;
+    }
+    trueNegatives += 1;
+  }
+  const precisionDenominator = truePositives + falsePositives;
+  const recallDenominator = truePositives + falseNegatives;
+  const precision = precisionDenominator === 0 ? 0 : truePositives / precisionDenominator;
+  const recall = recallDenominator === 0 ? 0 : truePositives / recallDenominator;
+  const f1 = precision + recall === 0 ? 0 : 2 * precision * recall / (precision + recall);
+  return {
+    truePositives,
+    trueNegatives,
+    falsePositives,
+    falseNegatives,
+    precision,
+    recall,
+    f1
+  };
+}
+function buildSuggestions(metrics) {
+  const suggestions = [];
+  if (metrics.falseNegatives > 0) {
+    suggestions.push(
+      "False negatives found: clarify capability keywords and add explicit 'use when ...' phrasing in description."
+    );
+  }
+  if (metrics.falsePositives > 0) {
+    suggestions.push("False positives found: narrow scope boundaries and add explicit non-goals in description.");
+  }
+  if (suggestions.length === 0) {
+    suggestions.push("Trigger behavior looks clean on this sample. Keep monitoring with domain-specific custom queries.");
+  }
+  return suggestions;
+}
+async function runTriggerTest(skill, options) {
+  const queries = options.queries && options.queries.length > 0 ? triggerQueryArraySchema.parse(options.queries) : await generateQueriesWithModel(skill, options.provider, options.model, options.numQueries);
+  const results = [];
+  const skillName = skill.frontmatter.name;
+  for (const testQuery of queries) {
+    const fakeCount = 5 + Math.floor(Math.random() * 4);
+    const fakeSkills = sample(FAKE_SKILLS, fakeCount);
+    const allSkills = shuffle([
+      ...fakeSkills,
+      {
+        name: skill.frontmatter.name,
+        description: skill.frontmatter.description
+      }
+    ]);
+    const skillListText = allSkills.map((entry) => `- ${entry.name}: ${entry.description}`).join("\n");
+    const systemPrompt = [
+      "You are selecting one skill to activate for a user query.",
+      "Choose the single best matching skill name from the provided list, or 'none' if no skill is a good fit.",
+      "Respond with only the skill name or 'none'."
+    ].join(" ");
+    const userPrompt = [`Available skills:`, skillListText, "", `User query: ${testQuery.query}`].join("\n");
+    const rawResponse = await options.provider.sendMessage(systemPrompt, userPrompt, { model: options.model });
+    const decision = parseDecision(
+      rawResponse,
+      allSkills.map((entry) => entry.name)
+    );
+    const expected = testQuery.should_trigger ? skillName : "none";
+    const matched = testQuery.should_trigger ? decision === skillName : decision !== skillName;
+    results.push({
+      query: testQuery.query,
+      shouldTrigger: testQuery.should_trigger,
+      expected,
+      actual: decision,
+      matched,
+      rawModelResponse: options.verbose ? rawResponse : void 0
+    });
+  }
+  const metrics = calculateMetrics(skillName, results);
+  return {
+    skillName,
+    model: options.model,
+    provider: options.provider.name,
+    queries,
+    cases: results,
+    metrics,
+    suggestions: buildSuggestions(metrics)
+  };
+}
+
+// src/utils/config.ts
+function resolveApiKey(provider, override) {
+  if (override && override.trim() !== "") {
+    return override.trim();
+  }
+  if (provider === "anthropic") {
+    const envValue2 = process.env.ANTHROPIC_API_KEY?.trim();
+    if (envValue2) {
+      return envValue2;
+    }
+    throw new Error(
+      "No Anthropic API key found. Set ANTHROPIC_API_KEY environment variable or pass --api-key flag."
+    );
+  }
+  const envValue = process.env.OPENAI_API_KEY?.trim();
+  if (envValue) {
+    return envValue;
+  }
+  throw new Error("No OpenAI API key found. Set OPENAI_API_KEY environment variable or pass --api-key flag.");
+}
+
+// src/providers/anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+function wait(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function isRateLimitError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const maybeStatus = error.status;
+  if (maybeStatus === 429) {
+    return true;
+  }
+  const maybeMessage = error.message;
+  if (typeof maybeMessage === "string" && /rate limit/i.test(maybeMessage)) {
+    return true;
+  }
+  return false;
+}
+var AnthropicProvider = class {
+  name = "anthropic";
+  client;
+  constructor(apiKey) {
+    this.client = new Anthropic({ apiKey });
+  }
+  async sendMessage(systemPrompt, userMessage, options) {
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        const response = await this.client.messages.create({
+          model: options.model,
+          max_tokens: 2048,
+          system: systemPrompt,
+          messages: [
+            {
+              role: "user",
+              content: userMessage
+            }
+          ]
+        });
+        const textBlocks = response.content.filter((block) => block.type === "text");
+        const text = textBlocks.map((block) => block.text).join("\n").trim();
+        if (text.length === 0) {
+          throw new Error("Model returned an empty response.");
+        }
+        return text;
+      } catch (error) {
+        lastError = error;
+        if (!isRateLimitError(error) || attempt === 2) {
+          break;
+        }
+        const delay = Math.min(4e3, 500 * 2 ** attempt) + Math.floor(Math.random() * 250);
+        await wait(delay);
+      }
+    }
+    if (lastError instanceof Error) {
+      throw new Error(`Anthropic API call failed: ${lastError.message}`);
+    }
+    throw new Error("Anthropic API call failed with an unknown error.");
+  }
+};
+
+// src/providers/openai.ts
+var OpenAIProvider = class {
+  name = "openai";
+  _apiKey;
+  constructor(apiKey) {
+    this._apiKey = apiKey;
+  }
+  async sendMessage(_systemPrompt, _userMessage, _options) {
+    void this._apiKey;
+    throw new Error("OpenAI provider coming soon.");
+  }
+};
+
+// src/providers/index.ts
+function createProvider(providerName, apiKeyOverride) {
+  const apiKey = resolveApiKey(providerName, apiKeyOverride);
+  if (providerName === "anthropic") {
+    return new AnthropicProvider(apiKey);
+  }
+  return new OpenAIProvider(apiKey);
+}
+
+// src/commands/trigger.ts
+var triggerOptionsSchema = z3.object({
+  model: z3.string(),
+  provider: z3.enum(["anthropic", "openai"]),
+  queries: z3.string().optional(),
+  numQueries: z3.number().int().min(2),
+  saveQueries: z3.string().optional(),
+  verbose: z3.boolean().optional(),
+  apiKey: z3.string().optional()
+});
+function registerTriggerCommand(program) {
+  program.command("trigger").description("Evaluate whether a skill description triggers correctly.").argument("<path-to-skill>", "Path to SKILL.md or skill directory").option("--model <model>", "Model to use", "claude-sonnet-4-5-20250929").option("--provider <provider>", "LLM provider: anthropic|openai", "anthropic").option("--queries <path>", "Path to custom test queries JSON").option("--num-queries <n>", "Number of auto-generated queries", (value) => Number.parseInt(value, 10), 20).option("--save-queries <path>", "Save generated queries to a JSON file").option("--api-key <key>", "API key override").option("--verbose", "Show full model decisions").action(async (targetPath, commandOptions, command) => {
+    const globalOptions = getGlobalCliOptions(command);
+    const parsedOptions = triggerOptionsSchema.safeParse(commandOptions);
+    if (!parsedOptions.success) {
+      writeError(new Error(parsedOptions.error.issues[0]?.message ?? "Invalid trigger options."), globalOptions.json);
+      process.exitCode = 2;
+      return;
+    }
+    const options = parsedOptions.data;
+    const spinner = globalOptions.json || !process.stdout.isTTY ? null : ora("Preparing trigger evaluation...").start();
+    try {
+      if (options.numQueries % 2 !== 0) {
+        throw new Error("--num-queries must be an even number so the suite can split should/should-not trigger cases.");
+      }
+      if (spinner) {
+        spinner.text = "Parsing skill...";
+      }
+      const skill = await parseSkillStrict(targetPath);
+      if (spinner) {
+        spinner.text = "Initializing model provider...";
+      }
+      const provider = createProvider(options.provider, options.apiKey);
+      let queries = void 0;
+      if (options.queries) {
+        if (spinner) {
+          spinner.text = "Loading custom trigger queries...";
+        }
+        const loaded = await readJsonFile(options.queries);
+        const parsedQueries = triggerQueryArraySchema.safeParse(loaded);
+        if (!parsedQueries.success) {
+          throw new Error(`Invalid --queries JSON: ${parsedQueries.error.issues[0]?.message ?? "unknown format issue"}`);
+        }
+        queries = parsedQueries.data;
+      }
+      if (spinner) {
+        spinner.text = "Running trigger simulations...";
+      }
+      const result = await runTriggerTest(skill, {
+        model: options.model,
+        provider,
+        queries,
+        numQueries: options.numQueries,
+        verbose: Boolean(options.verbose)
+      });
+      if (options.saveQueries) {
+        await writeJsonFile(options.saveQueries, result.queries);
+      }
+      spinner?.stop();
+      if (globalOptions.json) {
+        writeResult(result, true);
+      } else {
+        writeResult(renderTriggerReport(result, globalOptions.color, Boolean(options.verbose)), false);
+      }
+    } catch (error) {
+      spinner?.stop();
+      writeError(error, globalOptions.json);
+      process.exitCode = 2;
+    }
+  });
+}
+
+// src/commands/eval.ts
+import ora2 from "ora";
+import { z as z6 } from "zod";
+
+// src/core/eval-runner.ts
+import { z as z5 } from "zod";
+
+// src/core/grader.ts
+import { z as z4 } from "zod";
+var gradedAssertionSchema = z4.object({
+  assertion: z4.string(),
+  passed: z4.boolean(),
+  evidence: z4.string()
+});
+var graderOutputSchema = z4.object({
+  assertions: z4.array(gradedAssertionSchema)
+});
+function extractJsonObject(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    return JSON.parse(trimmed);
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    return JSON.parse(trimmed.slice(start, end + 1));
+  }
+  throw new Error("Grader did not return a JSON object.");
+}
+async function gradeResponse(options) {
+  const assertionList = options.assertions && options.assertions.length > 0 ? options.assertions : [
+    "The response follows the skill instructions faithfully.",
+    "The response is well-structured and actionable.",
+    "The response addresses the user prompt directly."
+  ];
+  const systemPrompt = [
+    "You are a strict evaluator for agent skill outputs.",
+    "Assess each assertion and return JSON only.",
+    'Required output format: {"assertions":[{"assertion":"...","passed":true|false,"evidence":"..."}]}'
+  ].join(" ");
+  const userPrompt = [
+    `Skill: ${options.skillName}`,
+    "Skill instructions:",
+    options.skillBody,
+    "",
+    `User prompt: ${options.userPrompt}`,
+    "",
+    "Model response:",
+    options.modelResponse,
+    "",
+    "Assertions to evaluate:",
+    assertionList.map((assertion, index) => `${index + 1}. ${assertion}`).join("\n")
+  ].join("\n");
+  const raw = await options.provider.sendMessage(systemPrompt, userPrompt, { model: options.model });
+  const parsed = graderOutputSchema.safeParse(extractJsonObject(raw));
+  if (!parsed.success) {
+    throw new Error(`Failed to parse grader output: ${parsed.error.issues[0]?.message ?? "invalid grader JSON"}`);
+  }
+  return parsed.data.assertions;
+}
+
+// src/core/eval-runner.ts
+var evalPromptSchema = z5.object({
+  prompt: z5.string().min(1),
+  assertions: z5.array(z5.string().min(1)).optional()
+});
+var evalPromptArraySchema = z5.array(evalPromptSchema);
+function extractJsonArray(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return JSON.parse(trimmed);
+  }
+  const start = trimmed.indexOf("[");
+  const end = trimmed.lastIndexOf("]");
+  if (start >= 0 && end > start) {
+    return JSON.parse(trimmed.slice(start, end + 1));
+  }
+  throw new Error("Model did not return a JSON array.");
+}
+async function generatePrompts(skill, provider, model, count) {
+  const systemPrompt = [
+    "You generate realistic evaluation prompts for an agent skill.",
+    "Return JSON only.",
+    'Format: [{"prompt":"...","assertions":["...", "..."]}]',
+    "Assertions should be concrete and checkable."
+  ].join(" ");
+  const userPrompt = [
+    `Skill name: ${skill.frontmatter.name}`,
+    `Skill description: ${skill.frontmatter.description}`,
+    "Skill instructions:",
+    skill.content,
+    "",
+    `Generate ${count} prompts that stress the main capabilities and likely edge cases.`,
+    "Each prompt should include 2-4 assertions."
+  ].join("\n");
+  const raw = await provider.sendMessage(systemPrompt, userPrompt, { model });
+  const parsed = evalPromptArraySchema.safeParse(extractJsonArray(raw));
+  if (!parsed.success) {
+    throw new Error(`Failed to parse generated eval prompts: ${parsed.error.issues[0]?.message ?? "invalid prompt JSON"}`);
+  }
+  if (parsed.data.length !== count) {
+    throw new Error(`Expected ${count} prompts, got ${parsed.data.length}.`);
+  }
+  return parsed.data;
+}
+async function runEval(skill, options) {
+  const prompts = options.prompts && options.prompts.length > 0 ? evalPromptArraySchema.parse(options.prompts) : await generatePrompts(skill, options.provider, options.model, 5);
+  const results = [];
+  for (const evalPrompt of prompts) {
+    const systemPrompt = [
+      "You are an AI assistant with an activated skill.",
+      "Follow this SKILL.md content exactly where applicable.",
+      "",
+      skill.raw
+    ].join("\n");
+    const response = await options.provider.sendMessage(systemPrompt, evalPrompt.prompt, { model: options.model });
+    const gradedAssertions = await gradeResponse({
+      provider: options.provider,
+      model: options.graderModel,
+      skillName: skill.frontmatter.name,
+      skillBody: skill.content,
+      userPrompt: evalPrompt.prompt,
+      modelResponse: response,
+      assertions: evalPrompt.assertions
+    });
+    const passedAssertions2 = gradedAssertions.filter((assertion) => assertion.passed).length;
+    results.push({
+      prompt: evalPrompt.prompt,
+      assertions: gradedAssertions,
+      responseSummary: response.slice(0, 200),
+      response,
+      passedAssertions: passedAssertions2,
+      totalAssertions: gradedAssertions.length
+    });
+  }
+  const totalAssertions = results.reduce((total, result) => total + result.totalAssertions, 0);
+  const passedAssertions = results.reduce((total, result) => total + result.passedAssertions, 0);
+  return {
+    skillName: skill.frontmatter.name,
+    model: options.model,
+    graderModel: options.graderModel,
+    provider: options.provider.name,
+    prompts,
+    results,
+    summary: {
+      totalPrompts: results.length,
+      totalAssertions,
+      passedAssertions
+    }
+  };
+}
+
+// src/commands/eval.ts
+var evalOptionsSchema = z6.object({
+  prompts: z6.string().optional(),
+  model: z6.string(),
+  graderModel: z6.string().optional(),
+  provider: z6.enum(["anthropic", "openai"]),
+  saveResults: z6.string().optional(),
+  verbose: z6.boolean().optional(),
+  apiKey: z6.string().optional()
+});
+function registerEvalCommand(program) {
+  program.command("eval").description("Run end-to-end skill execution and quality evaluation.").argument("<path-to-skill>", "Path to SKILL.md or skill directory").option("--prompts <path>", "Path to eval prompts JSON").option("--model <model>", "Model to execute prompts", "claude-sonnet-4-5-20250929").option("--grader-model <model>", "Model used for grading (defaults to --model)").option("--provider <provider>", "LLM provider: anthropic|openai", "anthropic").option("--save-results <path>", "Save full evaluation results to JSON").option("--api-key <key>", "API key override").option("--verbose", "Show full model responses").action(async (targetPath, commandOptions, command) => {
+    const globalOptions = getGlobalCliOptions(command);
+    const parsedOptions = evalOptionsSchema.safeParse(commandOptions);
+    if (!parsedOptions.success) {
+      writeError(new Error(parsedOptions.error.issues[0]?.message ?? "Invalid eval options."), globalOptions.json);
+      process.exitCode = 2;
+      return;
+    }
+    const options = parsedOptions.data;
+    const spinner = globalOptions.json || !process.stdout.isTTY ? null : ora2("Preparing evaluation...").start();
+    try {
+      if (spinner) {
+        spinner.text = "Parsing skill...";
+      }
+      const skill = await parseSkillStrict(targetPath);
+      if (spinner) {
+        spinner.text = "Initializing model provider...";
+      }
+      const provider = createProvider(options.provider, options.apiKey);
+      let prompts = void 0;
+      if (options.prompts) {
+        if (spinner) {
+          spinner.text = "Loading test prompts...";
+        }
+        const loaded = await readJsonFile(options.prompts);
+        const parsedPrompts = evalPromptArraySchema.safeParse(loaded);
+        if (!parsedPrompts.success) {
+          throw new Error(`Invalid --prompts JSON: ${parsedPrompts.error.issues[0]?.message ?? "unknown format issue"}`);
+        }
+        prompts = parsedPrompts.data;
+      }
+      if (spinner) {
+        spinner.text = "Running eval prompts and grading responses...";
+      }
+      const result = await runEval(skill, {
+        provider,
+        model: options.model,
+        graderModel: options.graderModel ?? options.model,
+        prompts
+      });
+      if (options.saveResults) {
+        await writeJsonFile(options.saveResults, result);
+      }
+      spinner?.stop();
+      if (globalOptions.json) {
+        writeResult(result, true);
+      } else {
+        writeResult(renderEvalReport(result, globalOptions.color, Boolean(options.verbose)), false);
+      }
+    } catch (error) {
+      spinner?.stop();
+      writeError(error, globalOptions.json);
+      process.exitCode = 2;
+    }
+  });
+}
+
+// src/index.ts
+function resolveVersion() {
+  try {
+    const currentFilePath = fileURLToPath(import.meta.url);
+    const packageJsonPath = path5.resolve(path5.dirname(currentFilePath), "..", "package.json");
+    const raw = fs5.readFileSync(packageJsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+async function run(argv) {
+  const program = new Command();
+  program.name("skilltest").description("The testing framework for Agent Skills.").version(resolveVersion()).option("--json", "Output results as JSON").option("--no-color", "Disable colored output").showHelpAfterError();
+  registerLintCommand(program);
+  registerTriggerCommand(program);
+  registerEvalCommand(program);
+  await program.parseAsync(argv);
+}
+run(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Error: ${message}
+`);
+  process.exitCode = 2;
+});
+export {
+  run
+};
+//# sourceMappingURL=index.js.map