guardskills 1.1.0 → 1.2.0

package/dist/cli.js

@@ -176,9 +176,13 @@ function enforceSourcePolicy(repoInput, policy) {
 
 // src/install/skills.ts
 import { execa } from "execa";
-async function runSkillsInstall(repo, skill) {
+async function runProviderInstall(provider, repo, skill) {
+  if (provider === "playbooks" && !skill) {
+    return 30;
+  }
+  const args = provider === "skills" ? skill ? ["skills", "add", repo, "--skill", skill] : ["skills", "add", repo] : provider === "playbooks" ? ["playbooks", "add", "skill", repo, "--skill", skill] : provider === "skillkit" ? skill ? ["skillkit", "install", repo, "--skill", skill] : ["skillkit", "install", repo] : skill ? ["openskills", "install", repo, skill] : ["openskills", "install", repo];
   try {
-    await execa("npx", ["skills", "add", repo, "--skill", skill], {
+    await execa("npx", args, {
       stdio: "inherit"
     });
     return 0;
@@ -1043,6 +1047,22 @@ var cliAddOptionsSchema = z2.object({
   maxAuxFiles: z2.coerce.number().int().min(1).max(200).optional(),
   maxTotalFiles: z2.coerce.number().int().min(1).max(400).optional()
 });
+var cliBulkAddOptionsSchema = z2.object({
+  config: z2.string().optional(),
+  strict: z2.boolean().optional(),
+  ci: z2.boolean().optional(),
+  json: z2.boolean().optional(),
+  yes: z2.boolean().optional(),
+  dryRun: z2.boolean().optional(),
+  force: z2.boolean().optional(),
+  allowUnverifiable: z2.boolean().optional(),
+  githubTimeoutMs: z2.coerce.number().int().min(1e3).max(12e4).optional(),
+  githubRetries: z2.coerce.number().int().min(0).max(6).optional(),
+  githubRetryBaseMs: z2.coerce.number().int().min(50).max(5e3).optional(),
+  maxFileBytes: z2.coerce.number().int().min(4096).max(5e6).optional(),
+  maxAuxFiles: z2.coerce.number().int().min(1).max(200).optional(),
+  maxTotalFiles: z2.coerce.number().int().min(1).max(400).optional()
+});
 var effectiveAddOptionsSchema = z2.object({
   skill: z2.string().min(1),
   strict: z2.boolean(),
@@ -1162,9 +1182,11 @@ function evaluateGate(level, options) {
     gateNote: level === "WARNING" ? "WARNING accepted via --yes." : "SAFE to proceed."
   };
 }
-async function runAddCommand(repo, rawOptions) {
+async function runAddCommand(repo, rawOptions, context = {}) {
   const cliOptions = cliAddOptionsSchema.parse(rawOptions);
   const loadedConfig = loadGuardSkillsConfig(cliOptions.config);
+  const provider = context.provider ?? "skills";
+  const commandName = context.commandName ?? "guardskills add";
   const options = resolveEffectiveAddOptions(cliOptions, loadedConfig.config);
   enforceSourcePolicy(repo, loadedConfig.config.policy);
   enforceOptionPolicy(options, loadedConfig.config);
@@ -1185,7 +1207,7 @@ async function runAddCommand(repo, rawOptions) {
   const gate = evaluateGate(decision.level, options);
   const configNote = loadedConfig.path ? ` Config: ${loadedConfig.path}` : "";
   const report = {
-    command: "guardskills add",
+    command: commandName,
     repo,
     skill: options.skill,
     strict: options.strict,
@@ -1210,14 +1232,353 @@ async function runAddCommand(repo, rawOptions) {
   if (options.dryRun || options.ci) {
     return 0;
   }
-  return runSkillsInstall(repo, options.skill);
+  return runProviderInstall(provider, repo, options.skill);
 }
 
-// src/commands/scan-clawhub.ts
+// src/commands/openskills-install.ts
+import fs2 from "fs";
+import os from "os";
+import path4 from "path";
+import { execa as execa2 } from "execa";
 import { z as z3 } from "zod";
+var ALLOWED_TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([
+  ".md",
+  ".txt",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".ps1",
+  ".py",
+  ".js",
+  ".ts",
+  ".mjs",
+  ".cjs",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".ini",
+  ".cfg"
+]);
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", ".next", ".turbo"]);
+var cliOpenSkillsOptionsSchema = z3.object({
+  config: z3.string().optional(),
+  strict: z3.boolean().optional(),
+  ci: z3.boolean().optional(),
+  json: z3.boolean().optional(),
+  yes: z3.boolean().optional(),
+  dryRun: z3.boolean().optional(),
+  force: z3.boolean().optional(),
+  allowUnverifiable: z3.boolean().optional(),
+  githubTimeoutMs: z3.coerce.number().int().min(1e3).max(12e4).optional(),
+  githubRetries: z3.coerce.number().int().min(0).max(6).optional(),
+  githubRetryBaseMs: z3.coerce.number().int().min(50).max(5e3).optional(),
+  maxFileBytes: z3.coerce.number().int().min(4096).max(5e6).optional(),
+  maxAuxFiles: z3.coerce.number().int().min(1).max(200).optional(),
+  maxTotalFiles: z3.coerce.number().int().min(1).max(400).optional()
+});
+var DEFAULT_OPTIONS2 = {
+  strict: false,
+  ci: false,
+  json: false,
+  yes: false,
+  dryRun: false,
+  force: false,
+  allowUnverifiable: false,
+  githubTimeoutMs: 15e3,
+  githubRetries: 2,
+  githubRetryBaseMs: 300,
+  maxFileBytes: 25e4,
+  maxAuxFiles: 40,
+  maxTotalFiles: 120
+};
+function resolveEffectiveOptions(cliOptions, config) {
+  const defaults = config.defaults ?? {};
+  const resolver = config.resolver ?? {};
+  return {
+    strict: cliOptions.strict ?? defaults.strict ?? DEFAULT_OPTIONS2.strict,
+    ci: cliOptions.ci ?? defaults.ci ?? DEFAULT_OPTIONS2.ci,
+    json: cliOptions.json ?? defaults.json ?? DEFAULT_OPTIONS2.json,
+    yes: cliOptions.yes ?? defaults.yes ?? DEFAULT_OPTIONS2.yes,
+    dryRun: cliOptions.dryRun ?? defaults.dryRun ?? DEFAULT_OPTIONS2.dryRun,
+    force: cliOptions.force ?? defaults.force ?? DEFAULT_OPTIONS2.force,
+    allowUnverifiable: cliOptions.allowUnverifiable ?? defaults.allowUnverifiable ?? DEFAULT_OPTIONS2.allowUnverifiable,
+    githubTimeoutMs: cliOptions.githubTimeoutMs ?? resolver.githubTimeoutMs ?? DEFAULT_OPTIONS2.githubTimeoutMs,
+    githubRetries: cliOptions.githubRetries ?? resolver.githubRetries ?? DEFAULT_OPTIONS2.githubRetries,
+    githubRetryBaseMs: cliOptions.githubRetryBaseMs ?? resolver.githubRetryBaseMs ?? DEFAULT_OPTIONS2.githubRetryBaseMs,
+    maxFileBytes: cliOptions.maxFileBytes ?? resolver.maxFileBytes ?? DEFAULT_OPTIONS2.maxFileBytes,
+    maxAuxFiles: cliOptions.maxAuxFiles ?? resolver.maxAuxFiles ?? DEFAULT_OPTIONS2.maxAuxFiles,
+    maxTotalFiles: cliOptions.maxTotalFiles ?? resolver.maxTotalFiles ?? DEFAULT_OPTIONS2.maxTotalFiles
+  };
+}
+function enforceOptionPolicy2(options, config) {
+  const policy = config.policy;
+  if (!policy) {
+    return;
+  }
+  if (options.force && policy.allowForce === false) {
+    throw new GuardSkillsError(
+      "POLICY_VIOLATION",
+      "Policy blocks --force overrides (allowForce=false)."
+    );
+  }
+  if (options.allowUnverifiable && policy.allowUnverifiableOverride === false) {
+    throw new GuardSkillsError(
+      "POLICY_VIOLATION",
+      "Policy blocks --allow-unverifiable overrides (allowUnverifiableOverride=false)."
+    );
+  }
+}
+function findSkillDirs(rootDir) {
+  const found = /* @__PURE__ */ new Set();
+  const stack = [{ dir: rootDir, depth: 0 }];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+    const skillFile = path4.join(current.dir, "SKILL.md");
+    if (fs2.existsSync(skillFile) && fs2.statSync(skillFile).isFile()) {
+      found.add(current.dir);
+      continue;
+    }
+    if (current.depth >= 8) {
+      continue;
+    }
+    let entries;
+    try {
+      entries = fs2.readdirSync(current.dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+      stack.push({ dir: path4.join(current.dir, entry.name), depth: current.depth + 1 });
+    }
+  }
+  return [...found].sort();
+}
+function collectLocalFiles(skillDir, options) {
+  const files = [];
+  const unverifiableReasons = [];
+  const stack = [skillDir];
+  while (stack.length > 0) {
+    const currentDir = stack.pop();
+    if (!currentDir) {
+      continue;
+    }
+    let entries;
+    try {
+      entries = fs2.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      unverifiableReasons.push(`Cannot read directory: ${currentDir}`);
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path4.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) {
+          stack.push(fullPath);
+        }
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const relativePath = path4.relative(skillDir, fullPath).replace(/\\/g, "/");
+      const ext = path4.extname(relativePath).toLowerCase();
+      const isSkillFile2 = path4.basename(relativePath).toLowerCase() === "skill.md";
+      if (!isSkillFile2 && !ALLOWED_TEXT_EXTENSIONS2.has(ext)) {
+        continue;
+      }
+      if (files.length >= options.maxTotalFiles) {
+        unverifiableReasons.push(
+          `Reached maxTotalFiles=${options.maxTotalFiles}. Remaining files were not scanned.`
+        );
+        return { files, unverifiableReasons };
+      }
+      let sizeBytes = 0;
+      try {
+        sizeBytes = fs2.statSync(fullPath).size;
+      } catch {
+        unverifiableReasons.push(`Cannot stat file: ${relativePath}`);
+        continue;
+      }
+      if (sizeBytes > options.maxFileBytes) {
+        unverifiableReasons.push(
+          `Skipped oversized file (${sizeBytes} bytes > ${options.maxFileBytes}): ${relativePath}`
+        );
+        continue;
+      }
+      try {
+        files.push({
+          path: relativePath,
+          content: fs2.readFileSync(fullPath, "utf8")
+        });
+      } catch {
+        unverifiableReasons.push(`Cannot read text content: ${relativePath}`);
+      }
+    }
+  }
+  return { files, unverifiableReasons };
+}
+function resolveSource(source) {
+  const maybePath = path4.resolve(source);
+  if (fs2.existsSync(maybePath)) {
+    return { kind: "local", path: maybePath };
+  }
+  const shorthand = source.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/);
+  if (shorthand) {
+    return { kind: "git", cloneUrl: `https://github.com/${shorthand[1]}/${shorthand[2]}.git` };
+  }
+  try {
+    const parsed = new URL(source);
+    if (parsed.hostname === "github.com" || parsed.hostname === "www.github.com") {
+      return { kind: "git", cloneUrl: source.endsWith(".git") ? source : `${source}.git` };
+    }
+  } catch {
+  }
+  return { kind: "git", cloneUrl: source };
+}
+function aggregateLevel(levels) {
+  if (levels.includes("UNVERIFIABLE")) {
+    return "UNVERIFIABLE";
+  }
+  if (levels.includes("CRITICAL")) {
+    return "CRITICAL";
+  }
+  if (levels.includes("UNSAFE")) {
+    return "UNSAFE";
+  }
+  if (levels.includes("WARNING")) {
+    return "WARNING";
+  }
+  return "SAFE";
+}
+async function runInteractiveInstallCommand(provider, source, skillName, rawOptions) {
+  if (provider !== "openskills" && provider !== "skills" && provider !== "skillkit") {
+    throw new GuardSkillsError(
+      "INVALID_OPTIONS",
+      `Interactive install flow is not supported for provider '${provider}'.`
+    );
+  }
+  const cliOptions = cliOpenSkillsOptionsSchema.parse(rawOptions);
+  const loadedConfig = loadGuardSkillsConfig(cliOptions.config);
+  const options = resolveEffectiveOptions(cliOptions, loadedConfig.config);
+  enforceSourcePolicy(source, loadedConfig.config.policy);
+  enforceOptionPolicy2(options, loadedConfig.config);
+  const resolvedSource = resolveSource(source);
+  const tempDir = resolvedSource.kind === "git" ? fs2.mkdtempSync(path4.join(os.tmpdir(), `guardskills-${provider}-`)) : null;
+  const scanRoot = resolvedSource.kind === "git" ? tempDir ?? "" : resolvedSource.path;
+  try {
+    if (resolvedSource.kind === "git") {
+      try {
+        await execa2("git", ["clone", "--depth", "1", resolvedSource.cloneUrl, scanRoot], {
+          timeout: options.githubTimeoutMs
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GuardSkillsError(
+          "GITHUB_UNKNOWN",
+          `Failed to clone source '${source}' for ${provider} scan: ${message}`,
+          { cause: error }
+        );
+      }
+    }
+    const discovered = findSkillDirs(scanRoot);
+    if (discovered.length === 0) {
+      throw new GuardSkillsError("SKILL_NOT_FOUND", "No SKILL.md files were found in the source.");
+    }
+    const selectedDirs = skillName ? discovered.filter((dir) => path4.basename(dir).toLowerCase() === skillName.toLowerCase()) : discovered;
+    if (selectedDirs.length === 0) {
+      throw new GuardSkillsError(
+        "SKILL_NOT_FOUND",
+        `Skill '${skillName}' was not found. Available: ${discovered.map((dir) => path4.basename(dir)).join(", ")}`
+      );
+    }
+    const levels = [];
+    const summaries = [];
+    for (const skillDir of selectedDirs) {
+      const skill = path4.basename(skillDir);
+      const { files, unverifiableReasons } = collectLocalFiles(skillDir, options);
+      const resolvedSkill = {
+        source: `local:${skillDir}`,
+        owner: "local",
+        repo: "local",
+        defaultBranch: "local",
+        commitSha: "local",
+        skillName: skill,
+        skillDir: skillDir.replace(/\\/g, "/"),
+        skillFilePath: "SKILL.md",
+        files,
+        unverifiableReasons
+      };
+      const scan = scanResolvedSkill(resolvedSkill);
+      const decision = calculateRiskScore(scan.findings, {
+        strict: options.strict,
+        trustCredits: 0,
+        hasUnverifiableContent: scan.hasUnverifiableContent
+      });
+      levels.push(decision.level);
+      summaries.push({ skill, level: decision.level, riskScore: decision.riskScore });
+    }
+    const overall = aggregateLevel(levels);
+    const gate = evaluateGate(overall, { ...options, skill: skillName ?? "ALL_SKILLS" });
+    const label = provider === "openskills" ? "OpenSkills" : provider === "skillkit" ? "skillkit" : "skills.sh";
+    const note = `${gate.gateNote} ${label} flow: ${skillName ? "single skill" : "interactive skill selection"}.`;
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            command: `guardskills ${provider} ${provider === "skills" ? "add" : "install"}`,
+            source,
+            skill: skillName ?? null,
+            scannedSkills: summaries.length,
+            overallLevel: overall,
+            skills: summaries,
+            note
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(`Command: guardskills ${provider} ${provider === "skills" ? "add" : "install"}`);
+      console.log(`Source: ${source}`);
+      console.log(`Selection: ${skillName ?? "interactive (all scanned)"}`);
+      console.log(`Scanned Skills: ${summaries.length}`);
+      console.log(`Decision: ${overall}`);
+      console.log("Per-skill results:");
+      for (const summary of summaries) {
+        const score = summary.riskScore === null ? "n/a" : summary.riskScore.toFixed(1);
+        console.log(`- ${summary.skill}: ${summary.level} (risk ${score})`);
+      }
+      console.log(`Note: ${note}`);
+    }
+    if (!gate.canInstall) {
+      return gate.exitCode;
+    }
+    if (options.dryRun || options.ci) {
+      return 0;
+    }
+    return runProviderInstall(provider, source, skillName);
+  } finally {
+    if (tempDir) {
+      fs2.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+}
+
+// src/commands/scan-clawhub.ts
+import { z as z4 } from "zod";
 
 // src/resolver/clawhub.ts
-import path4 from "path";
+import path5 from "path";
 import JSZip from "jszip";
 var DEFAULT_REGISTRY_BASE_URL = "https://clawhub.ai";
 var DEFAULT_ARCHIVE_BASE_URL = "https://auth.clawdhub.com";
@@ -1225,7 +1586,7 @@ var DEFAULT_REQUEST_TIMEOUT_MS2 = 15e3;
 var DEFAULT_MAX_FILE_SIZE_BYTES = 25e4;
 var DEFAULT_MAX_TOTAL_FILES = 120;
 var RETRYABLE_STATUS2 = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
-var ALLOWED_TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([
+var ALLOWED_TEXT_EXTENSIONS3 = /* @__PURE__ */ new Set([
   ".md",
   ".txt",
   ".sh",
@@ -1467,8 +1828,8 @@ function isLikelyTextFile2(filePath) {
   if (lower.endsWith("/skill.md") || lower === "skill.md") {
     return true;
   }
-  const ext = path4.posix.extname(lower);
-  return ALLOWED_TEXT_EXTENSIONS2.has(ext);
+  const ext = path5.posix.extname(lower);
+  return ALLOWED_TEXT_EXTENSIONS3.has(ext);
 }
 function isBinaryContent2(content) {
   return content.includes("\0");
@@ -1611,7 +1972,7 @@ async function resolveSkillFromArchive(metadata, identifier, options) {
     defaultBranch: "archive",
     commitSha: archiveMeta.version ?? "archive",
     skillName: options.skillNameOverride ?? archiveMeta.slug,
-    skillDir: path4.posix.dirname(skillFilePath),
+    skillDir: path5.posix.dirname(skillFilePath),
     skillFilePath,
     files,
     unverifiableReasons: [...unverifiableReasons],
@@ -1759,34 +2120,34 @@ async function resolveSkillFromClawHub(identifier, options = {}) {
 }
 
 // src/commands/scan-clawhub.ts
-var cliScanClawHubOptionsSchema = z3.object({
-  config: z3.string().optional(),
-  strict: z3.boolean().optional(),
-  json: z3.boolean().optional(),
-  skill: z3.string().min(1).optional(),
-  version: z3.string().min(1).optional(),
-  clawhubRegistry: z3.string().min(1).optional(),
-  githubTimeoutMs: z3.coerce.number().int().min(1e3).max(12e4).optional(),
-  githubRetries: z3.coerce.number().int().min(0).max(6).optional(),
-  githubRetryBaseMs: z3.coerce.number().int().min(50).max(5e3).optional(),
-  maxFileBytes: z3.coerce.number().int().min(4096).max(5e6).optional(),
-  maxAuxFiles: z3.coerce.number().int().min(1).max(200).optional(),
-  maxTotalFiles: z3.coerce.number().int().min(1).max(400).optional()
+var cliScanClawHubOptionsSchema = z4.object({
+  config: z4.string().optional(),
+  strict: z4.boolean().optional(),
+  json: z4.boolean().optional(),
+  skill: z4.string().min(1).optional(),
+  version: z4.string().min(1).optional(),
+  clawhubRegistry: z4.string().min(1).optional(),
+  githubTimeoutMs: z4.coerce.number().int().min(1e3).max(12e4).optional(),
+  githubRetries: z4.coerce.number().int().min(0).max(6).optional(),
+  githubRetryBaseMs: z4.coerce.number().int().min(50).max(5e3).optional(),
+  maxFileBytes: z4.coerce.number().int().min(4096).max(5e6).optional(),
+  maxAuxFiles: z4.coerce.number().int().min(1).max(200).optional(),
+  maxTotalFiles: z4.coerce.number().int().min(1).max(400).optional()
 });
-var effectiveScanClawHubOptionsSchema = z3.object({
-  strict: z3.boolean(),
-  json: z3.boolean(),
-  skill: z3.string().min(1).optional(),
-  version: z3.string().min(1).optional(),
-  clawhubRegistry: z3.string().min(1),
-  githubTimeoutMs: z3.number().int().min(1e3).max(12e4),
-  githubRetries: z3.number().int().min(0).max(6),
-  githubRetryBaseMs: z3.number().int().min(50).max(5e3),
-  maxFileBytes: z3.number().int().min(4096).max(5e6),
-  maxAuxFiles: z3.number().int().min(1).max(200),
-  maxTotalFiles: z3.number().int().min(1).max(400)
+var effectiveScanClawHubOptionsSchema = z4.object({
+  strict: z4.boolean(),
+  json: z4.boolean(),
+  skill: z4.string().min(1).optional(),
+  version: z4.string().min(1).optional(),
+  clawhubRegistry: z4.string().min(1),
+  githubTimeoutMs: z4.number().int().min(1e3).max(12e4),
+  githubRetries: z4.number().int().min(0).max(6),
+  githubRetryBaseMs: z4.number().int().min(50).max(5e3),
+  maxFileBytes: z4.number().int().min(4096).max(5e6),
+  maxAuxFiles: z4.number().int().min(1).max(200),
+  maxTotalFiles: z4.number().int().min(1).max(400)
 });
-var DEFAULT_OPTIONS2 = {
+var DEFAULT_OPTIONS3 = {
   strict: false,
   json: false,
   skill: void 0,
@@ -1834,17 +2195,17 @@ function resolveEffectiveScanClawHubOptions(cliOptions, config) {
   const defaults = config.defaults ?? {};
   const resolver = config.resolver ?? {};
   return effectiveScanClawHubOptionsSchema.parse({
-    strict: cliOptions.strict ?? defaults.strict ?? DEFAULT_OPTIONS2.strict,
-    json: cliOptions.json ?? defaults.json ?? DEFAULT_OPTIONS2.json,
-    skill: cliOptions.skill ?? DEFAULT_OPTIONS2.skill,
-    version: cliOptions.version ?? DEFAULT_OPTIONS2.version,
-    clawhubRegistry: cliOptions.clawhubRegistry ?? DEFAULT_OPTIONS2.clawhubRegistry,
-    githubTimeoutMs: cliOptions.githubTimeoutMs ?? resolver.githubTimeoutMs ?? DEFAULT_OPTIONS2.githubTimeoutMs,
-    githubRetries: cliOptions.githubRetries ?? resolver.githubRetries ?? DEFAULT_OPTIONS2.githubRetries,
-    githubRetryBaseMs: cliOptions.githubRetryBaseMs ?? resolver.githubRetryBaseMs ?? DEFAULT_OPTIONS2.githubRetryBaseMs,
-    maxFileBytes: cliOptions.maxFileBytes ?? resolver.maxFileBytes ?? DEFAULT_OPTIONS2.maxFileBytes,
-    maxAuxFiles: cliOptions.maxAuxFiles ?? resolver.maxAuxFiles ?? DEFAULT_OPTIONS2.maxAuxFiles,
-    maxTotalFiles: cliOptions.maxTotalFiles ?? resolver.maxTotalFiles ?? DEFAULT_OPTIONS2.maxTotalFiles
+    strict: cliOptions.strict ?? defaults.strict ?? DEFAULT_OPTIONS3.strict,
+    json: cliOptions.json ?? defaults.json ?? DEFAULT_OPTIONS3.json,
+    skill: cliOptions.skill ?? DEFAULT_OPTIONS3.skill,
+    version: cliOptions.version ?? DEFAULT_OPTIONS3.version,
+    clawhubRegistry: cliOptions.clawhubRegistry ?? DEFAULT_OPTIONS3.clawhubRegistry,
+    githubTimeoutMs: cliOptions.githubTimeoutMs ?? resolver.githubTimeoutMs ?? DEFAULT_OPTIONS3.githubTimeoutMs,
+    githubRetries: cliOptions.githubRetries ?? resolver.githubRetries ?? DEFAULT_OPTIONS3.githubRetries,
+    githubRetryBaseMs: cliOptions.githubRetryBaseMs ?? resolver.githubRetryBaseMs ?? DEFAULT_OPTIONS3.githubRetryBaseMs,
+    maxFileBytes: cliOptions.maxFileBytes ?? resolver.maxFileBytes ?? DEFAULT_OPTIONS3.maxFileBytes,
+    maxAuxFiles: cliOptions.maxAuxFiles ?? resolver.maxAuxFiles ?? DEFAULT_OPTIONS3.maxAuxFiles,
+    maxTotalFiles: cliOptions.maxTotalFiles ?? resolver.maxTotalFiles ?? DEFAULT_OPTIONS3.maxTotalFiles
   });
 }
 async function runScanClawHubCommand(identifier, rawOptions) {
@@ -1906,10 +2267,10 @@ async function runScanClawHubCommand(identifier, rawOptions) {
 }
 
 // src/commands/scan-local.ts
-import fs2 from "fs";
-import path5 from "path";
-import { z as z4 } from "zod";
-var ALLOWED_TEXT_EXTENSIONS3 = /* @__PURE__ */ new Set([
+import fs3 from "fs";
+import path6 from "path";
+import { z as z5 } from "zod";
+var ALLOWED_TEXT_EXTENSIONS4 = /* @__PURE__ */ new Set([
   ".md",
   ".txt",
   ".sh",
@@ -1928,23 +2289,23 @@ var ALLOWED_TEXT_EXTENSIONS3 = /* @__PURE__ */ new Set([
   ".ini",
   ".cfg"
 ]);
-var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", ".next", ".turbo"]);
-var cliScanLocalOptionsSchema = z4.object({
-  config: z4.string().optional(),
-  strict: z4.boolean().optional(),
-  json: z4.boolean().optional(),
-  skill: z4.string().min(1).optional(),
-  maxFileBytes: z4.coerce.number().int().min(4096).max(5e6).optional(),
-  maxTotalFiles: z4.coerce.number().int().min(1).max(400).optional()
+var SKIP_DIRS2 = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", ".next", ".turbo"]);
+var cliScanLocalOptionsSchema = z5.object({
+  config: z5.string().optional(),
+  strict: z5.boolean().optional(),
+  json: z5.boolean().optional(),
+  skill: z5.string().min(1).optional(),
+  maxFileBytes: z5.coerce.number().int().min(4096).max(5e6).optional(),
+  maxTotalFiles: z5.coerce.number().int().min(1).max(400).optional()
 });
-var effectiveScanLocalOptionsSchema = z4.object({
-  strict: z4.boolean(),
-  json: z4.boolean(),
-  skill: z4.string().min(1).optional(),
-  maxFileBytes: z4.number().int().min(4096).max(5e6),
-  maxTotalFiles: z4.number().int().min(1).max(400)
+var effectiveScanLocalOptionsSchema = z5.object({
+  strict: z5.boolean(),
+  json: z5.boolean(),
+  skill: z5.string().min(1).optional(),
+  maxFileBytes: z5.number().int().min(4096).max(5e6),
+  maxTotalFiles: z5.number().int().min(1).max(400)
 });
-var DEFAULT_OPTIONS3 = {
+var DEFAULT_OPTIONS4 = {
   strict: false,
   json: false,
   skill: void 0,
@@ -1955,30 +2316,30 @@ function toPosixPath(filePath) {
   return filePath.replace(/\\/g, "/");
 }
 function getNearbyPathSuggestions(targetPath) {
-  const parent = path5.dirname(targetPath);
-  if (!fs2.existsSync(parent)) {
+  const parent = path6.dirname(targetPath);
+  if (!fs3.existsSync(parent)) {
     return [];
   }
-  const needle = path5.basename(targetPath).toLowerCase();
+  const needle = path6.basename(targetPath).toLowerCase();
   const suggestions = [];
-  for (const entry of fs2.readdirSync(parent, { withFileTypes: true })) {
+  for (const entry of fs3.readdirSync(parent, { withFileTypes: true })) {
     if (entry.name.toLowerCase().includes(needle)) {
-      suggestions.push(path5.join(parent, entry.name));
+      suggestions.push(path6.join(parent, entry.name));
     }
   }
   return suggestions.slice(0, 5);
 }
 function isSkillFile(filePath) {
-  return path5.basename(filePath).toLowerCase() === "skill.md";
+  return path6.basename(filePath).toLowerCase() === "skill.md";
 }
 function isScannableTextFile(filePath) {
   if (isSkillFile(filePath)) {
     return true;
   }
-  const ext = path5.extname(filePath).toLowerCase();
-  return ALLOWED_TEXT_EXTENSIONS3.has(ext);
+  const ext = path6.extname(filePath).toLowerCase();
+  return ALLOWED_TEXT_EXTENSIONS4.has(ext);
 }
-function findSkillDirs(rootDir) {
+function findSkillDirs2(rootDir) {
   const found = /* @__PURE__ */ new Set();
   const stack = [{ dir: rootDir, depth: 0 }];
   let seen = 0;
@@ -1991,8 +2352,8 @@ function findSkillDirs(rootDir) {
     if (seen > 5e3) {
       break;
     }
-    const skillFile = path5.join(current.dir, "SKILL.md");
-    if (fs2.existsSync(skillFile) && fs2.statSync(skillFile).isFile()) {
+    const skillFile = path6.join(current.dir, "SKILL.md");
+    if (fs3.existsSync(skillFile) && fs3.statSync(skillFile).isFile()) {
       found.add(current.dir);
       continue;
     }
@@ -2001,7 +2362,7 @@ function findSkillDirs(rootDir) {
     }
     let entries;
     try {
-      entries = fs2.readdirSync(current.dir, { withFileTypes: true });
+      entries = fs3.readdirSync(current.dir, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -2009,10 +2370,10 @@ function findSkillDirs(rootDir) {
       if (!entry.isDirectory()) {
         continue;
       }
-      if (SKIP_DIRS.has(entry.name)) {
+      if (SKIP_DIRS2.has(entry.name)) {
         continue;
       }
-      stack.push({ dir: path5.join(current.dir, entry.name), depth: current.depth + 1 });
+      stack.push({ dir: path6.join(current.dir, entry.name), depth: current.depth + 1 });
     }
   }
   return [...found].sort();
@@ -2021,8 +2382,8 @@ function formatCandidates(candidates) {
   return candidates.map((candidate) => `- ${toPosixPath(candidate)}`).join("\n");
 }
 function resolveSkillDirectory(inputPath, preferredSkillName) {
-  const absoluteInput = path5.resolve(inputPath);
-  if (!fs2.existsSync(absoluteInput)) {
+  const absoluteInput = path6.resolve(inputPath);
+  if (!fs3.existsSync(absoluteInput)) {
     const suggestions = getNearbyPathSuggestions(absoluteInput);
     const suggestionText = suggestions.length > 0 ? `
 Nearby paths:
@@ -2032,7 +2393,7 @@ ${formatCandidates(suggestions)}` : "";
       `Local path not found: ${toPosixPath(absoluteInput)}${suggestionText}`
     );
   }
-  const stat = fs2.statSync(absoluteInput);
+  const stat = fs3.statSync(absoluteInput);
   if (stat.isFile()) {
     if (!isSkillFile(absoluteInput)) {
       throw new GuardSkillsError(
@@ -2041,15 +2402,15 @@ ${formatCandidates(suggestions)}` : "";
       );
     }
     return {
-      skillDir: path5.dirname(absoluteInput),
+      skillDir: path6.dirname(absoluteInput),
       note: "Using parent directory of provided SKILL.md file."
     };
   }
-  const directSkillFile = path5.join(absoluteInput, "SKILL.md");
-  if (fs2.existsSync(directSkillFile) && fs2.statSync(directSkillFile).isFile()) {
+  const directSkillFile = path6.join(absoluteInput, "SKILL.md");
+  if (fs3.existsSync(directSkillFile) && fs3.statSync(directSkillFile).isFile()) {
     return { skillDir: absoluteInput };
   }
-  const discovered = findSkillDirs(absoluteInput);
+  const discovered = findSkillDirs2(absoluteInput);
   if (discovered.length === 0) {
     throw new GuardSkillsError(
       "INVALID_LOCAL_PATH",
@@ -2058,7 +2419,7 @@ ${formatCandidates(suggestions)}` : "";
   }
   if (preferredSkillName) {
     const matches = discovered.filter(
-      (directory) => path5.basename(directory).toLowerCase() === preferredSkillName.toLowerCase()
+      (directory) => path6.basename(directory).toLowerCase() === preferredSkillName.toLowerCase()
     );
     if (matches.length === 1) {
       const selected = matches[0];
@@ -2070,7 +2431,7 @@ ${formatCandidates(suggestions)}` : "";
         note: `Auto-selected skill '${preferredSkillName}' under the provided path.`
       };
     }
-    const available = discovered.map((directory) => path5.basename(directory));
+    const available = discovered.map((directory) => path6.basename(directory));
     throw new GuardSkillsError(
       "INVALID_LOCAL_PATH",
       `Requested --skill '${preferredSkillName}' was not found.
@@ -2093,7 +2454,7 @@ Available skills: ${available.join(", ")}`
 ${formatCandidates(discovered)}`
   );
 }
-function collectLocalFiles(skillDir, options) {
+function collectLocalFiles2(skillDir, options) {
   const files = [];
   const unverifiableReasons = [];
   const stack = [skillDir];
@@ -2104,15 +2465,15 @@ function collectLocalFiles(skillDir, options) {
     }
     let entries;
     try {
-      entries = fs2.readdirSync(currentDir, { withFileTypes: true });
+      entries = fs3.readdirSync(currentDir, { withFileTypes: true });
     } catch {
       unverifiableReasons.push(`Cannot read directory: ${toPosixPath(currentDir)}`);
       continue;
     }
     for (const entry of entries) {
-      const fullPath = path5.join(currentDir, entry.name);
+      const fullPath = path6.join(currentDir, entry.name);
       if (entry.isDirectory()) {
-        if (!SKIP_DIRS.has(entry.name)) {
+        if (!SKIP_DIRS2.has(entry.name)) {
           stack.push(fullPath);
         }
         continue;
@@ -2120,7 +2481,7 @@ function collectLocalFiles(skillDir, options) {
       if (!entry.isFile()) {
         continue;
       }
-      const relativePath = toPosixPath(path5.relative(skillDir, fullPath));
+      const relativePath = toPosixPath(path6.relative(skillDir, fullPath));
       if (!isScannableTextFile(relativePath)) {
         continue;
       }
@@ -2132,7 +2493,7 @@ function collectLocalFiles(skillDir, options) {
       }
       let sizeBytes = 0;
       try {
-        sizeBytes = fs2.statSync(fullPath).size;
+        sizeBytes = fs3.statSync(fullPath).size;
       } catch {
         unverifiableReasons.push(`Cannot stat file: ${relativePath}`);
         continue;
@@ -2146,7 +2507,7 @@ function collectLocalFiles(skillDir, options) {
       try {
         files.push({
           path: relativePath,
-          content: fs2.readFileSync(fullPath, "utf8")
+          content: fs3.readFileSync(fullPath, "utf8")
         });
       } catch {
         unverifiableReasons.push(`Cannot read text content: ${relativePath}`);
@@ -2159,11 +2520,11 @@ function resolveEffectiveScanLocalOptions(cliOptions, config) {
   const defaults = config.defaults ?? {};
   const resolver = config.resolver ?? {};
   return effectiveScanLocalOptionsSchema.parse({
-    strict: cliOptions.strict ?? defaults.strict ?? DEFAULT_OPTIONS3.strict,
-    json: cliOptions.json ?? defaults.json ?? DEFAULT_OPTIONS3.json,
-    skill: cliOptions.skill ?? DEFAULT_OPTIONS3.skill,
-    maxFileBytes: cliOptions.maxFileBytes ?? resolver.maxFileBytes ?? DEFAULT_OPTIONS3.maxFileBytes,
-    maxTotalFiles: cliOptions.maxTotalFiles ?? resolver.maxTotalFiles ?? DEFAULT_OPTIONS3.maxTotalFiles
+    strict: cliOptions.strict ?? defaults.strict ?? DEFAULT_OPTIONS4.strict,
+    json: cliOptions.json ?? defaults.json ?? DEFAULT_OPTIONS4.json,
+    skill: cliOptions.skill ?? DEFAULT_OPTIONS4.skill,
+    maxFileBytes: cliOptions.maxFileBytes ?? resolver.maxFileBytes ?? DEFAULT_OPTIONS4.maxFileBytes,
+    maxTotalFiles: cliOptions.maxTotalFiles ?? resolver.maxTotalFiles ?? DEFAULT_OPTIONS4.maxTotalFiles
   });
 }
 async function runScanLocalCommand(inputPath, rawOptions) {
@@ -2171,7 +2532,7 @@ async function runScanLocalCommand(inputPath, rawOptions) {
   const loadedConfig = loadGuardSkillsConfig(cliOptions.config);
   const options = resolveEffectiveScanLocalOptions(cliOptions, loadedConfig.config);
   const target = resolveSkillDirectory(inputPath, options.skill);
-  const { files, unverifiableReasons } = collectLocalFiles(target.skillDir, options);
+  const { files, unverifiableReasons } = collectLocalFiles2(target.skillDir, options);
   if (files.length === 0) {
     throw new GuardSkillsError(
       "INVALID_LOCAL_PATH",
@@ -2184,7 +2545,7 @@ async function runScanLocalCommand(inputPath, rawOptions) {
     repo: "local",
     defaultBranch: "local",
     commitSha: "local",
-    skillName: options.skill ?? path5.basename(target.skillDir),
+    skillName: options.skill ?? path6.basename(target.skillDir),
     skillDir: toPosixPath(target.skillDir),
     skillFilePath: "SKILL.md",
     files,
@@ -2226,15 +2587,69 @@ async function runScanLocalCommand(inputPath, rawOptions) {
 }
 
 // src/cli.ts
+function withCommonAddOptions(command, requireSkill) {
+  const configured = command.option("--config <path>", "Path to guardskills.config.json").option("--strict", "Use stricter risk thresholds").option("--ci", "Deterministic CI mode: scan + gate only, no install handoff").option("--json", "Output machine-readable JSON").option("--yes", "Auto-confirm warnings").option("--dry-run", "Scan only, do not install").option("--force", "Override UNSAFE outcome").option("--allow-unverifiable", "Override UNVERIFIABLE outcome").option("--github-timeout-ms <ms>", "GitHub API request timeout in milliseconds").option("--github-retries <count>", "Retry count for retryable GitHub errors").option("--github-retry-base-ms <ms>", "Base backoff delay for GitHub retries").option("--max-file-bytes <bytes>", "Max file size to scan").option("--max-aux-files <count>", "Max auxiliary files from scripts/src folders").option("--max-total-files <count>", "Max total resolved files to scan");
+  return requireSkill ? configured.requiredOption("--skill <name>", "Skill name to install") : configured.option("--skill <name>", "Skill name to install");
+}
 async function main() {
   const program = new Command();
-  program.name("guardskills").description("Security wrapper around skills add").version("1.1.0");
-  program.command("add").description("Scan a skill source and conditionally install it via skills CLI").argument("<repo>", "GitHub repository URL or owner/repo").requiredOption("--skill <name>", "Skill name to install").option("--config <path>", "Path to guardskills.config.json").option("--strict", "Use stricter risk thresholds").option("--ci", "Deterministic CI mode: scan + gate only, no install handoff").option("--json", "Output machine-readable JSON").option("--yes", "Auto-confirm warnings").option("--dry-run", "Scan only, do not install").option("--force", "Override UNSAFE outcome").option("--allow-unverifiable", "Override UNVERIFIABLE outcome").option("--github-timeout-ms <ms>", "GitHub API request timeout in milliseconds").option("--github-retries <count>", "Retry count for retryable GitHub errors").option("--github-retry-base-ms <ms>", "Base backoff delay for GitHub retries").option("--max-file-bytes <bytes>", "Max file size to scan").option("--max-aux-files <count>", "Max auxiliary files from scripts/src folders").option("--max-total-files <count>", "Max total resolved files to scan").action(async (repo, options) => {
-    const code = await runAddCommand(repo, options);
+  program.name("guardskills").description("Security wrapper around skill installation CLIs").version("1.1.0");
+  const legacyAdd = program.command("add").description("Scan a skill source and conditionally install it via skills CLI").argument("<repo>", "GitHub repository URL or owner/repo");
+  withCommonAddOptions(legacyAdd, true).action(
+    async (repo, options) => {
+      const code = await runAddCommand(repo, options);
+      process.exitCode = code;
+    }
+  );
+  const skills = program.command("skills").description("Guarded wrapper for skills.sh install commands");
+  withCommonAddOptions(
+    skills.command("add").description("Scan a skill source and conditionally install it via skills CLI").argument("<repo>", "GitHub repository URL or owner/repo"),
+    false
+  ).action(async (repo, options) => {
+    const resolvedSkill = typeof options.skill === "string" ? options.skill : void 0;
+    const code = resolvedSkill ? await runAddCommand(repo, options, {
+      provider: "skills",
+      commandName: "guardskills skills add"
+    }) : await runInteractiveInstallCommand("skills", repo, void 0, options);
+    process.exitCode = code;
+  });
+  const playbooks = program.command("playbooks").description("Guarded wrapper for Playbooks install commands");
+  withCommonAddOptions(
+    playbooks.command("add").description("Scan a skill source and conditionally install it via Playbooks CLI").argument("<resource>", "Playbooks resource type (must be 'skill')").argument("<repo>", "GitHub repository URL or owner/repo"),
+    true
+  ).action(async (resource, repo, options) => {
+    if (resource !== "skill") {
+      throw new GuardSkillsError(
+        "INVALID_OPTIONS",
+        `Unsupported playbooks resource '${resource}'. Use: guardskills playbooks add skill <repo> --skill <name>`
+      );
+    }
+    const code = await runAddCommand(repo, options, {
+      provider: "playbooks",
+      commandName: "guardskills playbooks add skill"
+    });
+    process.exitCode = code;
+  });
+  const openskills = program.command("openskills").description("Guarded wrapper for OpenSkills install commands");
+  withCommonAddOptions(
+    openskills.command("install").description("Scan a skill source and conditionally install it via OpenSkills CLI").argument("<repo>", "GitHub repository URL or owner/repo").argument("[skill]", "Skill name to install"),
+    false
+  ).action(async (repo, skill, options) => {
+    const resolvedSkill = skill ?? (typeof options.skill === "string" ? options.skill : void 0);
+    const code = await runInteractiveInstallCommand("openskills", repo, resolvedSkill, options);
+    process.exitCode = code;
+  });
+  const skillkit = program.command("skillkit").description("Guarded wrapper for skillkit install commands");
+  withCommonAddOptions(
+    skillkit.command("install").description("Scan a skill source and conditionally install it via skillkit CLI").argument("<repo>", "GitHub repository URL or owner/repo").argument("[skill]", "Skill name to install"),
+    false
+  ).action(async (repo, skill, options) => {
+    const resolvedSkill = skill ?? (typeof options.skill === "string" ? options.skill : void 0);
+    const code = await runInteractiveInstallCommand("skillkit", repo, resolvedSkill, options);
     process.exitCode = code;
   });
-  program.command("scan-local").description("Scan a local skill folder and print a risk decision").argument("<path>", "Local folder path (or SKILL.md file path)").option("--skill <name>", "Skill directory name when path contains multiple skills").option("--config <path>", "Path to guardskills.config.json").option("--strict", "Use stricter risk thresholds").option("--json", "Output machine-readable JSON").option("--max-file-bytes <bytes>", "Max file size to scan").option("--max-total-files <count>", "Max total files to scan").action(async (inputPath, options) => {
-    const code = await runScanLocalCommand(inputPath, options);
+  program.command("scan-local").description("Scan a local skill folder and print a risk decision").argument("<path>", "Local folder path (or SKILL.md file path)").option("--skill <name>", "Skill directory name when path contains multiple skills").option("--config <path>", "Path to guardskills.config.json").option("--strict", "Use stricter risk thresholds").option("--json", "Output machine-readable JSON").option("--max-file-bytes <bytes>", "Max file size to scan").option("--max-total-files <count>", "Max total files to scan").action(async (repo, options) => {
+    const code = await runScanLocalCommand(repo, options);
     process.exitCode = code;
   });
   program.command("scan-clawhub").description("Scan a ClawHub skill package and print a risk decision").argument("<identifier>", "ClawHub package identifier").option("--skill <name>", "Override skill folder name to resolve in source repository").option("--version <version>", "Preferred package version/tag").option("--clawhub-registry <url>", "ClawHub registry base URL").option("--config <path>", "Path to guardskills.config.json").option("--strict", "Use stricter risk thresholds").option("--json", "Output machine-readable JSON").option("--github-timeout-ms <ms>", "Upstream resolver request timeout in milliseconds").option("--github-retries <count>", "Retry count for retryable upstream errors").option("--github-retry-base-ms <ms>", "Base backoff delay for upstream retries").option("--max-file-bytes <bytes>", "Max file size to scan").option("--max-aux-files <count>", "Max auxiliary files from scripts/src folders").option("--max-total-files <count>", "Max total resolved files to scan").action(async (identifier, options) => {