@sagargupta1610/skillcheck 0.2.0

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+import {
+  checkEvals,
+  crossSkillFindings,
+  initEvals,
+  lintSkillDir,
+  toSarif
+} from "./chunk-MGSKVMAQ.js";
+
+// src/cli.ts
+import { appendFile, readFile, stat, writeFile } from "fs/promises";
+import { join } from "path";
+import { Command } from "commander";
+import { glob } from "glob";
+var VERSION = "0.2.0";
+var program = new Command();
+program.name("skillcheck").description("Conformance suite for Agent Skills (SKILL.md)").version(VERSION);
+program.command("lint").description(
+  "Lint one or more skill directories against the Agent Skills spec"
+).argument(
+  "<paths...>",
+  "skill directories (or parents containing */SKILL.md)"
+).option("--strict", "deprecated alias for --profile strict (default)", false).option(
+  "--profile <profile>",
+  "strict (skills-ref parity) | lenient (client-guide)",
+  "strict"
+).option(
+  "--format <format>",
+  "output format: pretty | concise | json | github | sarif",
+  "pretty"
+).option(
+  "--fail-on <severity>",
+  "minimum severity that fails: error | warning | never",
+  "error"
+).option("--sarif <path>", "also write a SARIF 2.1.0 report to this path").option("--max-warnings <n>", "fail when warnings exceed this count").action(async (paths, opts) => {
+  const skillDirs = await expandSkillDirs(paths);
+  if (skillDirs.length === 0) {
+    console.error("no SKILL.md found under the given paths");
+    process.exit(2);
+  }
+  const profile = opts.profile === "lenient" ? "lenient" : "strict";
+  const config = await loadConfig();
+  const results = [];
+  for (const dir of skillDirs) {
+    const result = await lintSkillDir(dir, {
+      profile,
+      ...config?.rules ? { ruleOverrides: config.rules } : {}
+    });
+    result.findings.push(...await checkEvals(dir, result.skillName));
+    recount(result);
+    results.push(result);
+  }
+  crossSkillFindings(results);
+  if (opts.sarif) {
+    await writeFile(opts.sarif, toSarif(results, VERSION), "utf8");
+  }
+  report(results, opts.format);
+  await emitGithubOutputs(results);
+  const errors = results.reduce((s, r) => s + r.errorCount, 0);
+  const warnings = results.reduce((s, r) => s + r.warningCount, 0);
+  const maxWarnings = opts.maxWarnings === void 0 ? Number.POSITIVE_INFINITY : Number(opts.maxWarnings);
+  let failed = false;
+  if (opts.failOn === "never") failed = false;
+  else if (opts.failOn === "warning") failed = errors > 0 || warnings > 0;
+  else failed = errors > 0;
+  if (warnings > maxWarnings) failed = true;
+  process.exit(failed ? 1 : 0);
+});
+var evalCmd = program.command("eval").description("Trigger-test definitions for skills");
+evalCmd.command("init").description(
+  "Scaffold evals/evals.json for a skill (skill-creator-compatible format)"
+).argument("<skill-dir>", "skill directory").action(async (dir) => {
+  try {
+    const path = await initEvals(dir);
+    console.log(`created ${path}`);
+    console.log(
+      "Fill in the REPLACE placeholders: 3 explicit / 3 implicit / 3 contextual / 4 negative triggers."
+    );
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(2);
+  }
+});
+evalCmd.command("check").description("Validate evals/evals.json against the schema").argument("<skill-dir>", "skill directory").action(async (dir) => {
+  const result = await lintSkillDir(dir);
+  const findings = await checkEvals(dir, result.skillName);
+  if (findings.length === 0) {
+    console.log("evals.json ok (or absent)");
+    process.exit(0);
+  }
+  for (const f of findings) {
+    console.log(
+      `${f.severity === "error" ? "ERR " : "WARN"} [${f.code}] ${f.message}`
+    );
+  }
+  process.exit(findings.some((f) => f.severity === "error") ? 1 : 0);
+});
+async function loadConfig() {
+  try {
+    const raw = await readFile("skillcheck.config.json", "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function expandSkillDirs(paths) {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const p of paths) {
+    if (await exists(join(p, "SKILL.md")) || await exists(join(p, "skill.md"))) {
+      dirs.add(p);
+      continue;
+    }
+    const matches = await glob("**/{SKILL,skill}.md", {
+      cwd: p,
+      ignore: ["**/node_modules/**", "**/.git/**"],
+      absolute: true
+    });
+    for (const m of matches) {
+      dirs.add(join(m, ".."));
+    }
+  }
+  return [...dirs].sort();
+}
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+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;
+}
+async function emitGithubOutputs(results) {
+  const errors = results.reduce((s, r) => s + r.errorCount, 0);
+  const warnings = results.reduce((s, r) => s + r.warningCount, 0);
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (outputPath) {
+    await appendFile(
+      outputPath,
+      `error-count=${errors}
+warning-count=${warnings}
+`,
+      "utf8"
+    );
+  }
+  const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryPath) {
+    const lines = [
+      "## skillcheck",
+      "",
+      `**${results.length}** skill(s) checked: **${errors}** error(s), **${warnings}** warning(s)`,
+      ""
+    ];
+    const withFindings = results.filter((r) => r.findings.length > 0);
+    if (withFindings.length > 0) {
+      lines.push(
+        "| Skill | Rule | Severity | Message |",
+        "| --- | --- | --- | --- |"
+      );
+      for (const r of withFindings) {
+        for (const f of r.findings.slice(0, 50)) {
+          lines.push(
+            `| ${r.skillName ?? r.skillDir} | ${f.code} | ${f.severity} | ${f.message.replace(/\|/g, "\\|")} |`
+          );
+        }
+      }
+    }
+    await appendFile(summaryPath, `${lines.join("\n")}
+`, "utf8");
+  }
+}
+function report(results, format) {
+  if (format === "json") {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  if (format === "sarif") {
+    console.log(toSarif(results, VERSION));
+    return;
+  }
+  if (format === "github") {
+    for (const r of results) {
+      for (const f of r.findings) {
+        const level = f.severity === "error" ? "error" : f.severity === "warning" ? "warning" : "notice";
+        const file = join(r.skillDir, f.file);
+        console.log(
+          `::${level} file=${file},line=${f.line ?? 1},title=${f.code} ${f.alias}::${f.message}`
+        );
+      }
+    }
+    return;
+  }
+  if (format === "concise") {
+    for (const r of results) {
+      for (const f of r.findings) {
+        const glyph = f.severity === "error" ? "x" : f.severity === "warning" ? "!" : "-";
+        console.log(
+          `${glyph} ${r.skillDir}/${f.file}:${f.line ?? 1}: ${f.code} (${f.alias}): ${f.message}`
+        );
+      }
+    }
+    printTotals(results);
+    return;
+  }
+  for (const r of results) {
+    const label = r.skillName ?? "(unnamed)";
+    if (r.findings.length === 0) {
+      console.log(`ok   ${label}  ${r.skillDir}`);
+      continue;
+    }
+    console.log(`
+${label}  ${r.skillDir}`);
+    for (const f of r.findings) {
+      const tag = f.severity === "error" ? "ERR " : f.severity === "warning" ? "WARN" : "INFO";
+      console.log(`  ${tag} [${f.code} ${f.alias}] ${f.message}`);
+      if (f.suggestion) console.log(`       fix: ${f.suggestion}`);
+    }
+  }
+  printTotals(results);
+}
+function printTotals(results) {
+  const errors = results.reduce((s, r) => s + r.errorCount, 0);
+  const warnings = results.reduce((s, r) => s + r.warningCount, 0);
+  const infos = results.reduce((s, r) => s + r.infoCount, 0);
+  console.log(
+    `
+${results.length} skill(s) checked: ${errors} error(s), ${warnings} warning(s), ${infos} info`
+  );
+}
+program.parseAsync().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(2);
+});

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+
+/** Severity tiers: `error` = skills-ref 0.1.0 strict parity, `warning` =
+ * beyond-parity checks + client-guide lenient downgrades, `info` = advisory
+ * heuristics that never gate CI. */
+type Severity = "error" | "warning" | "info";
+/** Lint profile: `strict` = skills-ref parity (default), `lenient` =
+ * client-implementation-guide behavior (name-too-long and dir-mismatch
+ * downgrade to warnings; extension fields stay warnings). */
+type Profile = "strict" | "lenient";
+interface RuleMeta {
+    /** Stable code, e.g. "SC013". Never renumbered or recycled. */
+    code: string;
+    /** Kebab-case alias, interchangeable with the code everywhere. */
+    alias: string;
+    /** Default severity under the strict profile. */
+    severity: Severity;
+    /** Severity under the lenient profile (defaults to `severity`). */
+    lenientSeverity?: Severity;
+    /** Autofix classification; v0.2 tags but does not fix. */
+    fixable: "safe" | "unsafe" | null;
+    summary: string;
+}
+interface Finding {
+    code: string;
+    alias: string;
+    severity: Severity;
+    message: string;
+    /** Path of the file the finding is anchored to, relative to the skill dir. */
+    file: string;
+    line?: number;
+    /** Optional fix-it suggestion printed in pretty output. */
+    suggestion?: string;
+}
+interface LintResult {
+    skillDir: string;
+    skillName: string | null;
+    findings: Finding[];
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+}
+interface LintOptions {
+    /** Lint profile. Default "strict" (skills-ref parity). */
+    profile?: Profile;
+    /** Per-rule severity overrides from config: code/alias -> off|warn|error. */
+    ruleOverrides?: Record<string, "off" | "warn" | "error" | "info">;
+}
+/** Parsed SKILL.md frontmatter. Unknown fields are preserved for rule checks. */
+interface SkillFrontmatter {
+    name?: unknown;
+    description?: unknown;
+    license?: unknown;
+    compatibility?: unknown;
+    metadata?: unknown;
+    "allowed-tools"?: unknown;
+    [key: string]: unknown;
+}
+interface ParsedSkill {
+    frontmatter: SkillFrontmatter | null;
+    /** skills-ref-parity parse error message, if frontmatter is unusable. */
+    parseError: string | null;
+    /** Raw frontmatter text (for raw-text scans like SC021). */
+    rawFrontmatter: string;
+    /** Markdown body (everything after the closing frontmatter fence). */
+    body: string;
+    /** 1-based line number where the body starts. */
+    bodyStartLine: number;
+}
+
+/** Validate evals/evals.json against the schema + semantic rules.
+ * Returns findings (empty when the file is absent -- evals are optional). */
+declare function checkEvals(skillDir: string, skillName: string | null): Promise<Finding[]>;
+/** Scaffold evals/evals.json for a skill (skill-creator-compatible). */
+declare function initEvals(skillDir: string, skillName?: string): Promise<string>;
+
+declare const evalsFileSchema: z.ZodObject<{
+    skill_name: z.ZodString;
+    settings: z.ZodOptional<z.ZodObject<{
+        runs_per_prompt: z.ZodOptional<z.ZodNumber>;
+        trigger_threshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    evals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        prompt: z.ZodString;
+        expected_output: z.ZodOptional<z.ZodString>;
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        expectations: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>>>;
+    triggers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            explicit: "explicit";
+            implicit: "implicit";
+            contextual: "contextual";
+            negative: "negative";
+        }>;
+        prompt: z.ZodString;
+        should_trigger: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+
+/** Typed registry of known client extension fields (beyond the agentskills.io
+ * spec). Drives SC301 (known extension, warning) and SC302 (invalid extension
+ * value). Sources: code.claude.com/docs skills pages, Cursor/Copilot/OpenCode
+ * docs, verified 2026-07-06. */
+interface ExtensionField {
+    /** Expected JS type(s) after YAML parse. */
+    type: "string" | "boolean" | "string-or-array" | "object" | "enum";
+    /** For enum type: allowed values. */
+    values?: string[];
+    /** Runtimes that read this field. */
+    runtimes: string[];
+    deprecated?: string;
+}
+declare const KNOWN_EXTENSIONS: Record<string, ExtensionField>;
+/** Spec-official frontmatter fields (ALLOWED_FIELDS in skills-ref). */
+declare const SPEC_FIELDS: Set<string>;
+
+/** Lint a single skill directory containing a SKILL.md (or skill.md). */
+declare function lintSkillDir(dir: string, options?: LintOptions): Promise<LintResult>;
+/** Cross-skill checks over a set of results (SC105 duplicate names). */
+declare function crossSkillFindings(results: LintResult[]): void;
+
+/** Split a SKILL.md source into frontmatter + body, replicating skills-ref
+ * parser.py semantics exactly (split-based, error strings verbatim). */
+declare function parseSkillMd(source: string): ParsedSkill;
+
+/** Rule registry: codes are stable, never renumbered or recycled.
+ * SC0xx frontmatter, SC1xx structure/references, SC2xx body, SC3xx extensions. */
+declare const RULES: RuleMeta[];
+declare function getRule(codeOrAlias: string): RuleMeta | undefined;
+
+/** Emit SARIF 2.1.0 (the only version GitHub code scanning accepts).
+ * Paths are repo-relative with forward slashes -- path stability keeps
+ * alerts from churning. */
+declare function toSarif(results: LintResult[], version: string, cwd?: string): string;
+
+export { type Finding, KNOWN_EXTENSIONS, type LintOptions, type LintResult, type ParsedSkill, type Profile, RULES, type RuleMeta, SPEC_FIELDS, type Severity, type SkillFrontmatter, checkEvals, crossSkillFindings, evalsFileSchema, getRule, initEvals, lintSkillDir, parseSkillMd, toSarif };

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  KNOWN_EXTENSIONS,
+  RULES,
+  SPEC_FIELDS,
+  checkEvals,
+  crossSkillFindings,
+  evalsFileSchema,
+  getRule,
+  initEvals,
+  lintSkillDir,
+  parseSkillMd,
+  toSarif
+} from "./chunk-MGSKVMAQ.js";
+export {
+  KNOWN_EXTENSIONS,
+  RULES,
+  SPEC_FIELDS,
+  checkEvals,
+  crossSkillFindings,
+  evalsFileSchema,
+  getRule,
+  initEvals,
+  lintSkillDir,
+  parseSkillMd,
+  toSarif
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@sagargupta1610/skillcheck",
+  "version": "0.2.0",
+  "description": "Conformance suite for Agent Skills: lint SKILL.md against the spec, run it against real agent runtimes, publish a compatibility matrix",
+  "keywords": [
+    "agent-skills",
+    "skill",
+    "SKILL.md",
+    "claude-code",
+    "conformance",
+    "lint",
+    "agents"
+  ],
+  "license": "MIT",
+  "author": "Sagar Gupta <sg85207@gmail.com> (https://github.com/Sagargupta16)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sagargupta16/skillcheck.git"
+  },
+  "type": "module",
+  "bin": {
+    "skillcheck": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.10.0",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "glob": "^13.0.6",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
+    "@types/node": "^26.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}