/scheduler-skill-creator

name: scheduler-skill-creator
description: |
  建立並排程定時觸發的 skill。**所有新增定時／週期任務、提醒、排程通知的請求必須走此 skill**，禁止直接呼叫 schedules(mode=write)（那是 skill 已存在時的時間綁定工具，不該作為新建排程的入口）。

  必定觸發的訊息特徵（任一即活化）：
  - 相對延遲：「X 分鐘後」「X 小時後」「稍後」「待會」「等一下」
  - 明確時間：「X 點」「下午 X 點」「明天 X 點」「後天」「YYYY-MM-DD HH:MM」
  - 週期性：「每 X 分鐘」「每小時」「每天」「每週」「每月」「定時」「固定」
  - 提醒 / 通知意圖：「提醒我」「通知我」「告訴我」+ 時間描述

  範例觸發訊息：「5 分鐘後提醒我喝水」「每天早上 9 點抓 HN 頭條」「明天下午 3 點開會」「每 5 分鐘查台積電股價」。

  **不觸發**（即使訊息含「觸發」「排程」字眼也不 activate）：
  - 訊息含 `[執行已存在 scheduler skill:` 標記 → 為 `/sched-<name>` 手動 trigger，當前 agent 直接執行 body
  - 訊息為一份完整的 SKILL.md body（`# Title` + `## 任務` + `## 輸出格式` 結構），無建立／排程動詞 → 為 skill execution，非 creation
  - 訊息僅含「執行 skill X」「跑 X」「run skill X」無時間 token → 為 execution

  流程：解析訊息抽出「要做什麼」「何時觸發」→ 缺項用 ask_user 補問 → 生成 skill 檔案至 ~/.config/agenvoy/skills/scheduler/<short>-<hash8>/SKILL.md（無 scheduler- 前綴，hash 用於避免命名衝突）→ 呼叫 schedules(mode=write) 綁定時間 → 回報。

> **本 Skill 為 Agenvoy 內部最佳化版本**，依 Agenvoy 的執行環境撰寫（`run_command` 的 CWD、`~/.config/agenvoy/skills/.system/` 安裝位置、`edit_skill`／`schedules`／`find_edit_tool` 等工具、subagent 與排程的觸發路徑），**不保證適配其他 AI harness**。

Scheduler Skill 建立器

目的

scheduler 採 skill-based 觸發：到時間時，daemon 讀 `scheduler/<short>/SKILL.md` body 並起 in-process subagent 跑（always-allow）。本 skill 的職責 = 「從使用者意圖建出 skill 並綁定時間」，完整跑完 6 步即完成排程。

**重要：scheduler 用 skill 與一般 skill 隔離**

| 比較 | 一般 skill | scheduler 用 skill | |---|---|---| | 路徑 | `~/.config/agenvoy/skills/<name>/SKILL.md` | `~/.config/agenvoy/skills/scheduler/<short>-<hash8>/SKILL.md` | | frontmatter `name` | `<name>` | `<short>-<hash8>` (**無前綴**) | | 一般 `/<name>` 補全 | 出現 | **不出現**（scanner 不掃 scheduler/） | | 呼叫方式 | `/<name>` 觸發 | `schedules(mode=write, target=task, skill_name=<short>-<hash8>)` / `schedules(mode=write, target=cron, skill_name=<short>-<hash8>)` |

成功標準

• 生成檔案: `~/.config/agenvoy/skills/scheduler/<short>-<hash8>/SKILL.md`，frontmatter `name: <short>-<hash8>`（無前綴）
• skill body 描述任務行為、引用具體 tool
• 呼叫 `schedules(mode=write, target=task, time, skill_name=<short>-<hash8>)` 或 `schedules(mode=write, target=cron, time, skill_name=<short>-<hash8>)` 綁定時間成功
• 回報生成位置、full name（含 hash）、排程類型（one-shot／recurring）、下次觸發時間

步驟

0. 時間檢查門檻（**強制首動作**）

在呼叫**任何其他 tool**（特別是 `run_command` 跑 init script）**之前**，先檢查使用者訊息**是否含明確時間 token**。時間 token 定義：

| 類別 | Token 範例 | |---|---| | 相對延遲 | `N 分鐘後`／`N 小時後`／`N 秒後`／`待會`／`稍後`／`等一下` | | 絕對時鐘 | `X 點`／`HH:MM`／`下午 X 點`／`晚上 X 點` | | 絕對日期 | `今天`／`明天`／`後天`／`YYYY-MM-DD` | | 週期 | `每 N 分`／`每小時`／`每天`／`每週`／`每月`／`定時`／`固定` |

**判定流程**（兩個 yes／no 各自獨立檢查；缺項一律走 `ask_user` **tool call**）：

1. **任務 token 存在？**（訊息含可執行動作描述）

• 否 → 呼叫 `ask_user` tool：`{"questions":[{"question":"要做什麼？例：抓 HN 頭條 / 提醒我喝水"}]}`

2. **時間 token 存在？**（上表任一）

• 否 → 呼叫 `ask_user` tool：`{"questions":[{"question":"什麼時候執行？例：5 分鐘後 / 每 5 分鐘 / 明天 9 點"}]}`

兩項都缺時，同一個 `ask_user` 的 `questions` 帶兩題送出。收到回傳的 `answers` 後，把答案併入原訊息重跑步驟 0；兩者都齊才進步驟 1。

**問題一律用 `ask_user` tool call 送出**：`ask_user` 走 `pending.Ask` 阻塞等待 reply，harness 開 popup／prompt 收答案，agent 收到結構化 `answers` 後接著執行。TUI／CLI／Web／Telegram／Discord 都支援；只有 chat completions 端點沒有這個通道。

**需要補問的例子**：

| 訊息 | 為何要 ask_user | |---|---| | 「說我很棒」「提醒我」「叫我喝水」 | 任務有，時間**無** | | 「等等」「之後」「找時間」 | 模糊詞不算明確 token | | 「下班後」「有空時」 | 無可正規化為 cron／datetime 的時間值 |

時間以使用者說的為準：沒說就用 `ask_user` 問，不用預設值（`+10m`、`09:00`）或推測補齊。

1. 解析需求

步驟 0 通過後（任務與時間都齊全），抽兩元素：

• **任務**：要做什麼（行為描述）
• **時間**：何時觸發

範例解析：

| 訊息 | 任務 | 時間 | |---|---|---| | 每 5 分鐘提醒我台積電最新股價 | 查台積電股價並提醒 | 每 5 分鐘（recurring） | | 明天早上 9 點提醒我開會 | 開會提醒 | 明天 09:00（one-shot） | | 5 分鐘後叫我喝水 | 喝水提醒 | +5m（one-shot） | | 每天抓 HN 頭條給我 | 抓 HN 頭條摘要 | 每天（recurring，**步驟 0 已要求補問時段**） |

缺項一律以 `ask_user` **tool call** 補齊；`questions` 是 array，當下所有缺項寫成多題一起送。

2. 時間正規化 + 選 tool

| 使用者說 | 工具 | `time` 參數 | |---|---|---| | `X 分鐘後` | `schedules(mode=write, target=task)` | `+Xm` | | `X 小時後` | `schedules(mode=write, target=task)` | `+Xh` | | `今天 X 點`（24h） | `schedules(mode=write, target=task)` | `HH:MM` | | `明天 / 特定日期 X 點` | `schedules(mode=write, target=task)` | `YYYY-MM-DD HH:MM` | | `每 X 分鐘` | `schedules(mode=write, target=cron)` | `*/X * * * *` | | `每小時` | `schedules(mode=write, target=cron)` | `0 * * * *` | | `每天 X 點` | `schedules(mode=write, target=cron)` | `MM HH * * *` | | `每週 N`（0=Sun, 1=Mon, ..., 6=Sat） | `schedules(mode=write, target=cron)` | `MM HH * * N` | | `每月 D 日 X 點` | `schedules(mode=write, target=cron)` | `MM HH D * *` |

決定走 `schedules(mode=write)` target=task（一次性）或 target=cron（週期）。

3. 初始化 skill 目錄（**強制走 init 腳本**）

> **腳本路徑**：`run_command` 的 CWD 是使用者的工作目錄，**不是本 skill 目錄**，相對路徑 `scripts/...` 必定找不到（實測會讓 agent 反覆 glob 找檔案，白燒數輪）。本 skill 只服務 Agenvoy、安裝位置固定，一律用絕對路徑 `~/.config/agenvoy/skills/.system/scheduler-skill-creator/scripts/`。

> **禁止直接用 `write_file` 建立 SKILL.md** —— LLM 容易寫成 `<short>.md` 而非 `<short>/SKILL.md`，或誤加 `scheduler-` 前綴；也無法自行產生 hash suffix。必須先跑 init 腳本。

用 `run_command` 執行：

python3 ~/.config/agenvoy/skills/.system/scheduler-skill-creator/scripts/init_scheduler_skill.py <short-name>

`<short-name>` 由步驟 1 的任務描述推導（kebab-case、**不含 `scheduler-` 前綴**、**不含 hash**）。腳本會：

• 正規化 short name（lowercase、hyphen-case）
• 產生 8-char hex random suffix（`secrets.token_hex(4)`），組成 full name `<short>-<hash8>`
• 建立 `~/.config/agenvoy/skills/scheduler/<short>-<hash8>/SKILL.md`，寫入含 frontmatter `name: <short>-<hash8>` 的 TODO 模板

**捕捉 full name**：stdout 會印一行 `[OK] skill name: <short>-<hash8>`，**完整字串**（含 hash）是後續步驟 4／5 要用的 `skill_name`。極罕見 hash 碰撞時印 `[ERROR] collision` exit 1，重跑一次即可。

**重綁定既有 skill 的時間**（user 說「把那個 X 改成 Y」）：不再跑 init 腳本，直接用既存 full name 進步驟 5；既存 full name 可從先前回報訊息找，或 `find_files(mode=list)` 列出 `~/.config/agenvoy/skills/scheduler/` 選擇。

4. 建構 skill 內容（**委派 `/skill-creator`**）

目錄與名稱在步驟 3 已經定案，這一步只做內容。**呼叫 `/skill-creator`**，用它的「編輯現有 Skill」路徑填內容，不要在這裡自己重寫一套設計流程。

/skill-creator 編輯現有 skill：~/.config/agenvoy/skills/scheduler/<short>-<hash8>/
任務：<步驟 1 收集到的行為細節>

**交給 `/skill-creator` 的部分**（照它的步驟走）：

| 它的步驟 | 在這裡的作用 | |---|---| | 一：透過具體範例理解 | 已由步驟 1 完成，把結果直接給它，**不要再問一次** | | 二：規劃可重用內容 | 決定要不要 `scripts/` | |