skill-convertor/docs/superpowers/specs/skill-generator-规范.md at main

admin/skill-convertor

Fork 0

Files

zhaoyilun ff748ebbeb chore: initial commit

2026-04-15 01:17:01 +08:00

7.5 KiB

Raw Permalink Blame History

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

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

输入

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

js_script_path：脚本文件原路径
js_script_code：脚本内容
skill_name（可选）：技能目录名（kebab-case）
skill_domain（可选）：目标站点 host（如 www.zhihu.com）
skill_use_case：一句话任务说明
tool_name（可选）：工具名（默认 derive）
tool_description（可选）
arg_spec（可选）：参数说明映射，例如 {top_n: "...", body: "..."}
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 脚本适配要求

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

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

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

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

如有参数，必须有：

[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：

{
  "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/.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/.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) 生成流程（算法）

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

8) 验收清单（交付前）

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

7.5 KiB Raw Permalink Blame History Unescape Escape