skillmds 0.1.1 → 1.0.1

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "skillmds",
-  "version": "0.1.1",
-  "description": "Official MCP server for SkillMD — search, fetch, and install Agent Skills (SKILL.md) from skillmd.com inside any MCP-capable agent.",
+  "version": "1.0.1",
+  "description": "SkillMD for agents: the `skillmds` MCP server + the `skillmd` CLI (lint, scan, search, install, publish Agent Skills) from skillmd.com.",
   "type": "module",
   "bin": {
-    "skillmds": "bin/skillmd-mcp.mjs"
+    "skillmds": "bin/skillmd-mcp.mjs",
+    "skillmd": "bin/skillmd.mjs"
   },
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "cli",
     "agent-skills",
     "skill.md",
     "skillmd",
+    "lint",
+    "validator",
+    "sarif",
     "claude",
     "claude-code",
     "cursor",
@@ -22,9 +27,22 @@
   "bugs": { "url": "https://skillmd.com/contact" },
   "author": "SkillMD",
   "license": "MIT",
-  "files": ["bin", "README.md"],
+  "files": ["bin", "dist", "vendor", "README.md"],
   "engines": { "node": ">=18" },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.0"
+    "@clack/prompts": "^0.8.0",
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "commander": "^12.1.0",
+    "giget": "^1.2.0",
+    "picocolors": "^1.1.0",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@skillmd/core": "*",
+    "tsup": "^8.3.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "tsup"
   }
 }

package/vendor/index.js

@@ -0,0 +1,297 @@
+// ../../packages/core/src/parse.ts
+import { parse as parseYaml } from "yaml";
+var MAX_SKILL_BYTES = 256 * 1024;
+var MAX_DESCRIPTION = 500;
+var MAX_NAME = 120;
+var slugify = (s) => String(s).toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "skill";
+function parseSkillMd(raw, type = "single") {
+  if (!raw || raw.length > MAX_SKILL_BYTES) return { error: "SKILL.md missing or too large (max 256KB)" };
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return { error: "Missing YAML frontmatter (--- ... ---)" };
+  let fm;
+  try {
+    fm = parseYaml(m[1] ?? "") ?? {};
+  } catch {
+    return { error: "Invalid YAML frontmatter" };
+  }
+  const name = String(fm.name ?? "").trim();
+  const description = String(fm.description ?? "").replace(/\s+/g, " ").trim();
+  if (!name) return { error: "frontmatter 'name' is required" };
+  if (!description) return { error: "frontmatter 'description' is required" };
+  if (description.length > MAX_DESCRIPTION) return { error: "description must be <= 500 chars" };
+  return {
+    name: name.slice(0, MAX_NAME),
+    description: description.slice(0, MAX_DESCRIPTION),
+    license: fm.license ? String(fm.license).slice(0, 64) : null,
+    body: m[2] ?? "",
+    type
+  };
+}
+var CATEGORY_KEYWORDS = [
+  ["devops", /docker|kubernetes|k8s|terraform|ci\/cd|deploy|helm|pipeline/i],
+  ["data", /\b(csv|xlsx|excel|spreadsheet|sql|dataframe|pandas|etl|analytics)\b/i],
+  ["docs", /\b(docx|word|pdf|markdown|report|documentation|slides?|pptx)\b/i],
+  ["web", /\b(html|css|react|vue|svelte|frontend|browser|tailwind|a11y)\b/i],
+  ["ai-ml", /\b(llm|embedding|rag|prompt|agent|fine-?tune|model|mcp)\b/i],
+  ["security", /\b(security|vulnerabilit|secret|audit|owasp|exploit|xss)\b/i],
+  ["design", /\b(image|figma|design|video|audio|svg|canvas)\b/i],
+  ["research", /\b(research|citation|summari[sz]e|knowledge)\b/i],
+  ["finance", /\b(invoice|account|financ|budget|revenue|business)\b/i],
+  ["integrations", /\b(api|webhook|graphql|rest|integration|oauth|slack)\b/i],
+  ["productivity", /\b(email|calendar|todo|task|notion|workflow)\b/i],
+  ["coding", /\b(code|refactor|test|debug|lint|typescript|python|rust|golang)\b/i]
+];
+function categorize(text) {
+  for (const [slug, re] of CATEGORY_KEYWORDS) if (re.test(text)) return slug;
+  return "coding";
+}
+
+// ../../packages/core/src/security.ts
+var RULES = [
+  ["executes_scripts", /```(?:sh|bash|python|py|js|ts|ruby|rb)\b|\b(subprocess|os\.system|child_process|exec\()/i],
+  ["network_calls", /\b(fetch|requests\.|urllib|axios|curl|wget|https?:\/\/|websocket)\b/i],
+  ["reads_secrets", /\b(api[_-]?key|secret|token|password|os\.environ|process\.env|getenv)\b/i]
+];
+function scanSecurity(body) {
+  const findings = [];
+  body.split(/\r?\n/).forEach((text, i) => {
+    for (const [flag, re] of RULES) {
+      if (re.test(text)) findings.push({ flag, line: i + 1, snippet: text.trim().slice(0, 120) });
+    }
+  });
+  const flags = [...new Set(findings.map((f) => f.flag))];
+  return { flags: flags.length ? flags : ["docs_only"], findings };
+}
+
+// ../../packages/core/src/rules.ts
+function utf8Bytes(s) {
+  let bytes = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 128) bytes += 1;
+    else if (c < 2048) bytes += 2;
+    else if (c >= 55296 && c <= 56319) {
+      bytes += 4;
+      i++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+var diag = (rule, message, line) => ({
+  id: rule.id,
+  severity: rule.severity,
+  message,
+  ...line !== void 0 ? { line } : {}
+});
+var RULES2 = [
+  {
+    id: "SK002",
+    severity: "error",
+    description: "name must be present and \u2264 120 chars",
+    check(s, _ctx) {
+      const out = [];
+      if (!s.name.trim()) out.push(diag(this, "frontmatter 'name' is required"));
+      else if (s.name.length > MAX_NAME) out.push(diag(this, `name must be \u2264 ${MAX_NAME} chars`));
+      return out;
+    }
+  },
+  {
+    id: "SK003",
+    severity: "error",
+    description: "description must be present and \u2264 500 chars",
+    check(s, _ctx) {
+      const out = [];
+      if (!s.description.trim()) out.push(diag(this, "frontmatter 'description' is required"));
+      else if (s.description.length > MAX_DESCRIPTION) out.push(diag(this, `description must be \u2264 ${MAX_DESCRIPTION} chars`));
+      return out;
+    }
+  },
+  {
+    id: "SK010",
+    severity: "warn",
+    description: "description should be \u2265 20 chars (not too terse)",
+    check(s, _ctx) {
+      return s.description.trim().length > 0 && s.description.trim().length < 20 ? [diag(this, "description is very terse (< 20 chars); add more detail to help discovery")] : [];
+    }
+  },
+  {
+    id: "SK011",
+    severity: "warn",
+    description: "license should be declared in frontmatter",
+    check(s, _ctx) {
+      return s.license ? [] : [diag(this, "no 'license' declared in frontmatter")];
+    }
+  },
+  {
+    id: "SK020",
+    severity: "warn",
+    description: "body should be \u2265 200 chars (not a stub)",
+    check(s, _ctx) {
+      return s.body.trim().length < 200 ? [diag(this, "body is very short (< 200 chars); this looks like a stub")] : [];
+    }
+  },
+  {
+    id: "SK021",
+    severity: "warn",
+    description: "body should contain at least one Markdown heading",
+    check(s, _ctx) {
+      return /^#{1,6}\s/m.test(s.body) ? [] : [diag(this, "body has no Markdown headings; add structure with '#' headings")];
+    }
+  },
+  {
+    id: "SK030",
+    severity: "error",
+    description: "total SKILL.md size must be \u2264 256KB",
+    check(s, _ctx) {
+      return utf8Bytes(s.body) > MAX_SKILL_BYTES ? [diag(this, "SKILL.md exceeds 256KB")] : [];
+    }
+  },
+  {
+    id: "SK040",
+    severity: "warn",
+    description: "name should match its directory/slug",
+    check(s, ctx) {
+      if (!ctx.slug) return [];
+      const expected = slugify(s.name);
+      return expected === ctx.slug ? [] : [diag(this, `name slug '${expected}' does not match directory '${ctx.slug}'`)];
+    }
+  }
+];
+function runRules(skill, ctx = {}) {
+  return RULES2.flatMap((r) => r.check(skill, ctx));
+}
+
+// ../../packages/core/src/quality.ts
+var WEIGHT = {
+  error: 25,
+  warn: 8,
+  info: 2
+};
+function qualityScore(diagnostics) {
+  const penalty = diagnostics.reduce((sum, d) => sum + WEIGHT[d.severity], 0);
+  return Math.max(0, Math.min(100, 100 - penalty));
+}
+
+// ../../packages/core/src/lint.ts
+function lint(raw, opts = {}) {
+  const parsed = parseSkillMd(raw, opts.type ?? "single");
+  if ("error" in parsed) {
+    const diagnostics2 = [{ id: "SK001", severity: "error", message: parsed.error }];
+    return {
+      ok: false,
+      diagnostics: diagnostics2,
+      security: scanSecurity(raw),
+      score: qualityScore(diagnostics2)
+    };
+  }
+  const ctx = opts.slug !== void 0 ? { slug: opts.slug } : {};
+  const diagnostics = runRules(parsed, ctx);
+  const security = scanSecurity(parsed.body);
+  const ok = !diagnostics.some((d) => d.severity === "error");
+  return { ok, skill: parsed, diagnostics, security, score: qualityScore(diagnostics) };
+}
+
+// ../../packages/core/src/format/text.ts
+var BADGE = { error: "ERROR", warn: " WARN", info: " INFO" };
+function toText(results, opts = {}) {
+  const paint = opts.decorate ?? ((t) => t);
+  const out = [];
+  for (const { file, result } of results) {
+    const status = result.ok ? paint("PASS", "ok") : paint("FAIL", "error");
+    out.push(`${status}  ${file}  ${paint(`score ${result.score}/100`, "dim")}`);
+    for (const d of result.diagnostics) {
+      const where = d.line !== void 0 ? `:${d.line}` : "";
+      out.push(`  ${paint(BADGE[d.severity], d.severity)}  ${d.id}${where}  ${d.message}`);
+    }
+    if (result.security.flags.length && result.security.flags[0] !== "docs_only") {
+      out.push(`  ${paint("SEC ", "warn")}  flags: ${result.security.flags.join(", ")}`);
+    }
+    out.push("");
+  }
+  const failed = results.filter((r) => !r.result.ok).length;
+  const summary = failed === 0 ? paint(`\u2713 ${results.length} skill(s) passed`, "ok") : paint(`\u2717 ${failed}/${results.length} skill(s) failed`, "error");
+  out.push(summary);
+  return out.join("\n");
+}
+
+// ../../packages/core/src/format/json.ts
+function toJson(results) {
+  return results.map(({ file, result }) => ({
+    file,
+    ok: result.ok,
+    score: result.score,
+    diagnostics: result.diagnostics,
+    security: result.security
+  }));
+}
+
+// ../../packages/core/src/format/sarif.ts
+var SARIF_LEVEL = { error: "error", warn: "warning", info: "note" };
+function toSarif(results) {
+  const sarifResults = results.flatMap(
+    ({ file, result }) => result.diagnostics.map((d) => ({
+      ruleId: d.id,
+      level: SARIF_LEVEL[d.severity] ?? "note",
+      message: { text: d.message },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: file },
+            region: { startLine: d.line ?? 1 }
+          }
+        }
+      ]
+    }))
+  );
+  return {
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "skillmd",
+            informationUri: "https://skillmd.com",
+            rules: RULES2.map((r) => ({
+              id: r.id,
+              shortDescription: { text: r.description },
+              defaultConfiguration: { level: SARIF_LEVEL[r.severity] ?? "note" }
+            }))
+          }
+        },
+        results: sarifResults
+      }
+    ]
+  };
+}
+
+// ../../packages/core/src/format/github.ts
+var LEVEL = { error: "error", warn: "warning", info: "notice" };
+function toGithub(results) {
+  const lines = [];
+  for (const { file, result } of results) {
+    for (const d of result.diagnostics) {
+      const level = LEVEL[d.severity] ?? "notice";
+      const loc = d.line !== void 0 ? `,line=${d.line}` : "";
+      lines.push(`::${level} file=${file}${loc},title=${d.id}::${d.message}`);
+    }
+  }
+  return lines.join("\n");
+}
+export {
+  MAX_DESCRIPTION,
+  MAX_NAME,
+  MAX_SKILL_BYTES,
+  RULES2 as RULES,
+  categorize,
+  lint,
+  parseSkillMd,
+  qualityScore,
+  runRules,
+  scanSecurity,
+  slugify,
+  toGithub,
+  toJson,
+  toSarif,
+  toText
+};