guardskills 0.1.0-alpha.4 → 1.1.0

package/README.md

@@ -33,14 +33,14 @@ 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>`
+- `guardskills scan-clawhub <identifier>`
 - 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
@@ -90,61 +90,97 @@ npm run ci
 npm run audit:prod
 ```
 
-Local dry-run:
+## Scan Skills by Source
+
+Use this section as the clean reference for supported scan sources.
+
+### 1. Local Skills
+
+Scan a skill folder on disk:
 
 ```bash
-guardskills add https://github.com/vercel-labs/skills --skill find-skills --dry-run
+guardskills scan-local C:\path\to\skill-folder
 ```
 
-Local folder check:
+If the path contains multiple skills:
 
 ```bash
-guardskills scan-local C:\path\to\skill-folder
+guardskills scan-local C:\path\to\skills --skill <skill-folder-name>
 ```
 
-Deterministic CI gate:
+JSON output:
 
 ```bash
-guardskills add https://github.com/vercel-labs/skills --skill find-skills --ci --json
+guardskills scan-local C:\path\to\skill-folder --json
 ```
 
-With resolver reliability controls:
+### 2. GitHub Skills
+
+Scan a GitHub-hosted skill without installing:
 
 ```bash
-guardskills add owner/repo --skill name \
-  --github-timeout-ms 15000 \
-  --github-retries 2 \
-  --github-retry-base-ms 300 \
-  --max-file-bytes 250000 \
-  --max-aux-files 40 \
-  --max-total-files 120
+guardskills add owner/repo --skill <skill-name> --dry-run
 ```
 
-## Local Check (Folder on Disk)
+Also supported:
 
-Scan any local skill directory:
+```bash
+guardskills add https://github.com/owner/repo --skill <skill-name> --dry-run
+```
+
+CI/machine-readable output:
 
 ```bash
-guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills\x-algo-post
+guardskills add owner/repo --skill <skill-name> --ci --json
 ```
 
-JSON output:
+### 3. `skills.sh` Skills
+
+For `skills.sh` installs, run the same guarded GitHub scan flow first:
+
+```bash
+guardskills add owner/repo --skill <skill-name> --dry-run
+```
+
+Then, only if acceptable, run the guarded install handoff:
+
+```bash
+guardskills add owner/repo --skill <skill-name>
+```
+
+Never run `skills add ...` directly before `guardskills`.
+
+### 4. ClawHub Skills
+
+Scan by ClawHub identifier:
 
 ```bash
-guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills\x-algo-post --json
+guardskills scan-clawhub owner/skill-slug
 ```
 
-If your path contains multiple skills, select one by directory name:
+Scan by full ClawHub link:
 
 ```bash
-guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills --skill x-algo-post
+guardskills scan-clawhub https://clawhub.ai/owner/skill-slug
 ```
 
-Path handling:
+JSON output:
 
-- 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>`
+```bash
+guardskills scan-clawhub https://clawhub.ai/owner/skill-slug --json
+```
+
+## Resolver Controls
+
+```bash
+guardskills add owner/repo --skill name \
+  --github-timeout-ms 15000 \
+  --github-retries 2 \
+  --github-retry-base-ms 300 \
+  --max-file-bytes 250000 \
+  --max-aux-files 40 \
+  --max-total-files 120
+```
 
 ## Configuration File
 
@@ -191,6 +227,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. Local Skills
+
+```bash
+guardskills scan-local <path-to-skill-folder>
+```
+
+If multiple skills are found:
+
+```bash
+guardskills scan-local <path-to-skills-root> --skill <skill-folder-name>
+```
+
+### 2. GitHub Skills
+
+```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
+```
+
+### 3. `skills.sh` Skills
+
+Use the same guarded GitHub flow before install:
+
+```bash
+guardskills add owner/repo --skill <skill-name> --dry-run
+```
+
+If allowed:
+
+```bash
+guardskills add owner/repo --skill <skill-name>
+```
+
+### 4. ClawHub Skills
+
+Use `scan-clawhub` with either identifier or full URL:
+
+```bash
+guardskills scan-clawhub owner/skill-slug
+```
+
+```bash
+guardskills scan-clawhub https://clawhub.ai/owner/skill-slug
+```
+
+For machine output:
+
+```bash
+guardskills scan-clawhub https://clawhub.ai/owner/skill-slug --json
+```
+
+If the ClawHub API does not expose GitHub source metadata, `guardskills` falls back to scanning the downloadable ClawHub archive payload.
+
+### 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 for source type:
+
+```bash
+guardskills add owner/repo --skill <skill-name> --dry-run
+```
+
+or
+
+```bash
+guardskills scan-local <path>
+```
+
+or
+
+```bash
+guardskills scan-clawhub https://clawhub.ai/owner/skill-slug
+```
+
+2. Only if decision is acceptable, run install through guardskills (GitHub/skills.sh flow):
+
+```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 local skills, run: guardskills scan-local <path>
+For GitHub or skills.sh skills, run: guardskills add owner/repo --skill <skill-name> --dry-run
+For ClawHub skills, run: guardskills scan-clawhub <owner/slug-or-full-url>
+If SAFE, proceed.
+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