Skill: nutstrut/skill-vetter-v2 (version 0.0.5)

--- name: skill-vetter-v2 description: Analyze any skill for safety before use. Preserve local judgment, classify risk clearly, and optionally verify the final report with SettlementWitness. metadata: --------- # Skill Vetter v2 Analyze skills before installation or use. Classify capabilities, risks, and trust dependencies with structured local review. Optionally verify the completed report with SettlementWitness. This is a **packaged vetting skill**, not a thin wrapper. It preserves local inspection as the primary decision path and adds an optional verification layer for auditability. ## Data handling and trust This skill defines a **local review workflow** with an optional verification step for the final report. * Perform capability analysis and risk classification locally * Do **not** send secrets, credentials, private keys, seed phrases, personal data, or full private repositories to any external service * If optional verification is used, send only the minimum structured task data needed to validate the report * Verification does **not** decide whether a skill is safe to install; it only validates that the vetting report matches the stated evaluation spec * Identity is optional; no wallet access, account access, or credentials are required ## Core Principle Never outsource the safety decision. External systems may help verify that a report was produced correctly, but the actual judgment about whether a skill should be trusted remains local and reviewable. ## Quick Reference | Situation | Action | | ---------------------------------------------- | -------------------------------------------------------------- | | New skill from unknown source | Run full local vetting workflow | | Skill asks for secrets or credentials | Escalate risk immediately | | Skill writes outside workspace | Mark as high risk unless clearly justified | | Skill calls external services | Classify trust dependency and data exposure | | Skill contains obfuscation or hidden execution | Mark unsafe | | Final report is complete | Optionally verify the report structure and verdict consistency | | Verification returns PASS | Attach receipt metadata to the report | | Verification returns FAIL | Re-check findings and correct the report | | Verification returns INDETERMINATE | Hold for manual review; do not treat as verified | ## What This Skill Does Skill Vetter v2 evaluates a target skill across four dimensions: 1. **Purpose and scope** What the skill claims to do, and whether its requested capabilities match that purpose. 2. **Install-time behavior** File writes, package installs, hooks, system changes, or bootstrap modifications. 3. **Runtime behavior** Commands, file access, network access, external APIs, tool usage, and data handling. 4. **Trust dependency** Whether the skill depends on transparent and reviewable systems, or on opaque and unverifiable services. ## Core Execution Loop 1. Inspect the skill package locally * `SKILL.md` * `README.md` and references * scripts, hooks, assets, templates * metadata and install surface 2. Identify declared and implied capabilities * file reads and writes * command execution * package installation * network or API usage * handling of credentials, memory, or sensitive files 3. Evaluate risk * install-time risk * runtime risk * data exposure risk * trust dependency risk 4. Generate a structured report 5. Optional: verify the completed report * define a deterministic verification spec for the report structure and verdict logic * run verification only on the minimal structured report payload * attach receipt metadata only when verification passes ## Risk Evaluation Categories ### Install-Time Risk Review for: * file writes outside the workspace * package installs or dependency changes * shell profile or system configuration changes * hook registration or startup injection * hidden setup steps not stated in the docs ### Runtime Risk Review for: * external API calls * arbitrary command execution * broad file system access * credential discovery or token handling * browser/session access * transmission of user data or memory files ### Trust Dependency Classify the skill's external dependencies: * **none** — local-only behavior, no external trust dependency * **transparent** — external dependency is narrow, explicit, and independently understandable * **opaque** — external dependency is broad, hidden, unverifiable, or requests sensitive data ## Red Flags Reject or escalate immediately if you find: * requests for credentials, API keys, seed phrases, or private keys * access to secret stores or credential directories without a clear need * obfuscated or encoded execution logic intended to hide behavior * silent network transmission of prompts, memory, or workspace files * writes outside expected directories without a clear reason * privilege escalation or system-level modification * unexplained background processes, persistence, or surveillance behavior ## Output Format ```json id="m8yx3p" { "skill_name": "...", "purpose": "...", "source": "clawhub | github | local | other", "capabilities": ["..."], "install_risk": "low | medium | high | extreme", "runtime_risk": "low | medium | high | extreme", "trust_dependency": "none | transparent | opaque", "warnings": ["..."], "recommendations": ["..."], "verdict": "safe | caution | unsafe", "verified": false, "verification": { "status": "not_run | pass | fail | indeterminate", "receipt_id": null, "notes": "" } } ``` --- ## Example Usage ### Input (Skill to Review) ```json id="9j3kdx" { "skill_name": "example-email-sender", "source": "github", "description": "Sends automated emails using an external API", "files": ["SKILL.md", "scripts/send-email.sh"] } ``` ### Output (Vetting Report) ```json id="4n6rfa" { "skill_name": "example-email-sender", "purpose": "Send automated emails via external API", "source": "github", "capabilities": [ "network access", "external API calls", "file read/write" ], "install_risk": "low", "runtime_risk": "medium", "trust_dependency": "opaque", "warnings": [ "Uses external API with unclear data handling", "No transparency on where email content is sent" ], "recommendations": [ "Verify API endpoint and data handling policy", "Limit data exposure before use" ], "verdict": "caution", "verified": false, "verification": { "status": "not_run", "receipt_id": null, "notes": "" } } ``` --- ## Optional Verification Workflow Use verification only after the local review is complete. Recommended pattern: 1. Define a deterministic verification spec for the report * required fields present * risk labels internally consistent * verdict supported by findings * no prohibited data included 2. Submit only the structured report and spec 3. Interpret results conservatively * **PASS** → attach receipt metadata and mark `verified: true` * **FAIL** → correct the report and keep `verified: false` * **INDETERMINATE** → keep `verified: false` and escalate for manual review Verification is optional and must never override local safety concerns. ## OpenClaw Setup (Recommended) OpenClaw is the best fit for this skill because it supports packaged skills, hooks, and workspace context. ### Installation **Via ClawHub:** ```bash id="t2j9mf" clawdhub install skill-vetter-v2 ``` **Manual:** ```bash id="a1vk0r" git clone https://github.com/your-org/skill-vetter-v2.git ~/.openclaw/skills/skill-vetter-v2 ``` ### Optional Hook Install the reminder hook if you want a prompt to vet skills before trusting them: ```bash id="0xptv9" cp -r hooks/openclaw ~/.openclaw/hooks/skill-vetter-v2 openclaw hooks enable skill-vetter-v2 ``` ### Local Scan Helper Run the local helper against a skill folder: ```bash id="z7p2qs" bash scripts/scan-skill.sh /path/to/skill ``` This helper inventories files and flags common red-patterns locally. It does not make network calls. ## Generic Setup (Other Agents) Use this skill with Claude Code, Codex, Copilot, or other agents by copying the package into your skills directory and reviewing target skills locally. Suggested workflow: 1. Read the target `SKILL.md` 2. Read all scripts, hooks, and references 3. Run the local scan helper 4. Write the structured report 5. Optionally verify the report ## What This Is Not * not an installer * not an auto-executor for unknown code * not an external decision authority * not a replacement for human judgment on high-risk skills ## Outcome Agents can: * understand what a skill actually does before use * identify install-time and runtime risks clearly * separate transparent dependencies from opaque trust requirements * keep safety decisions local while optionally producing verifiable records ## Keywords ai-agents, skill-safety, risk-analysis, verification, trust, security

path: README.md
content: # Skill Vetter v2

**Know what a skill does before you trust it.**

Skill Vetter v2 is a packaged safety-review skill for evaluating agent skills before installation or use. It preserves a local, review-first workflow and adds optional SettlementWitness verification for the finished report.

## Why this exists

Most agent skills are installed based on a short description and a guess.

That creates avoidable risk:
- hidden file access
- undisclosed network behavior
- silent trust in opaque external services
- credential exposure or workspace exfiltration

Skill Vetter v2 makes those risks visible before a skill is trusted.

## What it analyzes

Every target skill is reviewed across four areas:

### 1. Purpose and scope
Does the actual package match the stated purpose?

### 2. Install-time behavior
Does it write files, register hooks, install packages, or modify environment state?

### 3. Runtime behavior
Does it execute commands, access sensitive files, call external services, or handle data broadly?

### 4. Trust dependency
Does it rely on narrow and understandable external systems, or on opaque services that require blind trust?

## Output

The skill produces a structured report with:
- capability inventory
- install-time risk
- runtime risk
- trust dependency classification
- warnings and recommendations
- final verdict: `safe`, `caution`, or `unsafe`

## SettlementWitness integration

This skill does **not** delegate the safety decision.

Optional verification is used only after local review is complete.
It can validate that the final report matches a deterministic spec and provide receipt metadata for auditability.

Use it conservatively:
- send only structured report data
- never send secrets, credentials, personal data, or full private repositories
- treat PASS as evidence that the report matches the spec, not as a substitute for judgment

## Included package structure

```text
skill-vetter-v2/
├── SKILL.md
├── README.md
├── _meta.json
├── .learnings/
├── assets/
├── hooks/
├── references/
└── scripts/
```

## Scripts

### `scripts/scan-skill.sh`
Local helper that inventories a skill directory and flags suspicious patterns such as:
- credential access attempts
- network calls
- package installs
- obfuscated execution
- writes outside expected scope

### `scripts/activator.sh`
Reminder hook content for prompting a vetting pass before a skill is trusted.

### `scripts/error-detector.sh`
Reminder that suspicious outputs or failures discovered during review should be captured in the final report.

## Hook

The OpenClaw hook injects a short reminder during bootstrap:
- review the full package, not just `SKILL.md`
- classify risk before installation
- keep verdict decisions local
- optionally verify the final report

## Best use cases

- reviewing third-party skills before install
- auditing internal packaged skills
- comparing multiple skills that solve the same task
- enforcing trust boundaries in autonomous agent environments

## Design rules

- preserve local judgment
- prefer transparent dependencies
- no mandatory identity
- no required credentials
- no blind PASS-to-trust shortcut
- verification augments review; it does not replace it

## Installation

Add this repository as a Claude/OpenClaw skill, or copy the folder into your local skills directory.

## Tags

ai-agents  
security  
risk-analysis  
trust  
verification  
skill-review


path: _meta.json
content: ownerId: kn71j6xbmpwfvx4c6y1ez8cd718081mg
slug: skill-vetter-v2
version: 2.0.0
publishedAt: 1774810862729

path: scripts/activator.sh
content: #!/bin/bash
# Skill Vetter v2 activator reminder
set -e
cat << 'EOF'
<skill-vetter-v2-reminder>
Before trusting or installing a skill:
- inspect the full package, not just the description
- classify install-time risk, runtime risk, and trust dependency
- record warnings and recommendations in a structured report
- keep the final safety decision local
- optionally verify the completed report only after local review is done
</skill-vetter-v2-reminder>
EOF


path: scripts/scan-skill.sh
content: #!/bin/bash
# Local scan helper for Skill Vetter v2
# Usage: ./scan-skill.sh /path/to/skill
set -euo pipefail

TARGET="${1:-}"
if [[ -z "$TARGET" ]]; then
  echo "Usage: $(basename "$0") /path/to/skill" >&2
  exit 1
fi
if [[ ! -d "$TARGET" ]]; then
  echo "Target is not a directory: $TARGET" >&2
  exit 1
fi

if ! command -v grep >/dev/null 2>&1; then
  echo "grep is required" >&2
  exit 1
fi

echo "SKILL VETTER LOCAL SCAN"
echo "Target: $TARGET"
echo "========================================"

echo
echo "Files:"
find "$TARGET" -maxdepth 4 -type f | sort

echo
echo "Potential indicators:"

declare -A CHECKS=(
  [network]='curl |wget |http://|https://|fetch\(|axios|requests\.'
  [credentials]='API_KEY|api_key|token|Authorization:|secret|~/.ssh|~/.aws|credentials'
  [dangerous_exec]='eval\(|exec\(|child_process|subprocess|os\.system|bash -c'
  [package_installs]='npm install|pnpm add|pip install|brew install|apt-get install|yum install'
  [privilege]='sudo|chmod 777|chown '
  [obfuscation]='base64|atob\(|fromCharCode|compressed|minified'
)

for name in "${!CHECKS[@]}"; do
  echo "--- $name ---"
  grep -RInE --exclude-dir=.git --exclude='*.png' --exclude='*.jpg' --exclude='*.jpeg' --exclude='*.gif' "${CHECKS[$name]}" "$TARGET" || true
  echo
 done

echo "Notes:"
echo "- Matches are signals, not automatic proof of malicious behavior."
echo "- Review context, scope, and stated purpose before assigning a verdict."
echo "- Keep the final decision local."


path: references/examples.md
content: # Examples

## Example verdict: safe

A formatting skill that only reads local markdown files and rewrites output style.

- install risk: low
- runtime risk: low
- trust dependency: none
- verdict: safe

## Example verdict: caution

A deployment helper that writes config files, installs a package, and calls a documented API.

- install risk: medium
- runtime risk: medium
- trust dependency: transparent
- verdict: caution

## Example verdict: unsafe

A skill that requests credentials, reads memory files without explanation, and sends prompts to an opaque external service.

- install risk: high
- runtime risk: extreme
- trust dependency: opaque
- verdict: unsafe

## Verification example

After local review, define a deterministic verification spec such as:
- all required report fields present
- verdict supported by listed warnings
- prohibited data absent

Only verify the structured report payload.


path: references/openclaw-integration.md
content: # OpenClaw Integration

Skill Vetter v2 works as a normal packaged skill in OpenClaw.

## Install

```bash
clawdhub install skill-vetter-v2
```

Or copy manually:

```bash
cp -r skill-vetter-v2 ~/.openclaw/skills/
```

## Optional hook

```bash
cp -r hooks/openclaw ~/.openclaw/hooks/skill-vetter-v2
openclaw hooks enable skill-vetter-v2
```

## Suggested workflow

1. Open the target skill folder
2. Read `SKILL.md`, `README.md`, scripts, hooks, references, and metadata
3. Run the local helper:
   ```bash
   bash scripts/scan-skill.sh /path/to/target-skill
   ```
4. Write the structured report
5. Optionally verify the final report

## Design intent

The hook is advisory. It does not install, execute, or approve the target skill.
The verdict remains local.


path: hooks/openclaw/handler.js
content: "use strict";
const REMINDER_CONTENT = `## Skill Vetter v2 Reminder

Before trusting or installing a skill:
- inspect the full package, not just SKILL.md
- review scripts, hooks, references, and metadata
- classify install-time risk, runtime risk, and trust dependency
- treat any request for secrets, credentials, or unexplained network access as a major warning
- keep the safety verdict local
- use optional verification only for the completed report`;
const handler = async (event) => {
  if (!event || typeof event !== 'object') return;
  if (event.type !== 'agent' || event.action !== 'bootstrap') return;
  if (!event.context || typeof event.context !== 'object') return;
  const sessionKey = event.sessionKey || '';
  if (sessionKey.includes(':subagent:')) return;
  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: 'SKILL_VETTER_V2_REMINDER.md',
      content: REMINDER_CONTENT,
      virtual: true,
    });
  }
};
module.exports = handler;
module.exports.default = handler;


path: hooks/openclaw/handler.ts
content: import type { HookHandler } from 'openclaw/hooks';

const REMINDER_CONTENT = `## Skill Vetter v2 Reminder

Before trusting or installing a skill:
- inspect the full package, not just SKILL.md
- review scripts, hooks, references, and metadata
- classify install-time risk, runtime risk, and trust dependency
- treat any request for secrets, credentials, or unexplained network access as a major warning
- keep the safety verdict local
- use optional verification only for the completed report`

const handler: HookHandler = async (event) => {
  if (!event || typeof event !== 'object') return;
  if (event.type !== 'agent' || event.action !== 'bootstrap') return;
  if (!event.context || typeof event.context !== 'object') return;

  const sessionKey = event.sessionKey || '';
  if (sessionKey.includes(':subagent:')) return;

  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: 'SKILL_VETTER_V2_REMINDER.md',
      content: REMINDER_CONTENT,
      virtual: true,
    });
  }
};

export default handler;


path: hooks/openclaw/HOOK.md
content: ---
name: skill-vetter-v2
description: "Injects a reminder to vet packaged skills before trusting or installing them"
metadata: {"openclaw":{"emoji":"🛡️","events":["agent:bootstrap"]}}
---

# Skill Vetter v2 Hook

Injects a reminder to review the full skill package and keep verdict decisions local.

## What It Does

- Fires on `agent:bootstrap`
- Adds a reminder to inspect the whole package, not just `SKILL.md`
- Prompts the agent to classify install-time risk, runtime risk, and trust dependency
- Reminds the agent that optional verification applies only to the final report


path: assets/REPORT-TEMPLATE.md
content: # Vetting Report Template

```json
{
  "skill_name": "",
  "purpose": "",
  "source": "clawhub | github | local | other",
  "capabilities": [],
  "install_risk": "low | medium | high | extreme",
  "runtime_risk": "low | medium | high | extreme",
  "trust_dependency": "none | transparent | opaque",
  "warnings": [],
  "recommendations": [],
  "verdict": "safe | caution | unsafe",
  "verified": false,
  "verification": {
    "status": "not_run | pass | fail | indeterminate",
    "receipt_id": null,
    "notes": ""
  }
}
```


path: assets/REVIEW-CHECKLIST.md
content: # Review Checklist

## Read first
- SKILL.md
- README.md
- _meta.json
- all scripts
- all hooks
- references and assets

## Capability review
- file reads
- file writes
- command execution
- package installs
- network access
- data handling
- secrets or credential access

## Red flags
- obfuscation
- unexplained network calls
- privilege escalation
- persistence mechanisms
- broad access to memory or secret stores

## Decision
- safe
- caution
- unsafe


path: .learnings/ERRORS.md
content: # Errors

Log unexpected review failures here.

Examples:
- parser errors while scanning a skill
- false negatives discovered after manual review
- missing files or malformed packages


path: .learnings/FEATURE_REQUESTS.md
content: # Feature Requests

Track user requests for future improvements.

Examples:
- richer capability classification
- better diffing between two skill versions
- export formats for audit trails


path: .learnings/LEARNINGS.md
content: # Learnings

Use this directory for improvements to the vetting workflow.

Examples:
- recurring red-flag patterns
- better trust-dependency heuristics
- false positives to avoid
- review templates that improve consistency


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)