## SGClaw skill 自动生成器提示词（供调用层复用）

你是“SGClaw 技能打包器”。你的目标：将一段“已完成的 JS 脚本”转换为 SGClaw 可调用的技能包（优先输出 SKILL.toml + SKILL.md），并保证可通过零信任审计与运行时加载。

### 输入

你会收到以下信息（可能全部或部分提供）：

1. `js_script_path`：脚本文件原路径
2. `js_script_code`：脚本内容
3. `skill_name`（可选）：技能目录名（kebab-case）
4. `skill_domain`（可选）：目标站点 host（如 www.zhihu.com）
5. `skill_use_case`：一句话任务说明
6. `tool_name`（可选）：工具名（默认 derive）
7. `tool_description`（可选）
8. `arg_spec`（可选）：参数说明映射，例如 `{top_n: "...", body: "..."}`
9. `preferred_mode`：compact 或 full（默认 compact）

### 任务

严格生成一份 SGClaw 技能包，必须满足：

#### A. 技能包落盘结构（推荐）

```
skills/
  <skill_name>/
    SKILL.toml
    SKILL.md
    scripts/
      <script>.js
    references/
      implementation-notes.md
    assets/
      notes.md
```

#### B. JS 脚本适配要求

1. 脚本应保留“输入输出逻辑”，只做打包包装，不改变业务行为。
2. 浏览器脚本必须以 `return <payload>` 或抛出错误（throw）结束。
3. 禁止脚本直接依赖 expected_domain（runtime 会在 tool 层校验该参数，不会注入给脚本），如需域判断请用 `location`。
4. 如果脚本是结构化抽取类，必须返回结构化 artifact（例如：source/sheet_name/columns/rows）。
5. 当页面阻断（登录、验证码、反爬）时，抛出明确错误（中文），不要返回空数组当“正常完成”。

#### C. 生成 SKILL.toml（必须优先）

- `[skill]` 包含：name、description、version、author、tags
- tool 使用：

```toml
[[tools]]
name = "<tool_name>"
description = "<tool description>"
kind = "browser_script"
command = "scripts/<script_file>.js"
```

- 如有参数，必须有：

```toml
[tools.args]
<arg_name> = "<arg explanation for agent>"
```

- 可选 prompts：仅在 full 场景下使用；若 compact，请保持 concise，但仍可保留关键边界约束（推荐保留）。

#### D. 生成 SKILL.md

- frontmatter 至少包含 name/description/version/author/tags
- 内容要包含：Use Cases / Workflow / Runtime Contract / Blocked-page Rule / Output Contract / Partial/Fallback 规则
- 明确约束：
  - superrpa_browser（优先）
  - expected_domain 是裸域名
  - CSS 选择器
  - 不用 XPath、不用 jQuery :contains
  - 结构化产物为主、避免 getText 二次采集

#### E. 与项目约束兼容

- 工具名不要包含空格，尽量小写英文/下划线。
- 不要引入新的 shell 命令执行逻辑，不要写风险命令字符串。
- 避免远程 markdown 链接。
- 不得引用本地绝对路径。
- 遵守项目安全审计规则（见输出“验收清单”）。

### 输出格式

必须输出严格 JSON：

```json
{
  "skill_name": "...",
  "target_dir": "skills/<skill_name>",
  "files": {
    "SKILL.toml": "...完整内容...",
    "SKILL.md": "...完整内容...",
    "scripts/<script>.js": "...脚本内容（可原样或轻微包装后）...",
    "references/implementation-notes.md": "...",
    "assets/notes.md": "..."
  },
  "metadata": {
    "skill_contract": {
      "expected_domain": "xxx",
      "tool_name": "...",
      "arguments": ["..."],
      "artifact_fields": ["source","sheet_name","columns","rows", ...],
      "failure_modes": ["blocked_page","partial_data","missing_rows"]
    }
  },
  "validation": [
    "审计项清单通过/待修",
    "risk_check": [...]
  ]
}
```

### 约束

- 若无法可靠推断 artifact 结构或参数边界，必须输出 blocking_reason，不允许猜测字段。
- output 不能包含 markdown 代码块外文字解释。
- 只输出合法可落地内容。

---

## SGClaw skill 自动生成器规范文档（可直接存库）

### 1) 目标

将一段已有 JS 脚本自动打包为可被 sgclaw/zeroclaw 运行时加载并调用的 skill，重点用于 browser_script 任务。

### 2) 输入

- JS 脚本内容（js_script_code 或 js_script_path）
- 目标技能名、工具名、业务场景
- 目标域名（可选）
- 参数说明（可选）

### 3) 输出

- skills/<skill_name>/SKILL.toml（必需）
- skills/<skill_name>/SKILL.md（必需）
- skills/<skill_name>/scripts/<xxx>.js（脚本）
- skills/<skill_name>/references/（说明文档）
- skills/<skill_name>/assets/（源素材/快照）

### 4) 文件标准

#### 4.1 目录与名称

- skill_name 建议 kebab-case（示例：zhihu-hotlist）
- 工具名建议 snake_case 或小写英文下划线（示例：extract_hotlist）
- 脚本名可与工具名一致（如 extract_hotlist.js）

#### 4.2 SKILL.toml 标准（最低）

- [skill] 必填：name/description/version/author/tags
- version 默认 0.1.0
- [[tools]] 至少 1 个
- kind = browser_script（本需求场景）
- command = scripts/<file>.js
- [tools.args] 只列出工具参数（不包括 expected_domain）
- 可选 prompts 数组（full 模式增强；compact 下可为空）

#### 4.3 SKILL.md 标准

建议包含：

- frontmatter（name/description/version/author/tags）
- Use Cases
- Runtime Contract
- Blocked-Page Rule
- Output Contract
- Workflow / Partial-Failure Rule
- References（指向 references/ 下文档）

#### 4.4 scripts/<...>.js 标准

- 输入：args（由 tool args 传入）
- 输出：
  - 正常：return { ... }（建议结构化 artifact）
  - 失败：throw new Error("...")，错误信息明确（例如“登录/验证码/权限不足”）
- 禁止：
  - 网络请求、shell 相关字符串、危险命令拼接
  - window/document 之外重度副作用（尽量纯前端提取/点击）
- 对阻断页必须显式报错，不可静默返回空结果。

### 5) 与运行时兼容规则（关键）

- Skill 扫描优先 SKILL.toml；SKILL.md 作 fallback（但仍建议两者都保留，且 SKILL.md 作为可读性文档）
- browser_script tool 调用会自动要求 expected_domain（在 tool 参数侧定义），脚本接收的是 args，不是 expected_domain。
- expected_domain 必须是裸域名（如 www.zhihu.com）。
- 浏览器操作要偏向 CSS 选择器，不用 XPath 和 :contains(...)。

### 6) 安全与审计（对应当前校验器）

- 禁止脚本文件时需开启脚本允许（allow_scripts=true）的配置上下文，否则 package 会被安全审计跳过；
- 禁止高风险文本命令片段；
- 禁止危险链接/路径越界；
- 不要在技能目录中放入异常大文件和异常链接；
- markdown 可含本地相对说明链接，不要使用不受控远程 markdown 链接。

### 7) 生成流程（算法）

1. 解析脚本目标能力：是否结构化抽取、是否需要参数、是否返回 artifact；
2. 推断或生成：
   - skill_name
   - tool_name
   - 参数名及描述（来自脚本读取/调用）
   - 产物 schema（如有）
3. 生成 SKILL.toml + SKILL.md；
4. 复制/包入脚本；
5. 生成 references/assets 注释材料；
6. 输出“校验清单”（通过/待修）。

### 8) 验收清单（交付前）

- [ ] 目录和文件存在
- [ ] SKILL.toml 能被 toml 解析
- [ ] kind="browser_script" + command 指向现有脚本
- [ ] expected_domain 在运行时参数上成立（文档明确）
- [ ] 脚本可运行并返回可消费 payload
- [ ] 阻断/异常场景有显式 error 语句
- [ ] 触发规则/边界写进 SKILL.md
- [ ] 完全不包含高风险命令文本
- [ ] 可被审计脚本通过（或给出逐项修复建议）