📦 skill-prescan — 技能预扫描

技能预扫描（skill-prescan） 在发布到ClawHub之前，预扫描您的SKILL.md文件。该工具模拟ClawScan安全审查，使用与真实ClawHub扫描器相同的系统提示和评估标准，允许您迭代您的技能文档，直到它通过审查。

何时使用：

• 在发布新技能到ClawHub之前
• 修改之前未通过安全审查的技能
• 了解为什么ClawHub将您的技能标记为“可疑”
• 在不消耗发布尝试的情况下本地迭代

要求：

• Python 3.8+
• OpenAI API密钥（或任何OpenAI兼容API）

使用方法：

# 基本扫描（使用OPENAI_API_KEY环境变量）
python3 {baseDir}/scripts/scan.py path/to/SKILL.md
# 指定API密钥和模型
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --api-key sk-xxx --model gpt-5.5
# 使用自定义OpenAI兼容端点
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --base-url https://your-gateway.com --model gpt-5.5
# 使用Anthropic Claude
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --provider anthropic --api-key sk-ant-xxx
# 运行多次以检查一致性
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --runs 3
# 输出原始JSON
python3 {baseDir}/scripts/scan.py path/to/SKILL.md --json

模型选择： 真实的ClawHub扫描器使用gpt-5.5，reasoning.effort为“xhigh”。为了获得最准确的本地模拟，使用gpt-5.5通过任何OpenAI兼容端点（默认）。

提供者标志 | 模型 | 准确性与ClawHub ---------|------|------------------- OpenAI兼容 | --provider openai（默认）| gpt-5.5, gpt-5, gpt-5.1 | 最接近真实结果 Anthropic | --provider anthropic | claude-sonnet-4-6, claude-opus-4-6 | 更宽松

注意：真实扫描器使用带有扩展推理的响应API，这不通过聊天补全可用。本地结果可能比生产环境更宽松。

理解结果： 判决：

• benign — 您的技能应该通过ClawHub的审查并可被搜索。
• suspicious — 您的技能将被标记并从搜索中隐藏。审查问题。
• malicious — 您的技能将被完全阻止。

发现： 每个发现都有一个状态：

• note — 与目的相符的行为，用户应该知道。
• concern — 扫描器认为过于宽泛、无边界或未充分披露的行为。一个或多个问题触发可疑。

关键规则来自ClawHub的扫描器： “一个连贯的技能，只有与目的相符的笔记，应该保持良性，并提供清晰的用户指南。” 如果您的技能在没有任何问题（只有笔记）的情况下被标记为可疑，这意味着扫描器认为笔记的组合是“过于宽泛的”。这更难通过文档来解决。

编写有效的安全文档：

• 明确披露所有功能 — 扫描器标记隐藏或未披露的行为。
• 限制高影响行为 — 文档用户批准机制、范围限制、可逆性和封闭性。
• 状态结构限制 — 明确列出工具不能做什么。
• 使用中立框架 — 事实上描述行为，而不是防御性地描述。
• 具体描述数据流 — 描述传输的内容、传输到哪里以及适用的边界。

环境变量： 变量 | 描述 | 默认值 -----|------|------ OPENAI_API_KEY | LLM服务的API密钥（必需） | OPENAI_BASE_URL | OpenAI兼容API的基本URL | https://api.openai.com SCAN_MODEL | 用于扫描的模型 | gpt-5.5 SCAN_PROVIDER | 提供者：openai或anthropic | openai

工作原理： 扫描器将您的SKILL.md内容发送到LLM，使用与ClawHub的ClawScan相同的系统提示（从开源ClawHub存储库中提取）。LLM在多个安全维度上评估您的技能并返回判决。

限制：

• 本地扫描使用聊天补全API；ClawHub使用带有reasoning.effort： “xhigh”的响应API，这可能会产生更严格的结果。
• ClawHub还单独运行VirusTotal扫描 —— 该工具仅模拟LLM（ClawScan）部分。
• 结果可能因LLM温度（默认为1.0）而在运行之间有所不同。
• 扫描器提示可能会在任何时候由ClawHub更新 —— 检查源存储库以获取最新版本。