make-skill

<!--
  参考 Anthropic 的 `skill-creator` skill（尤其 "creating a skill" 部分），
  为 QwenPaw 改写。
  Credit: https://github.com/anthropics/skills/blob/main/skill-creator/SKILL.md
-->

# Make Skill

把当前会话沉淀为可复用的 workspace skill。

你自己编排两阶段流程：

* **Phase A.** 提出一份精简的计划，让出 turn 等用户 approve。
* **Phase B.** 用户 approve 后，基于 THIS 会话撰写完整 SKILL.md 正文，
  通过 `materialize_skill` 持久化。

**不要**用 `write_file` 直接创建 SKILL.md 或其附属文件（脚本、JSON
等）。所有文件的首次创建必须走 `materialize_skill`（通过 `body` 和
`extra_files` 参数），它会跑安全扫描并原子写入 manifest。创建成功后，
如需修改可以使用 `edit_file` 编辑已有文件。

## 步骤 0. 确定 focus、派生 skill 名

### 0a. 确定 focus

两种触发入口：

* `/make-skill <focus>`。focus 紧跟在命令后面。
* 自然语言（「把这个变成 skill」「保存这个工作流」「把刚才的 X 流程
  变成 skill」「make a skill from this」）。从用户想保存的对话主题里
  提炼一个简短 focus 短语。如果模糊，先问一句澄清。

### 0b. 派生 skill 名

按**这条规则**从 focus 派生 skill 名：

```
skill_name = "-".join(focus.split())
```

内部空白（空格、tab、全角空格、连续空格）折叠成单个 `-`。其他字符
原样保留。

例子：

* `cooking` → `cooking`
* `view image debug` → `view-image-debug`
* `烹饪 食谱` → `烹饪-食谱`
* `Stock Price` → `Stock-Price`（大小写保留）

这个 `skill_name` 在以下场合**保持一致使用**：步骤 1 的 `plan.name`、
步骤 3 的 `materialize_skill` 的 `name=` 参数。

## 步骤 1. 提出计划，让出 turn 等用户 approve

调用 `create_plan`，**四个必填参数**（`name`、`description`、
`expected_outcome`、`subtasks`）都要给：

* **`name`**：步骤 0 中标准化的 `skill_name`。
* **`description`**：精简 preview（这是用户审核的内容），两部分：
  * **Part 1：触发预览。** 2 到 4 句话，日常语言。必须覆盖三点：
    * **Goal.** 这个 skill 产生什么端到端结果。
    * **Trigger.** 哪些用户表达和场景应该触发它。稍微 push 一些
      同义词。
    * **I/O.** 期望什么输入，产出什么输出。
    这里不是 SKILL.md frontmatter 格式，frontmatter 后面再 distill。
  * **Part 2：步骤大纲与 batch 规划。** 两部分内容：
    * **步骤大纲。** 编号列表，每行一个简短动词短语。不写细节、不写
      参数、不写错误处理、不写 sub-bullet、不写 `##` 子标题。只给出
      形状，让用户能快速判断顺序和范围。步骤名要从 THIS 会话里实际
      发生的事情里提取。不要编造；会话里没依据的就省略。
      格式示例（**不要**抄这个内容）：
      ```
      1. <verb phrase, ~5-10 words>
      2. <verb phrase, ~5-10 words>
      3. <…>
      ```
    * **Batch 规划。** 简要说明如何将上述步骤组织成 `run_tool_batch`
      的 JSON 文件：
      * 哪些步骤可以串成一个 batch（或需要拆成多个 batch 文件）。
      * 哪些中间环节原本需要 agent 介入判断，但实际上可以通过编写
        脚本（正则匹配、关键词筛选、JSON 解析等）来替代，从而减少
        agent 交互次数，让更多步骤纳入自动化 batch。
      * 列出预计需要的文件清单，如：
        ```
        scripts/main.json      — 主 batch 流程
        scripts/parse.py       — 解析 snapshot 提取目标内容
        ```
      目标是尽可能用脚本替代 agent 的中间判断，让 skill 执行时只需
      一次 `run_tool_batch` 调用即可完成，避免 agent 与工具之间的
      多轮交互。这让用户在 approve 前就能看到 batch 的整体结构。
* **`expected_outcome`**（plan 顶层，**必填**，与 subtask 的
  `expected_outcome` 不是同一个）：一句具体描述整个 skill 创建的成功
  状态。直接用这个字面值（替换 `<skill_name>`）即可：
  `"A new workspace skill <skill_name> is created, enabled, and invocable via /<skill_name>."`
* **`subtasks`**：一个长度为 1 的列表，包含唯一一个 subtask：
  * `name`：`"Write and materialize skill"`
  * `description`：`"Write the SKILL.md body and call materialize_skill."`
  * `expected_outcome`：`"Skill created and visible via /skills."`

`plan.name` 和 `plan.description` 用**与用户最近消息相同的语言**。
`expected_outcome` 保留英文即可。

`create_plan` 返回后，**让出 turn**。用户会回复 approve、refine 或
cancel。`/plan` 模式的标准机制接管：

* Refine：调 `revise_current_plan`，把反馈合到 name、description、或步
  骤大纲里。
* Cancel：调 `finish_plan` with `state="abandoned"`。

向用户呈现计划时用标准 plan card 格式。**不要**在 chat 里另搞
`Subtask: …` / `Focus: …` 这种自定义字段，用标准化后的 `plan.name`，
不要用 raw focus。本步骤只负责提出计划并等待用户确认，**不要**在此步
调用 `materialize_skill`。

### 选择执行方式

用户 approve 后，询问执行方式（让出一轮 turn）：

> 计划已 approve。Phase B（撰写与持久化）要**在当前对话继续执行**，
> 还是**交给后台 subagent 执行**？
>
> - **当前对话**：在本轮对话中完成。适合需要反复 refine 的场景。
> - **后台**：交给 subagent 完成，不阻塞当前对话。subagent 继承本会话
>   完整上下文和已批准的计划。

**让出 turn**，等用户回复后再继续。如果用户没有明确选择，默认使用
当前对话模式。

* **当前对话**模式：按下方步骤 2–5 正常执行。
* **后台**模式：见下方「后台执行 Phase B」小节。

**如果你当前已经是 subagent**（由主 agent 通过 `spawn_subagent`
派生），跳过询问，直接执行步骤 2–4（主 agent 已完成 plan 收尾，
subagent 无需调用任何 plan 相关工具）。

### 后台执行 Phase B

Phase A（步骤 0–1）已在前台完成，用户已经 approve 了计划。现在将
Phase B 交给 subagent 执行。

这一步你自己**不需要**调用 `materialize_skill` 或执行任何 skill 创建
操作——只需组装 task 描述并提交给 subagent，由 subagent 完成全部后续
工作。

1. 将以下信息组装成 task 描述传给 subagent：
   - 已 approve 的 `plan.name`（`skill_name`）和计划内容
   - 明确指令：「基于当前会话上下文和已 approve 的计划，按 make-skill
     步骤 2–4 完整执行：撰写 SKILL.md 正文、调用 materialize_skill
     持久化、验证 batch 引用、试跑 batch。完成后报告结果。**无需调用
     任何 plan 相关工具（`create_plan`、`finish_subtask`、
     `finish_plan`），无需等待用户 approve，直接自行完成全部流程。**」
2. 调用：
   ```
   spawn_subagent(
       task="<上述 task 描述>。无需调用任何 plan 相关工具，直接完成全部流程。",
       fork=True,
       background=True,
   )
   ```
3. 立即对唯一的 subtask 调 `finish_subtask`，再调 `finish_plan` with
   `state="completed"` 收尾。不需要等 subagent 完成。
4. 告知用户已提交后台任务，可通过 `check_agent_task(task_id=...)` 查看
   进度。subagent 完成后会在 workspace 中创建 skill。

### Plan 工具不可用时的 fallback

如果 `create_plan` 不在你的 toolkit 里（workspace 未启用 plan mode），
退回到文本式计划：

1. 把同样的精简 preview（Part 1 触发预览 + Part 2 步骤大纲）作为普通
   聊天消息发给用户。
2. 消息末尾请用户回复 approve、refine 或 cancel。
3. **让出 turn。** approve → 用你提出的大纲跳到步骤 2 写正文；
   refine → 修文本计划再让出 turn；cancel → 停止。
4. 跳过步骤 5 的 `finish_subtask` / `finish_plan`，没 plan 就没这两个
   动作。

## 步骤 2. 用户 approve 后撰写 SKILL.md 正文

用户 approve 计划、唯一的 subtask 转为 in-progress 后，基于 THIS 会话
写完整的 SKILL.md 正文。**内容能撑得起就不嫌长。**

写作风格：

* 使用祈使句。
* 对**非显而易见**的指令简要解释 WHY（next agent 的 theory of mind）。
  避免硬邦邦的 `MUST`。
* 正文目标少于约 500 行。接近上限就拆 sub-section + 加清晰指针。

### 2a. 与已 approve 的步骤大纲 1-to-1 对齐

正文主章节与 `plan.description` Part 2 一一对应：同序、同范围。章节
标题用对应步骤的动词短语。如果用户在 approve 阶段对 Part 2 做了
refine，**按 refined 版本**写。

### 2b. 将完整流程整理为 batch JSON（首选执行方式）

**SKILL.md 正文的核心是一个 `run_tool_batch` 调用。** future agent 触发
skill 时应**直接调用 batch**，而不是逐步手动执行。分步说明只作为
batch 的补充参考（见 2c），不是主要执行指令。

回顾 THIS 会话中的工具调用序列，把 skill 的**完整端到端流程**整理成一
个 `run_tool_batch` JSON 文件。从流程起点到终点，所有**可以无条件串联
执行**的步骤都应纳入 batch。

#### 何时适用

* skill 的核心流程包含 **≥ 2 步的工具调用链**。
* 典型场景：批量文件操作、搜索后处理、多文件修改流水线、多步浏览器
  操作等。
* **大部分流程都可以通过脚本实现自动化。** 不要因为某个步骤「看起来
  需要判断」就放弃把它纳入 batch。绝大多数中间处理——提取内容、筛选
  结果、格式转换、条件判断、数据清洗——都能通过在 batch 中插入
  `execute_shell_command` 调用脚本来程序化。两种方式：
  * **内联短脚本**：直接在 `command` 中写
    `python3 -c "..."` 单行处理。
  * **独立脚本文件**：将复杂逻辑写成 `.py` 或 `.sh` 等文件放在
    `scripts/` 目录