skill-prescan

SKILL.md

---
name: skill-prescan
description: Simulate ClawHub's ClawScan security review before publishing. Sends SKILL.md content to a remote LLM (user-configured) for evaluation using the same prompt as the real scanner.
homepage: https://github.com/openclaw/clawhub
metadata: {"openclaw": {"emoji": "🔍"}}
---

# skill-prescan

Simulate ClawHub's ClawScan security review before publishing. This tool sends your SKILL.md content to a remote LLM service (that you configure) using the same system prompt as the real ClawHub scanner, allowing you to iterate on your skill documentation until it passes.

## When to Use

- Before publishing a new skill to ClawHub
- After modifying a skill that previously failed the security review
- To understand why ClawHub flagged your skill as "suspicious"
- To iterate without consuming publish attempts

## Requirements

- Python 3.8+
- An API key for an LLM service (OpenAI, Anthropic, or any OpenAI-compatible endpoint)

## Data Flow & Privacy

**This tool sends data to a remote LLM API.** When you run a scan:

1. The full content of the specified SKILL.md file is read from disk
2. It is sent via HTTPS to your configured LLM provider (OpenAI, Anthropic, or custom endpoint)
3. The LLM returns a security evaluation verdict

**What is transmitted:** The entire text content of the SKILL.md file you specify, wrapped in the ClawScan evaluation prompt.

**What is NOT transmitted:** No other files, environment variables, credentials, or system information beyond the single file you point at.

**Your responsibility:** Do not scan files containing secrets, API keys, or proprietary content unless you trust your configured LLM provider's data retention policy.

## Usage

```bash
# Basic scan (uses OPENAI_API_KEY env var)
python3 {baseDir}/scripts/scan.py path/to/SKILL.md

# Specify API key and model
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --api-key sk-xxx --model gpt-5.5

# Use a custom OpenAI-compatible endpoint
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --base-url https://your-gateway.com --model gpt-5.5

# Use Anthropic Claude
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --provider anthropic --api-key sk-ant-xxx

# Run multiple times to check consistency
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --runs 3

# Output raw JSON
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --json
```

## Model Selection

The real ClawHub scanner uses **gpt-5.5** with `reasoning.effort: "xhigh"` and `max_output_tokens: 16000`. For the most accurate simulation, use gpt-5.5 via any OpenAI-compatible endpoint (default).

| Provider | Flag | Models | Accuracy vs ClawHub |
|----------|------|--------|-------------------|
| OpenAI-compatible | `--provider openai` (default) | gpt-5.5, gpt-5, gpt-5.1 | Closest to real results |
| Anthropic | `--provider anthropic` | claude-sonnet-4-6, claude-opus-4-6 | More lenient |

Note: the real scanner uses the Responses API with extended reasoning, which is not available through Chat Completions. Results may be slightly more lenient than production.

## Understanding Results

### Verdicts

- **benign** — Your skill should pass ClawHub's review and be searchable.
- **suspicious** — Your skill will be flagged for Review. Review the concerns and user guidance.
- **malicious** — Your skill will be blocked entirely.

### Dimensions

The scanner evaluates 5 dimensions, each rated `ok`, `note`, or `concern`:
- **purpose_capability** — Is the stated purpose coherent with actual capabilities?
- **instruction_scope** — Are the instructions bounded and user-controlled?
- **install_mechanism** — Is the install path transparent and verifiable?
- **environment_proportionality** — Are credentials/environment requirements proportionate?
- **persistence_privilege** — Does the skill persist or escalate privileges?

### Key Rule from ClawHub's Scanner

> "A coherent skill with only purpose-aligned notes should remain benign with clear user guidance."
> "Shell commands, network calls, file I/O, credentials, or install steps are not malicious by themselves; classify based on purpose fit, scope, provenance, and artifact evidence."

## Writing Effective Safety Documentation

1. **Disclose all capabilities explicitly** — the scanner flags hidden or undisclosed behavior.
2. **Bound high-impact actions** — document user approval mechanisms, scope limits, reversibility, and containment.
3. **State structural limitations** — explicitly list what the tool cannot do.
4. **Use neutral framing** — describe behaviors factually rather than defensively.
5. **Be specific about data flows** — describe what is transmitted, to where, and what boundaries apply.

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `OPENAI_API_KEY` | API key for the LLM service | (required) |
| `OPENAI_BASE_URL` | Base URL for OpenAI-compatible API | `https://api.openai.com` |
| `SCAN_MODEL` | Model to use for scanning | `gpt-5.5` |
| `SCAN_PROVIDER` | Provider: `openai` or `anthropic` | `openai` |

## How It Works

The script reads your SKILL.md, wraps it in the same evaluation prompt that ClawHub's ClawScan uses (extracted from the [open-source ClawHub repository](https://github.com/openclaw/clawhub/blob/main/convex/lib/securityPrompt.ts)), and sends it to your configured LLM provider for evaluation.

**Simulation scope:** This tool evaluates instruction-only skills (SKILL.md without accompanying code files). The scan context assumes a single-file skill with no static scan findings — matching the common case for instruction-only skills on ClawHub. Skills with code files, complex install steps, or multiple artifacts may receive different results from the real scanner which inspects the full package.

## Limitations

- This is a simulation, not the real ClawHub scanner. Verdicts are approximate.
- Only evaluates the LLM (ClawScan) portion — does not replicate VirusTotal or SkillSpector scans.
- Assumes instruction-only skill context (single SKILL.md, no code files, clean static scan). Skills with code files will get different results on ClawHub.
- Uses Chat Completions API; ClawHub uses Responses API with `reasoning.effort: "xhigh"` which may produce stricter results.
- Results may vary between runs due to LLM non-determinism.
- The ClawHub scanner prompt may be updated at any time — check the source repo for the latest version.