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

# 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).

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

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), 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.