guardskills 1.0.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # guardskills
 
-`guardskills` is a security wrapper around `skills` installation.
+`guardskills` is a security wrapper around skill installation CLIs (`skills`, `playbooks`, `openskills`, `skillkit`).
 
 GitHub: https://github.com/felixondesk/guardskills
 
@@ -16,12 +16,24 @@ use:
 npx guardskills add https://github.com/vercel-labs/skills --skill find-skills
 ```
 
+Or provider-prefixed wrappers:
+
+```bash
+npx guardskills skills add https://github.com/vercel-labs/skills --skill find-skills
+npx guardskills skills add planetscale/database-skills
+npx guardskills playbooks add skill anthropics/skills --skill frontend-design
+npx guardskills openskills install anthropics/skills ui-designer
+npx guardskills openskills install anthropics/skills
+npx guardskills skillkit install rohitg00/skillkit dev-tools
+npx guardskills skillkit install rohitg00/skillkit
+```
+
 ## What It Does
 
 1. Resolves a skill from GitHub.
 2. Scans resolved files for malicious patterns.
 3. Computes a risk decision (`SAFE`, `WARNING`, `UNSAFE`, `CRITICAL`, `UNVERIFIABLE`).
-4. Proceeds to `npx skills add ...` only if gate policy allows.
+4. Proceeds to the selected installer CLI only if gate policy allows.
 
 ## Security Notice
 
@@ -33,13 +45,21 @@ npx guardskills add https://github.com/vercel-labs/skills --skill find-skills
 
 ## Current Readiness
 
-- Current stage: **stable (v1.0.0)**.
+- Current stage: **stable (v1.2.0)**.
 - Suitable for production use with standard security review practices.
 
 ## Implemented Features
 
-- `guardskills add <repo> --skill <name>`
+- `guardskills add <repo> --skill <name>` (legacy alias for `guardskills skills add`)
+- `guardskills skills add <repo> --skill <name>`
+- `guardskills skills add <repo>` (scan all discovered skills, then skills.sh interactive selection)
+- `guardskills playbooks add skill <repo> --skill <name>`
+- `guardskills openskills install <repo> <skill>`
+- `guardskills openskills install <repo>` (scan all discovered skills, then openskills interactive selection)
+- `guardskills skillkit install <repo> <skill>`
+- `guardskills skillkit install <repo>` (scan all discovered skills, then skillkit install flow)
 - `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
@@ -60,7 +80,7 @@ npx guardskills add https://github.com/vercel-labs/skills --skill find-skills
   - `--max-file-bytes`
   - `--max-aux-files`
   - `--max-total-files`
-- Installer handoff to `npx skills add ...` when allowed
+- Installer handoff to `npx skills|playbooks|openskills|skillkit ...` when allowed
 - Structured resolver error taxonomy + retry/backoff
 - Tests:
   - fixture scanner tests (`safe`, `warning`, `malicious`, `prose-only`)
@@ -89,61 +109,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-clawhub owner/skill-slug
+```
+
+Scan by full ClawHub link:
 
 ```bash
-guardskills scan-local C:\Felix\Skills\x-algo-skills\.github\skills\x-algo-post --json
+guardskills scan-clawhub https://clawhub.ai/owner/skill-slug
 ```
 
-If your path contains multiple skills, select one by directory name:
+JSON output:
 
 ```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 --json
 ```
 
-Path handling:
+## Resolver Controls
 
-- 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 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
 
@@ -202,77 +258,64 @@ Use this section as instructions for OpenClaw so it runs `guardskills` before in
 
 Before any skill install, always run a `guardskills` scan first.
 
-### 1. Scan GitHub Skills
-
-Use `guardskills add` with `--dry-run` for scan-only mode.
+### 1. Local Skills
 
 ```bash
-guardskills add owner/repo --skill <skill-name> --dry-run
+guardskills scan-local <path-to-skill-folder>
 ```
 
-Example:
+If multiple skills are found:
 
 ```bash
-guardskills add expo/skills --skill expo-app-design --dry-run
+guardskills scan-local <path-to-skills-root> --skill <skill-folder-name>
 ```
 
-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:
+### 2. GitHub Skills
 
 ```bash
-guardskills add expo/skills --skill expo-app-design --dry-run
+guardskills add owner/repo --skill <skill-name> --dry-run
 ```
 
-For CI/machine output:
+Also supported:
 
 ```bash
-guardskills add owner/repo --skill <skill-name> --ci --json
+guardskills add https://github.com/owner/repo --skill <skill-name> --dry-run
 ```
 
-### 2. Scan Local Skills
+### 3. `skills.sh` Skills
 
-Use `scan-local` when the skill is on disk:
+Use the same guarded GitHub flow before install:
 
 ```bash
-guardskills scan-local C:\path\to\skill-folder
+guardskills add owner/repo --skill <skill-name> --dry-run
 ```
 
-If multiple skills exist under a parent folder:
+If allowed:
 
 ```bash
-guardskills scan-local C:\path\to\skills --skill <skill-folder-name>
+guardskills add owner/repo --skill <skill-name>
 ```
 
-For JSON output:
+### 4. ClawHub Skills
+
+Use `scan-clawhub` with either identifier or full URL:
 
 ```bash
-guardskills scan-local C:\path\to\skill-folder --json
+guardskills scan-clawhub owner/skill-slug
 ```
 
-### 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
+guardskills scan-clawhub https://clawhub.ai/owner/skill-slug
 ```
 
-Also supported:
+For machine output:
 
 ```bash
-guardskills add https://github.com/owner/repo --skill <skill-name> --dry-run
+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.
@@ -283,13 +326,25 @@ guardskills add https://github.com/owner/repo --skill <skill-name> --dry-run
 
 ### Recommended Install Workflow
 
-1. Run scan:
+1. Run scan for source type:
 
 ```bash
 guardskills add owner/repo --skill <skill-name> --dry-run
 ```
 
-2. Only if decision is acceptable, run install through guardskills:
+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>
@@ -301,9 +356,10 @@ Do not run `skills add` directly first.
 
 ```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>.
+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.