guardskills 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -23,6 +23,14 @@ npx guardskills add https://github.com/vercel-labs/skills --skill find-skills
 3. Computes a risk decision (`SAFE`, `WARNING`, `UNSAFE`, `CRITICAL`, `UNVERIFIABLE`).
 4. Proceeds to `npx skills add ...` only if gate policy allows.
 
+## Security Notice
+
+`guardskills` is an additional security layer on top of `skills.sh`, not a replacement for your own review process.
+
+- `guardskills` does not maintain, control, or guarantee the safety of `skills.sh` or third-party skill repositories.
+- Static analysis reduces risk but cannot detect every threat.
+- A `SAFE` result means "no known high-risk pattern detected," not "guaranteed safe."
+
 ## Current Readiness
 
 - Current stage: **beta-quality**.
@@ -32,6 +40,7 @@ npx guardskills add https://github.com/vercel-labs/skills --skill find-skills
 ## Implemented Features
 
 - `guardskills add <repo> --skill <name>`
+- `guardskills scan-local <path>`
 - GitHub resolver (`owner/repo` and `https://github.com/...`)
 - Deterministic static scanner with rule matrix in `RULES.md`
 - Score-based decision engine with hard-block guardrails
@@ -87,6 +96,12 @@ Local dry-run:
 guardskills add https://github.com/vercel-labs/skills --skill find-skills --dry-run
 ```
 
+Local folder check:
+
+```bash
+guardskills scan-local C:\path\to\skill-folder
+```
+
 Deterministic CI gate:
 
 ```bash
@@ -105,6 +120,32 @@ guardskills add owner/repo --skill name \
   --max-total-files 120
 ```
 
+## Local Check (Folder on Disk)
+
+Scan any local skill directory:
+
+```bash
+guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills\x-algo-post
+```
+
+JSON output:
+
+```bash
+guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills\x-algo-post --json
+```
+
+If your path contains multiple skills, select one by directory name:
+
+```bash
+guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills --skill x-algo-post
+```
+
+Path handling:
+
+- missing path: fails with clear error and nearby suggestions
+- folder with one discovered `SKILL.md`: auto-selects it
+- folder with multiple discovered `SKILL.md`: asks for `--skill <name>`
+
 ## Configuration File
 
 `guardskills` supports repository-local policy and default settings via `guardskills.config.json`.

package/SECURITY.md

@@ -31,4 +31,10 @@ In scope:
 Out of scope:
 
 - vulnerabilities in third-party skill repositories themselves
-- social engineering reports without technical exploit details
+- social engineering reports without technical exploit details
+
+## Limitations
+
+- `guardskills` is an additional security control layer and not a guarantee of safety.
+- We do not maintain or control `skills.sh` or third-party skill repositories.
+- Scanner-based detection can miss novel or heavily obfuscated malware.

package/dist/cli.cjs

@@ -267,6 +267,47 @@ function printHumanReport(report) {
 function printJsonReport(report) {
   console.log(JSON.stringify(report, null, 2));
 }
+function printHumanLocalReport(report) {
+  console.log(`Command: ${report.command}`);
+  console.log(`Path: ${report.inputPath}`);
+  console.log(`Mode: ${report.strict ? "strict" : "standard"}`);
+  if (report.configPath) {
+    console.log(`Config: ${report.configPath}`);
+  }
+  console.log(`Skill Dir: ${report.skillDir}`);
+  console.log(`Files Scanned: ${report.scanFiles.length}`);
+  if (report.decision.riskScore === null) {
+    console.log("Result: UNVERIFIABLE");
+  } else {
+    console.log(`Risk Score: ${report.decision.riskScore.toFixed(1)}/100`);
+    console.log(`Decision: ${report.decision.level}`);
+  }
+  if (report.unverifiableReasons && report.unverifiableReasons.length > 0) {
+    console.log("Unverifiable Reasons:");
+    for (const reason of report.unverifiableReasons) {
+      console.log(`- ${reason}`);
+    }
+  }
+  if (report.decision.chainMatches.length > 0) {
+    console.log("Attack Chains:");
+    for (const chain of report.decision.chainMatches) {
+      console.log(`- ${chain.id} (+${chain.bonus}): ${chain.description}`);
+    }
+  }
+  if (report.decision.findings.length > 0) {
+    console.log("Findings:");
+    for (const finding of report.decision.findings.slice(0, 10)) {
+      const fileText = finding.file ? ` (${finding.file})` : "";
+      console.log(`- [${finding.severity}/${finding.confidence}] ${finding.title}${fileText}`);
+    }
+  } else {
+    console.log("Findings: none");
+  }
+  console.log(`Note: ${report.note}`);
+}
+function printJsonLocalReport(report) {
+  console.log(JSON.stringify(report, null, 2));
+}
 
 // src/resolver/github.ts
 var import_node_path2 = __toESM(require("path"), 1);
@@ -1129,14 +1170,338 @@ async function runAddCommand(repo, rawOptions) {
   return runSkillsInstall(repo, options.skill);
 }
 
+// src/commands/scan-local.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+var import_zod3 = require("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 cliScanLocalOptionsSchema = import_zod3.z.object({
+  config: import_zod3.z.string().optional(),
+  strict: import_zod3.z.boolean().optional(),
+  json: import_zod3.z.boolean().optional(),
+  skill: import_zod3.z.string().min(1).optional(),
+  maxFileBytes: import_zod3.z.coerce.number().int().min(4096).max(5e6).optional(),
+  maxTotalFiles: import_zod3.z.coerce.number().int().min(1).max(400).optional()
+});
+var effectiveScanLocalOptionsSchema = import_zod3.z.object({
+  strict: import_zod3.z.boolean(),
+  json: import_zod3.z.boolean(),
+  skill: import_zod3.z.string().min(1).optional(),
+  maxFileBytes: import_zod3.z.number().int().min(4096).max(5e6),
+  maxTotalFiles: import_zod3.z.number().int().min(1).max(400)
+});
+var DEFAULT_OPTIONS2 = {
+  strict: false,
+  json: false,
+  skill: void 0,
+  maxFileBytes: 25e4,
+  maxTotalFiles: 120
+};
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+function getNearbyPathSuggestions(targetPath) {
+  const parent = import_node_path4.default.dirname(targetPath);
+  if (!import_node_fs2.default.existsSync(parent)) {
+    return [];
+  }
+  const needle = import_node_path4.default.basename(targetPath).toLowerCase();
+  const suggestions = [];
+  for (const entry of import_node_fs2.default.readdirSync(parent, { withFileTypes: true })) {
+    if (entry.name.toLowerCase().includes(needle)) {
+      suggestions.push(import_node_path4.default.join(parent, entry.name));
+    }
+  }
+  return suggestions.slice(0, 5);
+}
+function isSkillFile(filePath) {
+  return import_node_path4.default.basename(filePath).toLowerCase() === "skill.md";
+}
+function isScannableTextFile(filePath) {
+  if (isSkillFile(filePath)) {
+    return true;
+  }
+  const ext = import_node_path4.default.extname(filePath).toLowerCase();
+  return ALLOWED_TEXT_EXTENSIONS2.has(ext);
+}
+function findSkillDirs(rootDir) {
+  const found = /* @__PURE__ */ new Set();
+  const stack = [{ dir: rootDir, depth: 0 }];
+  let seen = 0;
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+    seen += 1;
+    if (seen > 5e3) {
+      break;
+    }
+    const skillFile = import_node_path4.default.join(current.dir, "SKILL.md");
+    if (import_node_fs2.default.existsSync(skillFile) && import_node_fs2.default.statSync(skillFile).isFile()) {
+      found.add(current.dir);
+      continue;
+    }
+    if (current.depth >= 8) {
+      continue;
+    }
+    let entries;
+    try {
+      entries = import_node_fs2.default.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: import_node_path4.default.join(current.dir, entry.name), depth: current.depth + 1 });
+    }
+  }
+  return [...found].sort();
+}
+function formatCandidates(candidates) {
+  return candidates.map((candidate) => `- ${toPosixPath(candidate)}`).join("\n");
+}
+function resolveSkillDirectory(inputPath, preferredSkillName) {
+  const absoluteInput = import_node_path4.default.resolve(inputPath);
+  if (!import_node_fs2.default.existsSync(absoluteInput)) {
+    const suggestions = getNearbyPathSuggestions(absoluteInput);
+    const suggestionText = suggestions.length > 0 ? `
+Nearby paths:
+${formatCandidates(suggestions)}` : "";
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `Local path not found: ${toPosixPath(absoluteInput)}${suggestionText}`
+    );
+  }
+  const stat = import_node_fs2.default.statSync(absoluteInput);
+  if (stat.isFile()) {
+    if (!isSkillFile(absoluteInput)) {
+      throw new GuardSkillsError(
+        "INVALID_LOCAL_PATH",
+        "Local scan expects a directory or a SKILL.md file path."
+      );
+    }
+    return {
+      skillDir: import_node_path4.default.dirname(absoluteInput),
+      note: "Using parent directory of provided SKILL.md file."
+    };
+  }
+  const directSkillFile = import_node_path4.default.join(absoluteInput, "SKILL.md");
+  if (import_node_fs2.default.existsSync(directSkillFile) && import_node_fs2.default.statSync(directSkillFile).isFile()) {
+    return { skillDir: absoluteInput };
+  }
+  const discovered = findSkillDirs(absoluteInput);
+  if (discovered.length === 0) {
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `No SKILL.md found under: ${toPosixPath(absoluteInput)}`
+    );
+  }
+  if (preferredSkillName) {
+    const matches = discovered.filter(
+      (directory) => import_node_path4.default.basename(directory).toLowerCase() === preferredSkillName.toLowerCase()
+    );
+    if (matches.length === 1) {
+      const selected = matches[0];
+      if (!selected) {
+        throw new GuardSkillsError("INVALID_LOCAL_PATH", "Unable to resolve selected local skill.");
+      }
+      return {
+        skillDir: selected,
+        note: `Auto-selected skill '${preferredSkillName}' under the provided path.`
+      };
+    }
+    const available = discovered.map((directory) => import_node_path4.default.basename(directory));
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `Requested --skill '${preferredSkillName}' was not found.
+Available skills: ${available.join(", ")}`
+    );
+  }
+  if (discovered.length === 1) {
+    const selected = discovered[0];
+    if (!selected) {
+      throw new GuardSkillsError("INVALID_LOCAL_PATH", "Unable to resolve discovered local skill.");
+    }
+    return {
+      skillDir: selected,
+      note: "Auto-selected the only SKILL.md found under the provided path."
+    };
+  }
+  throw new GuardSkillsError(
+    "INVALID_LOCAL_PATH",
+    `Multiple skills found under path. Provide --skill <name>.
+${formatCandidates(discovered)}`
+  );
+}
+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 = import_node_fs2.default.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      unverifiableReasons.push(`Cannot read directory: ${toPosixPath(currentDir)}`);
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = import_node_path4.default.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) {
+          stack.push(fullPath);
+        }
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      const relativePath = toPosixPath(import_node_path4.default.relative(skillDir, fullPath));
+      if (!isScannableTextFile(relativePath)) {
+        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 = import_node_fs2.default.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: import_node_fs2.default.readFileSync(fullPath, "utf8")
+        });
+      } catch {
+        unverifiableReasons.push(`Cannot read text content: ${relativePath}`);
+      }
+    }
+  }
+  return { files, unverifiableReasons };
+}
+function resolveEffectiveScanLocalOptions(cliOptions, config) {
+  const defaults = config.defaults ?? {};
+  const resolver = config.resolver ?? {};
+  return effectiveScanLocalOptionsSchema.parse({
+    strict: cliOptions.strict ?? defaults.strict ?? DEFAULT_OPTIONS2.strict,
+    json: cliOptions.json ?? defaults.json ?? DEFAULT_OPTIONS2.json,
+    skill: cliOptions.skill ?? DEFAULT_OPTIONS2.skill,
+    maxFileBytes: cliOptions.maxFileBytes ?? resolver.maxFileBytes ?? DEFAULT_OPTIONS2.maxFileBytes,
+    maxTotalFiles: cliOptions.maxTotalFiles ?? resolver.maxTotalFiles ?? DEFAULT_OPTIONS2.maxTotalFiles
+  });
+}
+async function runScanLocalCommand(inputPath, rawOptions) {
+  const cliOptions = cliScanLocalOptionsSchema.parse(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);
+  if (files.length === 0) {
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `No scannable text files found in: ${toPosixPath(target.skillDir)}`
+    );
+  }
+  const resolvedSkill = {
+    source: `local:${toPosixPath(target.skillDir)}`,
+    owner: "local",
+    repo: "local",
+    defaultBranch: "local",
+    commitSha: "local",
+    skillName: options.skill ?? import_node_path4.default.basename(target.skillDir),
+    skillDir: toPosixPath(target.skillDir),
+    skillFilePath: "SKILL.md",
+    files,
+    unverifiableReasons
+  };
+  const scan = scanResolvedSkill(resolvedSkill);
+  const decision = calculateRiskScore(scan.findings, {
+    strict: options.strict,
+    trustCredits: 0,
+    hasUnverifiableContent: scan.hasUnverifiableContent
+  });
+  const noteParts = ["Local scan complete."];
+  if (target.note) {
+    noteParts.push(target.note);
+  }
+  if (decision.level === "UNSAFE" || decision.level === "CRITICAL" || decision.level === "UNVERIFIABLE") {
+    noteParts.push("Blocked-level risk detected.");
+  }
+  if (loadedConfig.path) {
+    noteParts.push(`Config: ${loadedConfig.path}`);
+  }
+  const report = {
+    command: "guardskills scan-local",
+    inputPath,
+    strict: options.strict,
+    configPath: loadedConfig.path ?? void 0,
+    decision,
+    scanFiles: resolvedSkill.files.map((file) => file.path),
+    skillDir: resolvedSkill.skillDir,
+    unverifiableReasons: scan.unverifiableReasons,
+    note: noteParts.join(" ")
+  };
+  if (options.json) {
+    printJsonLocalReport(report);
+  } else {
+    printHumanLocalReport(report);
+  }
+  return decision.level === "UNSAFE" || decision.level === "CRITICAL" || decision.level === "UNVERIFIABLE" ? 20 : 0;
+}
+
 // src/cli.ts
 async function main() {
   const program = new import_commander.Command();
-  program.name("guardskills").description("Security wrapper around skills add").version("0.1.0-alpha.0");
+  program.name("guardskills").description("Security wrapper around skills add").version("0.1.0-alpha.3");
   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);
     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);
+    process.exitCode = code;
+  });
   await program.parseAsync(process.argv);
 }
 main().catch((error) => {

package/dist/cli.js

@@ -243,6 +243,47 @@ function printHumanReport(report) {
 function printJsonReport(report) {
   console.log(JSON.stringify(report, null, 2));
 }
+function printHumanLocalReport(report) {
+  console.log(`Command: ${report.command}`);
+  console.log(`Path: ${report.inputPath}`);
+  console.log(`Mode: ${report.strict ? "strict" : "standard"}`);
+  if (report.configPath) {
+    console.log(`Config: ${report.configPath}`);
+  }
+  console.log(`Skill Dir: ${report.skillDir}`);
+  console.log(`Files Scanned: ${report.scanFiles.length}`);
+  if (report.decision.riskScore === null) {
+    console.log("Result: UNVERIFIABLE");
+  } else {
+    console.log(`Risk Score: ${report.decision.riskScore.toFixed(1)}/100`);
+    console.log(`Decision: ${report.decision.level}`);
+  }
+  if (report.unverifiableReasons && report.unverifiableReasons.length > 0) {
+    console.log("Unverifiable Reasons:");
+    for (const reason of report.unverifiableReasons) {
+      console.log(`- ${reason}`);
+    }
+  }
+  if (report.decision.chainMatches.length > 0) {
+    console.log("Attack Chains:");
+    for (const chain of report.decision.chainMatches) {
+      console.log(`- ${chain.id} (+${chain.bonus}): ${chain.description}`);
+    }
+  }
+  if (report.decision.findings.length > 0) {
+    console.log("Findings:");
+    for (const finding of report.decision.findings.slice(0, 10)) {
+      const fileText = finding.file ? ` (${finding.file})` : "";
+      console.log(`- [${finding.severity}/${finding.confidence}] ${finding.title}${fileText}`);
+    }
+  } else {
+    console.log("Findings: none");
+  }
+  console.log(`Note: ${report.note}`);
+}
+function printJsonLocalReport(report) {
+  console.log(JSON.stringify(report, null, 2));
+}
 
 // src/resolver/github.ts
 import path2 from "path";
@@ -1105,14 +1146,338 @@ async function runAddCommand(repo, rawOptions) {
   return runSkillsInstall(repo, options.skill);
 }
 
+// src/commands/scan-local.ts
+import fs2 from "fs";
+import path4 from "path";
+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 cliScanLocalOptionsSchema = z3.object({
+  config: z3.string().optional(),
+  strict: z3.boolean().optional(),
+  json: z3.boolean().optional(),
+  skill: z3.string().min(1).optional(),
+  maxFileBytes: z3.coerce.number().int().min(4096).max(5e6).optional(),
+  maxTotalFiles: z3.coerce.number().int().min(1).max(400).optional()
+});
+var effectiveScanLocalOptionsSchema = z3.object({
+  strict: z3.boolean(),
+  json: z3.boolean(),
+  skill: z3.string().min(1).optional(),
+  maxFileBytes: z3.number().int().min(4096).max(5e6),
+  maxTotalFiles: z3.number().int().min(1).max(400)
+});
+var DEFAULT_OPTIONS2 = {
+  strict: false,
+  json: false,
+  skill: void 0,
+  maxFileBytes: 25e4,
+  maxTotalFiles: 120
+};
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+function getNearbyPathSuggestions(targetPath) {
+  const parent = path4.dirname(targetPath);
+  if (!fs2.existsSync(parent)) {
+    return [];
+  }
+  const needle = path4.basename(targetPath).toLowerCase();
+  const suggestions = [];
+  for (const entry of fs2.readdirSync(parent, { withFileTypes: true })) {
+    if (entry.name.toLowerCase().includes(needle)) {
+      suggestions.push(path4.join(parent, entry.name));
+    }
+  }
+  return suggestions.slice(0, 5);
+}
+function isSkillFile(filePath) {
+  return path4.basename(filePath).toLowerCase() === "skill.md";
+}
+function isScannableTextFile(filePath) {
+  if (isSkillFile(filePath)) {
+    return true;
+  }
+  const ext = path4.extname(filePath).toLowerCase();
+  return ALLOWED_TEXT_EXTENSIONS2.has(ext);
+}
+function findSkillDirs(rootDir) {
+  const found = /* @__PURE__ */ new Set();
+  const stack = [{ dir: rootDir, depth: 0 }];
+  let seen = 0;
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+    seen += 1;
+    if (seen > 5e3) {
+      break;
+    }
+    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 formatCandidates(candidates) {
+  return candidates.map((candidate) => `- ${toPosixPath(candidate)}`).join("\n");
+}
+function resolveSkillDirectory(inputPath, preferredSkillName) {
+  const absoluteInput = path4.resolve(inputPath);
+  if (!fs2.existsSync(absoluteInput)) {
+    const suggestions = getNearbyPathSuggestions(absoluteInput);
+    const suggestionText = suggestions.length > 0 ? `
+Nearby paths:
+${formatCandidates(suggestions)}` : "";
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `Local path not found: ${toPosixPath(absoluteInput)}${suggestionText}`
+    );
+  }
+  const stat = fs2.statSync(absoluteInput);
+  if (stat.isFile()) {
+    if (!isSkillFile(absoluteInput)) {
+      throw new GuardSkillsError(
+        "INVALID_LOCAL_PATH",
+        "Local scan expects a directory or a SKILL.md file path."
+      );
+    }
+    return {
+      skillDir: path4.dirname(absoluteInput),
+      note: "Using parent directory of provided SKILL.md file."
+    };
+  }
+  const directSkillFile = path4.join(absoluteInput, "SKILL.md");
+  if (fs2.existsSync(directSkillFile) && fs2.statSync(directSkillFile).isFile()) {
+    return { skillDir: absoluteInput };
+  }
+  const discovered = findSkillDirs(absoluteInput);
+  if (discovered.length === 0) {
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `No SKILL.md found under: ${toPosixPath(absoluteInput)}`
+    );
+  }
+  if (preferredSkillName) {
+    const matches = discovered.filter(
+      (directory) => path4.basename(directory).toLowerCase() === preferredSkillName.toLowerCase()
+    );
+    if (matches.length === 1) {
+      const selected = matches[0];
+      if (!selected) {
+        throw new GuardSkillsError("INVALID_LOCAL_PATH", "Unable to resolve selected local skill.");
+      }
+      return {
+        skillDir: selected,
+        note: `Auto-selected skill '${preferredSkillName}' under the provided path.`
+      };
+    }
+    const available = discovered.map((directory) => path4.basename(directory));
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `Requested --skill '${preferredSkillName}' was not found.
+Available skills: ${available.join(", ")}`
+    );
+  }
+  if (discovered.length === 1) {
+    const selected = discovered[0];
+    if (!selected) {
+      throw new GuardSkillsError("INVALID_LOCAL_PATH", "Unable to resolve discovered local skill.");
+    }
+    return {
+      skillDir: selected,
+      note: "Auto-selected the only SKILL.md found under the provided path."
+    };
+  }
+  throw new GuardSkillsError(
+    "INVALID_LOCAL_PATH",
+    `Multiple skills found under path. Provide --skill <name>.
+${formatCandidates(discovered)}`
+  );
+}
+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: ${toPosixPath(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 = toPosixPath(path4.relative(skillDir, fullPath));
+      if (!isScannableTextFile(relativePath)) {
+        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 resolveEffectiveScanLocalOptions(cliOptions, config) {
+  const defaults = config.defaults ?? {};
+  const resolver = config.resolver ?? {};
+  return effectiveScanLocalOptionsSchema.parse({
+    strict: cliOptions.strict ?? defaults.strict ?? DEFAULT_OPTIONS2.strict,
+    json: cliOptions.json ?? defaults.json ?? DEFAULT_OPTIONS2.json,
+    skill: cliOptions.skill ?? DEFAULT_OPTIONS2.skill,
+    maxFileBytes: cliOptions.maxFileBytes ?? resolver.maxFileBytes ?? DEFAULT_OPTIONS2.maxFileBytes,
+    maxTotalFiles: cliOptions.maxTotalFiles ?? resolver.maxTotalFiles ?? DEFAULT_OPTIONS2.maxTotalFiles
+  });
+}
+async function runScanLocalCommand(inputPath, rawOptions) {
+  const cliOptions = cliScanLocalOptionsSchema.parse(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);
+  if (files.length === 0) {
+    throw new GuardSkillsError(
+      "INVALID_LOCAL_PATH",
+      `No scannable text files found in: ${toPosixPath(target.skillDir)}`
+    );
+  }
+  const resolvedSkill = {
+    source: `local:${toPosixPath(target.skillDir)}`,
+    owner: "local",
+    repo: "local",
+    defaultBranch: "local",
+    commitSha: "local",
+    skillName: options.skill ?? path4.basename(target.skillDir),
+    skillDir: toPosixPath(target.skillDir),
+    skillFilePath: "SKILL.md",
+    files,
+    unverifiableReasons
+  };
+  const scan = scanResolvedSkill(resolvedSkill);
+  const decision = calculateRiskScore(scan.findings, {
+    strict: options.strict,
+    trustCredits: 0,
+    hasUnverifiableContent: scan.hasUnverifiableContent
+  });
+  const noteParts = ["Local scan complete."];
+  if (target.note) {
+    noteParts.push(target.note);
+  }
+  if (decision.level === "UNSAFE" || decision.level === "CRITICAL" || decision.level === "UNVERIFIABLE") {
+    noteParts.push("Blocked-level risk detected.");
+  }
+  if (loadedConfig.path) {
+    noteParts.push(`Config: ${loadedConfig.path}`);
+  }
+  const report = {
+    command: "guardskills scan-local",
+    inputPath,
+    strict: options.strict,
+    configPath: loadedConfig.path ?? void 0,
+    decision,
+    scanFiles: resolvedSkill.files.map((file) => file.path),
+    skillDir: resolvedSkill.skillDir,
+    unverifiableReasons: scan.unverifiableReasons,
+    note: noteParts.join(" ")
+  };
+  if (options.json) {
+    printJsonLocalReport(report);
+  } else {
+    printHumanLocalReport(report);
+  }
+  return decision.level === "UNSAFE" || decision.level === "CRITICAL" || decision.level === "UNVERIFIABLE" ? 20 : 0;
+}
+
 // src/cli.ts
 async function main() {
   const program = new Command();
-  program.name("guardskills").description("Security wrapper around skills add").version("0.1.0-alpha.0");
+  program.name("guardskills").description("Security wrapper around skills add").version("0.1.0-alpha.3");
   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);
     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);
+    process.exitCode = code;
+  });
   await program.parseAsync(process.argv);
 }
 main().catch((error) => {

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "guardskills",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Security wrapper around skills add",
+  "keywords": [
+    "security",
+    "skills",
+    "cli",
+    "malware-detection",
+    "static-analysis",
+    "supply-chain",
+    "agent-skills",
+    "guardrails"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/felixondesk/guardskills.git"