guardskills 0.1.0-alpha.4 → 1.0.0

package/README.md

@@ -33,9 +33,8 @@ 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
 
@@ -191,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

@@ -1493,7 +1493,7 @@ async function runScanLocalCommand(inputPath, rawOptions) {
 // 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.3");
+  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;

package/dist/cli.js

@@ -1469,7 +1469,7 @@ async function runScanLocalCommand(inputPath, rawOptions) {
 // src/cli.ts
 async function main() {
   const program = new Command();
-  program.name("guardskills").description("Security wrapper around skills add").version("0.1.0-alpha.3");
+  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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardskills",
-  "version": "0.1.0-alpha.4",
+  "version": "1.0.0",
   "description": "Security wrapper around skills add",
   "keywords": [
     "security",