🛡️ GuardSkills

Security Gate for Agent Skill Installations

Scan before you install. Every time.

When to Use • Scan Commands • Interpret Results • Gate Flags • Scoring

🚨 When to Use

Always run guardskills BEFORE installing any skill. This includes:

• Installing via skills add (skills.sh)

• Installing via playbooks add skill

• Installing via openskills install

• Installing via skillkit install

• Running any skill from a local path

• Installing from ClawHub

Never run a skill installer directly without scanning first.

📥 Installation

guardskills is available as an npm package:

npx guardskills --help

Or install globally:

npm install -g guardskills

🔍 Scan Commands

1. GitHub Skills (Most Common)

Scan a GitHub-hosted skill without installing:

npx guardskills add owner/repo --skill <skill-name> --dry-run

Also accepts full URLs:

npx guardskills add https://github.com/owner/repo --skill <skill-name> --dry-run

2. Local Skills

Scan a skill folder on disk:

npx guardskills scan-local <path-to-skill-folder>

If the path contains multiple skills:

npx guardskills scan-local <path-to-skills-root> --skill <skill-folder-name>

3. ClawHub Skills

Scan by identifier or full URL:

npx guardskills scan-clawhub owner/skill-slug npx guardskills scan-clawhub https://clawhub.ai/owner/skill-slug

4. Guarded Install (After Scan Passes)

If the scan result is acceptable, run the guarded install:

skills.sh

npx guardskills add owner/repo --skill <skill-name>

Or with provider prefix

npx guardskills skills add owner/repo --skill <skill-name> npx guardskills playbooks add skill owner/repo --skill <skill-name> npx guardskills openskills install owner/repo <skill-name> npx guardskills skillkit install owner/repo <skill-name>

guardskills will scan first, then hand off to the underlying installer only if the gate allows.

🎯 Interpret Results

guardskills produces one of five risk decisions:

Decision Meaning Action

SAFE No known high-risk patterns detected ✅ Proceed

WARNING Some medium-risk patterns found ⚠️ Ask user for confirmation

UNSAFE High-risk patterns detected 🚫 Block unless user explicitly overrides with --force

CRITICAL Hard-blocked — credential exfil, RCE, destructive ops, or priv escalation 🛑 Always block

UNVERIFIABLE Content could not be fully analyzed 🚫 Block unless user explicitly allows with --allow-unverifiable

How to Respond to Each Decision

SAFE → Proceed with the install. WARNING → Tell the user what was found. Ask if they want to continue. UNSAFE → Tell the user the skill is high-risk. Do NOT install unless they explicitly say to override. CRITICAL → Tell the user the skill is blocked. Do NOT install. No override available. UNVERIFIABLE → Tell the user the content couldn't be fully scanned. Do NOT install unless they explicitly allow.

🏁 Gate Flags

Flag Purpose

--dry-run

Scan + decision only, no install handoff

--ci

Deterministic gate mode, no install handoff, for CI pipelines

--json

Machine-readable JSON output

--yes

Accept WARNING without prompting

--force

Accept UNSAFE (use with extreme caution)

--allow-unverifiable

Accept UNVERIFIABLE results

--strict

Use stricter scoring thresholds

🔧 Resolver Controls

Fine-tune GitHub API behavior:

npx 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

📊 Scoring Logic

guardskills uses a two-layer model:

Layer 1: Hard-Block Guardrails

A finding triggers an automatic hard block when all of these are true:

• Severity is CRITICAL

• Confidence is high

• Type is CREDENTIAL_EXFIL , DESTRUCTIVE_OP , REMOTE_CODE_EXEC , or PRIV_ESCALATION

Layer 2: Weighted Risk Score (0–100)

risk_score = clamp( sum(base_points × confidence_multiplier)

• chain_bonuses − trust_credits, 0, 100 )

Severity base points: CRITICAL=50, HIGH=25, MEDIUM=12, LOW=5, INFO=0

Confidence multipliers: high=1.0, medium=0.7, low=0.4

Standard thresholds:

Score Decision

0–29 SAFE

30–59 WARNING

60–79 UNSAFE

80–100 CRITICAL

Strict thresholds (--strict ):

Score Decision

0–19 SAFE

20–39 WARNING

40–59 UNSAFE

60–100 CRITICAL

📋 Exit Codes

Code Meaning

0

Allowed / success

10

Warning not confirmed

20

Blocked (UNSAFE, CRITICAL, or UNVERIFIABLE without override)

30

Runtime / internal error

🔄 Recommended Workflow

Follow this workflow every time you install a skill:

Scan first — choose the right command for the source type:

GitHub

npx guardskills add owner/repo --skill <name> --dry-run

Local

npx guardskills scan-local <path>

ClawHub

npx guardskills scan-clawhub owner/slug

Read the decision — check if it's SAFE, WARNING, UNSAFE, CRITICAL, or UNVERIFIABLE.

Act on the decision:

• SAFE → proceed with guarded install

• WARNING → inform user, ask for confirmation

• UNSAFE/CRITICAL → block and explain findings

• UNVERIFIABLE → block and explain

Install through guardskills (never directly):

npx guardskills add owner/repo --skill <name>

⚙️ Configuration

guardskills supports a config file (guardskills.config.json ) for repository-level policy:

{ "defaults": { "strict": false, "ci": false, "json": false, "yes": false, "dryRun": false, "force": false, "allowUnverifiable": false }, "resolver": { "githubTimeoutMs": 15000, "githubRetries": 2, "githubRetryBaseMs": 300, "maxFileBytes": 250000, "maxAuxFiles": 40, "maxTotalFiles": 120 }, "policy": { "allowForce": true, "allowUnverifiableOverride": true, "allowedOwners": [], "blockedOwners": [], "allowedRepos": [], "blockedRepos": [] } }

📚 References

• guardskills on npm

• guardskills on GitHub

• Scanner Rule Matrix

📄 License

MIT License — see LICENSE for details.

🛡️ Scan before you install. Every time.

guardskills on GitHub · guardskills on npm