guardskills 0.1.0-alpha.3 → 1.0.0

package/README.md

@@ -33,13 +33,13 @@ npx guardskills add https://github.com/vercel-labs/skills --skill find-skills
 
 ## Current Readiness
 
-- Current stage: **beta-quality**.
-- Good for internal use and early adopters.
-- Not final production-grade yet; see `PRODUCTION_READINESS.md`.
+- Current stage: **stable (v1.0.0)**.
+- Suitable for production use with standard security review practices.
 
 ## 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
@@ -95,6 +95,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
@@ -115,15 +121,29 @@ guardskills add owner/repo --skill name \
 
 ## Local Check (Folder on Disk)
 
-Current CLI release supports GitHub sources directly (`guardskills add <repo>`).  
-If you have a local skill folder, you can run the scanner manually:
+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:
 
-```powershell
-$env:SKILL_DIR = "C:/path/to/your/local-skill-folder"
-npx tsx --eval "import fs from 'node:fs'; import path from 'node:path'; import { scanResolvedSkill } from './src/scanner/scan.ts'; import { calculateRiskScore } from './src/scoring/engine.ts'; const root=process.env.SKILL_DIR; if(!root){throw new Error('SKILL_DIR missing')} const files=[]; const walk=(d)=>{for(const e of fs.readdirSync(d,{withFileTypes:true})){const p=path.join(d,e.name); if(e.isDirectory()) walk(p); else files.push({path:path.relative(root,p).replace(/\\\\/g,'/'),content:fs.readFileSync(p,'utf8')});}}; walk(root); const scan=scanResolvedSkill({source:'local',owner:'local',repo:'local',defaultBranch:'local',commitSha:'local',skillName:path.basename(root),skillDir:root,skillFilePath:'SKILL.md',files,unverifiableReasons:[]}); const decision=calculateRiskScore(scan.findings,{hasUnverifiableContent:scan.hasUnverifiableContent,strict:false,trustCredits:0}); console.log(JSON.stringify({level:decision.level,riskScore:decision.riskScore,findings:scan.findings},null,2));"
+```bash
+guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills --skill x-algo-post
 ```
 
-If the path is wrong, PowerShell returns an error before scan starts.
+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
 
@@ -170,6 +190,126 @@ Template files are included as:
 - `guardskills.config.json` (baseline default)
 - `guardskills.config.example.json` (copy/reference template)
 
+## OpenClaw Bot Instructions
+
+Use this section as instructions for OpenClaw so it runs `guardskills` before installing any skill.
+
+### Purpose
+
+`guardskills` is a security gate for skill installs. It scans skill content first, then decides if install should proceed.
+
+### Rule for OpenClaw
+
+Before any skill install, always run a `guardskills` scan first.
+
+### 1. Scan GitHub Skills
+
+Use `guardskills add` with `--dry-run` for scan-only mode.
+
+```bash
+guardskills add owner/repo --skill <skill-name> --dry-run
+```
+
+Example:
+
+```bash
+guardskills add expo/skills --skill expo-app-design --dry-run
+```
+
+If the user gives a full GitHub URL like:
+
+`https://github.com/expo/skills/tree/main/plugins/expo-app-design`
+
+convert it to:
+
+- repo: `expo/skills`
+- skill: `expo-app-design`
+
+Then run:
+
+```bash
+guardskills add expo/skills --skill expo-app-design --dry-run
+```
+
+For CI/machine output:
+
+```bash
+guardskills add owner/repo --skill <skill-name> --ci --json
+```
+
+### 2. Scan Local Skills
+
+Use `scan-local` when the skill is on disk:
+
+```bash
+guardskills scan-local C:\path\to\skill-folder
+```
+
+If multiple skills exist under a parent folder:
+
+```bash
+guardskills scan-local C:\path\to\skills --skill <skill-folder-name>
+```
+
+For JSON output:
+
+```bash
+guardskills scan-local C:\path\to\skill-folder --json
+```
+
+### 3. Scan Other Skills
+
+"Other skills" means any non-local skill from another GitHub repository.
+
+Use:
+
+```bash
+guardskills add owner/repo --skill <skill-name> --dry-run
+```
+
+Also supported:
+
+```bash
+guardskills add https://github.com/owner/repo --skill <skill-name> --dry-run
+```
+
+### How OpenClaw Should Interpret Results
+
+- `SAFE`: proceed.
+- `WARNING`: require confirmation before proceed (or explicit `--yes` behavior).
+- `UNSAFE`: block unless user explicitly asks for override (`--force`).
+- `CRITICAL`: block.
+- `UNVERIFIABLE`: block unless user explicitly allows override (`--allow-unverifiable`).
+
+### Recommended Install Workflow
+
+1. Run scan:
+
+```bash
+guardskills add owner/repo --skill <skill-name> --dry-run
+```
+
+2. Only if decision is acceptable, run install through guardskills:
+
+```bash
+guardskills add owner/repo --skill <skill-name>
+```
+
+Do not run `skills add` directly first.
+
+### Copy/Paste Bot Instruction Block
+
+```text
+Before installing any skill, always run guardskills first.
+For GitHub skills, run: guardskills add owner/repo --skill <skill-name> --dry-run
+For local skills, run: guardskills scan-local <path>
+If SAFE, proceed with guardskills add owner/repo --skill <skill-name>.
+If WARNING, ask for confirmation.
+If UNSAFE/CRITICAL, block.
+If UNVERIFIABLE, block unless user explicitly requests override.
+Never run skills add directly before a guardskills check.
+```
+
 ## Exit Codes
 
 - `0`: allowed/success

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("1.0.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);
     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("1.0.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);
     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.3",
+  "version": "1.0.0",
   "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"