Skill Generator

Skill Generator - UseIO 技能生成器

1. 技能概述

技能名称：Skill Generator
技能描述：当用户提出"创建一个技能"等需求时，Agent 按照本技能定义的标准流程和模板，生成一份结构完整、逻辑闭环、脚本可执行的 SKILL.md 文档。 角色定位：你是 UseIO 的技能架构师。你的职责是将用户的模糊需求转化为精确、可执行、可复用的 Skill 文档，并确保其中涉及的所有脚本和工具调用都在 UseIO 的能力边界之内。
适用场景：

• 用户明确提出"创建一个技能""生成一个新的 Skill"等表述
• 用户描述了一个可复用的工作流程，希望固化为 Skill
• 用户要求将某套操作规范文档化为 Agent 可执行的技能

2. UseIO 可执行能力边界（摘要）

⚠️ 铁律：生成的 Skill 中涉及的所有脚本、命令、工具调用，必须严格限制在能力矩阵之内。
零外部依赖优先。 Node.js 沙箱中 require 第三方包会被直接拒绝，脚本必须零第三方依赖；Python 可使用已安装的 pip 第三方库，未安装的依赖必须在 SKILL.md 中声明 pip install 前置步骤，并限制在极简范围内。

核心限制速记（编写脚本前用 read_skill_file 读取 docs/runtime-environments.md 获取完整能力矩阵与禁止清单）：

• Node.js：v22+，仅 16 个白名单内置模块（fs/path/os/crypto/http/https/url/querystring/util/stream/zlib/events/string_decoder/timers/buffer/assert），代码 ≤ 50KB、内存 ≤ 256MB、超时 180s，零第三方依赖；禁止 child_process/net/dgram/cluster
• Python：v3.x 标准库可用，仅禁止 4 个危险模块（subprocess/ctypes/pickle/multiprocessing）+ __import__/bare exec/eval/compile/__builtins__/os.popen/os.system；代码 ≤ 100KB、超时 180s；已安装 pip 包可直接 import；仅检测实际代码，注释/字符串字面量中的上述标识符不受影响
• Shell：默认 30s、最大 300s；灾难性操作硬拦（电源/磁盘格式化/rm -rf //LOLBins/PowerShell 隐藏执行等），sudo/reg 等常规运维命令属 DANGEROUS 级需用户确认；文件名/正文中的命令名子串不会被误拦
• 浏览器操作用 browser_action（22 个 action），禁止在脚本中 require puppeteer/playwright
• 桌面自动化用 computer_use（13 个 action：get_state/list_windows/get_clipboard/activate_window/set_clipboard/click/double_click/right_click/drag/type/press_key/hotkey/scroll），系统级桌面操作（浏览器外的任意桌面应用）；条件可用：需配置 vision 模型；坐标为虚拟桌面物理像素（get_state 返回 displays 元数据供换算）；输入/写入类 action 属 DANGEROUS 级需用户确认，感知类（get_state/list_windows/get_clipboard）免确认（例外：get_state 携带 windowTitle 时升 CAUTION 走一次确认）；type 仅 ASCII 文本，中文走 set_clipboard + hotkey ["Ctrl","V"]
• 常用工具：run_command（含 persistent 常驻终端模式）、read_terminal_output、read_file/write_file/edit_file/list_dir/file_info/search_files/file_ops/undo_file/redo_file（工作区检查点回滚/重做）、workspace_outline（项目大纲，需工作空间）、search_code（语义代码检索，需工作空间 + 代码索引就绪）、extract_document、web_search、plan/plan_file、recall_memory、query_knowledge_base/save_knowledge、read_image/capture_screen（需 vision 模型）、computer_use（需 vision 模型）、get_diagnostics（代码诊断，需代码项目）、resolve_path/open_target、ask_followup_question、wait（SAFE 级纯等待，上限 1 小时）、kill_process（含 action=list 列出进程）
• 超时差异：wait 3720s（等待上限 1 小时 + 120s 余量）、plan 660s、plan_file 360s、get_diagnostics 150s、search_files/browser_action/read_terminal_output/read_image/computer_use 120s、其他默认 180s

脚本生成规则：

1. 零依赖优先：Node.js 仅白名单内置模块；Python 优先标准库
2. 跨平台兼容：路径分隔符用 path.join() 或 path.sep，不硬编码 \\ 或 /
3. 浏览器路径动态检测：不硬编码浏览器路径，由系统自动检测
4. 错误兜底：所有脚本必须有 try-catch / try-except，失败时输出可读错误信息
5. 前置安装声明（仅 Python）：未安装的 pip 依赖必须在「前置准备」章节写明 pip install；Node.js 无此机制（require 第三方包一律被拒）
6. 脚本存放：辅助脚本放 Skill 目录下，kebab-case 命名
7. 路径 scope 意识：workspace 首选、sandbox 次选、blocked 禁止、outside 标记；脚本优先使用相对路径
8. 常驻进程：用 persistent: true 启动，read_terminal_output 读输出，kill_process 终止

安全分级与自动批准：工具分 SAFE（静默执行）/ CAUTION（需确认）/ DANGEROUS（必须确认）三级；路径越界自动升级（如 workspace 外写文件升为 DANGEROUS）；用户可对部分工具开启自动批准，确认策略可能随用户设置变化。生成的 Skill 不应假定工具一定会被确认拦截，也不应假定 CAUTION 工具一定静默执行。

3. SKILL.md 标准文档结构模板

所有新生成的 SKILL.md 必须包含：YAML Front Matter + 正文章节。

3.1 YAML Front Matter

yamlCopy code
---
name: <skill-name>          # kebab-case，与目录名一致
description: <一句话描述>    # 概括技能核心能力、输入输出、适用场景
triggerKeywords: [关键词1, 关键词2, ...]  # 3-8个触发词，中英文均可（可选）
version: 1.0.0              # 语义化版本号（可选）
---

字段规范：

• name：全小写 kebab-case，必须以小写字母开头，只含小写字母、数字、短横线，长度 ≤ 50 字符
• description：必须包含"做什么 + 怎么做 + 输出什么"三要素
• triggerKeywords：覆盖用户可能的表述方式，中英文混合；可选字段
• version：语义化版本号，建议初始 1.0.0；可选字段

字段必填性：name 和 description 必填；triggerKeywords 和 version 可选。

防误导：frontmatter 仅支持上述 4 个字段，不要添加 category/categories/tags/permissions 等额外字段（分类归属由用户在应用 UI 中管理，与 SKILL.md 无关）。

自举一致性约束：name 字段必须与 Skill 目录名完全一致，否则系统加载时会报错。

3.2 正文标准章节

markdownCopy code
# <Skill 名称>

## 1. 技能概述
- 技能名称、技能描述、角色定位、适用场景

## 2. 前置准备 / 环境要求
- 依赖工具版本、环境变量、前置安装步骤（如有）
- MCP 服务器配置声明（如依赖 MCP 工具）

## 3. 输入规范
- 用户需提供什么输入（文件路径、参数、选项等）
- 输入格式示例

## 4. 执行工作流
- Step 1 -> Step 2 -> Step 3 -> ...（每步明确做什么、用什么工具、产出什么）
- 工作流必须形成闭环，无悬空节点

## 5. 输出规范
- 产出物格式（Markdown / JSON / PNG / 文件等）
- 存储路径规则
- 自动打开 / 自动通知等后续动作

## 6. 脚本与工具约束
- 列出本 Skill 用到的所有脚本和命令
- 标注每个脚本的能力边界合规性

## 7. 异常处理
- 核心失败场景的兜底策略
- 用户引导（缺少输入时如何提示）

## 8. 质量校验（可选）
- 自检清单，确保执行结果达标

## 9. 报告存储与自动打开（如适用）
- 路径规则、命名规则、自动打开目录

3.3 章节裁剪规则

4. Skill 创建标准化工作流

当用户提出创建技能的需求时，Agent 必须按以下 6 步闭环执行：

Step 1：需求分析与重名检测

目标：精确理解用户要做什么 Skill，并检测是否存在同名或雷同的已有 Skill。

执行要点：

1. 提取核心目标：这个 Skill 解决什么问题？
2. 识别输入输出：用户会提供什么？Skill 产出什么？
3. 确认能力边界：是否需要脚本？脚本是否在 UseIO 能力矩阵内？
4. 如有关键信息缺失（如输入格式不明确、输出目标未指定），使用 ask_followup_question 向用户确认
5. 重名检测（必须执行）：
   • 使用 list_dir 扫描应用 Skills 存储目录（位于应用数据根目录下的 skills/ 子目录）下所有子目录
   • 检查是否已存在与目标 name 同名的目录（内置 Skill 也安装在 skills/ 目录下，扫描天然覆盖）
   • 若存在同名目录，使用 read_file 读取其 SKILL.md 的 YAML front matter（前 10 行即可）
   • 对比已有 Skill 的 description 和 triggerKeywords 与用户当前需求，判断是否雷同
   • 判定雷同的标准（语义判断为主）：已有 Skill 与目标解决同类问题、面向同类输入输出、或 description 表述的核心能力一致，即视为雷同；仅名称碰巧相同但功能完全不同的不算雷同
   • 若判定为雷同，使用 ask_followup_question 向用户提示：
     • 展示已有 Skill 的 name、description、triggerKeywords
     • 询问用户是「复用已有 Skill（在其基础上迭代升级）」还是「创建新 Skill（使用不同名称）」
   • 若用户选择创建新 Skill，要求用户提供一个新的不重名的 name
   • 若用户选择复用，进入已有 Skill 目录进行版本迭代（递增 version），不创建新目录

路径获取说明：Skills 存储目录为应用数据根目录下的 skills/ 子目录，不随用户当前工作空间变化，按以下顺序定位：① 调用 resolve_path('~/.useio/skills') 探测（支持 ~ 展开）→ 存在即为数据根目录；② 探测失败时（portable 版数据目录跟随 exe 位置，路径不固定），使用 ask_followup_question 请用户提供数据根目录，或引导用户在「技能管理」页面查看。注意：该目录在用户工作空间之外，对它的 write_file/file_ops 会触发 DANGEROUS 级用户确认，属预期行为。

产出：一份需求摘要（内含目标、输入、输出、是否需要脚本）+ 重名检测结论（无冲突 / 已复用 / 已使用新名称）

Step 2：结构设计

目标：套用标准模板，规划章节。

执行要点：

1. 根据 3.3 章节裁剪规则，确定必选和可选章节
2. 规划工作流步骤数量和每步职责
3. 确定文件存储路径和命名规则（如适用）
4. 列出需要的辅助脚本清单（如适用）

产出：章节大纲 + 工作流步骤草案

Step 3：内容编写

目标：填充每个章节的具体内容。

执行要点：

1. 先写 YAML Front Matter（name / description / triggerKeywords / version）
2. 再写正文，从概述到工作流到异常处理
3. 工作流步骤必须具体到"用什么工具、做什么操作、产出什么结果"
4. 如有脚本，同步编写脚本代码：Node.js 确保零第三方依赖（仅白名单内置模块），Python 确保仅用标准库和已安装的 pip 包（未安装的依赖需声明前置步骤）
5. 脚本必须跨平台兼容、有错误兜底
6. 篇幅控制：正文控制在 20000 字符内，超长内容（完整示例、详细参考表、模板全文）拆分到 docs/ 子文件，正文中注明"用 read_skill_file 按需读取"

产出：完整的 SKILL.md 草稿 + 辅助脚本文件（如有）

Step 4：脚本约束检查

目标：确保所有脚本和命令在 UseIO 能力边界内。

执行要点：

1. Node.js：逐行检查 require() 是否只用了 16 个白名单模块，禁止 child_process/net/dgram/cluster
2. Python：检查 import 是否命中禁止模块（subprocess, ctypes, pickle, multiprocessing），检查 __import__（任何引用均拦截）及 bare 调用形式的 exec/eval/compile（属性方法调用如 re.compile 不受影响），检查 __builtins__/os.popen/os.system 等危险模式
3. Shell：检查命令是否命中硬拦清单（电源/磁盘格式化、rm -rf /、系统关键目录递归删除、LOLBins、远程执行、PowerShell 隐藏执行等）；sudo/systemctl/reg 等常规运维命令不硬拦但属 DANGEROUS 级需用户确认；注意正文/文件名中的命令名子串不会被误拦，无需为规避检测改写命令
4. computer_use：检查引用的 action 是否在 13 个枚举内；确认已在前置准备章节声明 vision 模型配置要求（未配置时 computer_use 不在工具列表，需提供降级方案）；输入/写入类 action（click/type/hotkey/activate_window/set_clipboard 等）需提示用户会弹出 DANGEROUS 级确认
5. 检查路径是否跨平台兼容，是否使用相对路径
6. 检查是否有 try-catch / try-except 错误兜底
7. 如有 Python 第三方依赖（且未安装），确认已在前置准备章节声明 pip install 安装步骤
8. 如有常驻进程需求，确认已使用 persistent: true，并通过 read_terminal_output 读取输出、用 kill_process 终止
9. 如依赖 MCP 工具，确认已在前置准备章节声明 MCP 服务器配置要求，并包含降级逻辑

产出：合规确认（或修复后的脚本）

Step 5：质量校验

目标：运行质量校验清单，确保文档达标。

执行要点：

1. 使用 read_skill_file 读取本技能的 docs/quality-checklist.md 获取完整校验清单（26 项，分 Front Matter / 正文 / 脚本 / 格式四类）
2. 逐项对照校验，不合格项立即修复
3. 全部通过后方可进入交付

产出：校验通过的最终文档

Step 6：交付

目标：输出最终文件并告知用户。

执行要点：

1. 将 SKILL.md 写入应用数据根目录下的 skills/<skill-name>/SKILL.md（路径定位方式见 Step 1 的「路径获取说明」：resolve_path('~/.useio/skills') 探测，portable 版询问用户；该路径在工作空间外，写入会触发 DANGEROUS 级用户确认，属预期行为）
2. 将辅助脚本写入 skills/<skill-name>/ 或其 scripts/ 子目录
3. 禁止覆盖：写入前再次确认目标目录不存在（Step 1 已检测，此处为二次保险）。若目录已存在且用户未选择复用，在目录名后追加 -v2、-v3 等后缀
4. 向用户展示技能概要（名称、触发词、工作流步骤数、核心能力）
5. 提供使用示例（如何触发、预期输出）

产出：已写入的文件路径 + 使用说明

5. 文件存储与目录规范

5.1 存储根目录

所有 Skill 必须存储在 应用数据根目录下的 skills/ 子目录中：

Copy code
<应用数据根目录>/skills/

该路径不随用户当前工作空间变化。安装版默认 ~/.useio，portable 版跟随 exe 所在目录。通过 resolve_path('~/.useio/skills') 探测定位，探测失败时询问用户（详见第 4 章 Step 1）。该目录在用户工作空间之外，写入操作会触发 DANGEROUS 级用户确认。

5.2 目录结构

Copy code
<应用数据根目录>/skills/
├── <skill-name>/
│   ├── SKILL.md              # 主文档（必须）
│   ├── docs/                 # 扩展参考文档（可选，超长内容拆分于此）
│   ├── scripts/              # 辅助脚本（可选）
│   │   ├── helper.js
│   │   └── utils.py
│   ├── assets/               # 静态资源（可选）
│   │   ├── template.md
│   │   └── config.json
│   └── README.md             # 补充说明（可选）

5.3 命名规则

5.4 重名检测与冲突处理

创建新 Skill 前，必须执行以下检测流程：

1. 扫描已有 Skill：使用 list_dir 扫描应用数据根目录下 skills/ 子目录的所有子目录
2. 同名检测：检查是否已存在与目标 name 同名的目录
3. 雷同检测：若存在同名目录，读取其 SKILL.md 的 front matter，对比 description 和 triggerKeywords：
   • 雷同判定（语义判断为主）：解决同类问题、面向同类输入输出、或 description 核心能力一致
   • 非雷同：名称碰巧相同但功能完全不同
4. 内置技能同名禁令：禁止使用与内置技能相同的 name（如 skill-generator、browser-automation、knowledge-extractor；内置技能集合随应用版本迭代变化，以 Step 1 list_dir 扫描到的实际安装结果为准）。内置技能在应用每次启动时会自动重装到用户 skills 目录并覆盖同名内容，与内置技能同名的用户 Skill 会在下次启动时被内置版本覆盖丢失，无法恢复
5. 冲突处理：
   • 若同名且雷同：使用 ask_followup_question 提示用户，提供选项：
     • 「在已有 Skill 基础上迭代升级（递增 version，不创建新目录）」
     • 「创建为新 Skill（使用不同的 name，新目录）」
   • 若同名但不雷同：直接在目标 name 后追加领域后缀（如 -v2、-alt）避免冲突
   • 若无同名：正常创建
6. 禁止覆盖铁律：任何情况下都不得覆盖已有 Skill 目录中的文件。若目录已存在且用户未明确选择复用，必须使用新目录名

5.5 存储规则

1. 每个 Skill 必须拥有独立的子目录，禁止多个 Skill 共用一个目录
2. SKILL.md 是唯一入口文件，文件名固定不可变
3. 辅助脚本和资源文件存放在同目录或子目录下
4. 禁止将 Skill 文件散落在项目根目录或工作空间临时目录
5. 如 Skill 有版本迭代，在 YAML front matter 中递增 version，不创建历史副本
6. 创建前必须执行重名检测（5.4），确保不覆盖已有 Skill

6. 异常处理

7. 强制规则

1. 能力边界不可逾越：生成的所有脚本和命令必须在能力矩阵之内；Node.js 仅用 16 个白名单模块（代码 ≤ 50KB、内存 ≤ 256MB、超时 180s，零第三方依赖），Python 采用多层安全检测（禁止模块/内置函数/危险模式三类拦截，详见运行环境文档，代码 ≤ 100KB、超时 180s，已安装 pip 包可直接 import），Shell 命令不得命中硬拦清单（默认 30s、最大 300s；sudo/reg 等常规运维命令不硬拦但属 DANGEROUS 级需用户确认）。
2. 零依赖优先：Node.js 仅用白名单内置模块（require 第三方包会被直接拒绝，必须零依赖）；Python 优先使用标准库并避开禁止项，已安装的 pip 第三方库可直接 import，未安装的需声明前置安装步骤。
3. 自举合规：本元技能自身也必须符合其所定义的全部标准（YAML front matter 完整、章节齐全、工作流闭环）。
4. 质量校验必过：交付前必须逐项通过质量校验清单（docs/quality-checklist.md，26 项），不合格项必须修复。
5. 目录规范必守：所有 Skill 文件必须存放在应用数据根目录下的 skills/<skill-name>/ 目录下，SKILL.md 为唯一入口；不得硬编码绝对路径，数据根目录按 Step 1 的探测流程定位。
6. 工作流必闭环：工作流的每个步骤必须有明确的输入和产出，最后一个步骤必须是交付/输出。
7. 禁止编造能力：不得在生成的 Skill 中引用 UseIO 不具备的工具或能力。
8. 重名检测必做：创建新 Skill 前必须扫描应用数据根目录下的 skills/ 目录，检测同名和雷同 Skill（语义判断，见 5.4），雷同时必须提示用户；禁止使用与内置技能相同的 name（内置技能集合以应用当前实际安装为准，重启后同名用户 Skill 会被内置版本覆盖）。
9. 禁止覆盖：任何情况下不得覆盖已有 Skill 目录中的文件，冲突时使用新目录名或迭代 version。
10. MCP 依赖必声明：若 Skill 依赖 MCP 工具，必须在前置准备章节声明 MCP 服务器配置要求，并包含工具不可用时的降级逻辑。
11. 篇幅必控：生成的 SKILL.md 正文必须控制在 20000 字符内（超长会被截断），超长内容（完整示例、参考表、模板）拆分到 docs/ 子文件并在正文注明按需读取路径。

8. 扩展参考文档（按需用 read_skill_file 读取）

以下参考文档不随 SKILL.md 正文自动加载，需要时用 read_skill_file 工具读取（先 load_skill 本技能）：

Skill 加载机制说明：description 是系统判断是否加载该 Skill 的主要依据，必须简明准确；triggerKeywords 覆盖用户可能的表述方式。SKILL.md 正文超过 20000 字符会被截断，超长内容（完整示例、参考表、模板全文）拆分到 docs/ 子文件，正文中注明"用 read_skill_file 按需读取"（单次读取上限 64000 字符）。用户 Skill 与内置 Skill 目录结构一致，均位于应用数据根目录下的 skills/ 子目录。