scheduler-skill-creator

Scheduler Skill 建立器

目的

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

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

成功標準

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

步驟

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

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

判定流程（兩個 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 回傳的 answers 後，把答案併入原訊息重跑步驟 0；兩者都齊才進步驟 1。

強制使用 tool call、禁止用純文字輸出問題：

• ❌ 輸出 什麼時候執行？例：5 分鐘後 / ... 作為 assistant 文字回應 → 流程中斷（TUI／CLI 不會把使用者下一句話視為這題的回答）
• ✅ 呼叫 ask_user tool 帶 questions → harness 開 popup／prompt 收答案，回到 agent 主迴圈繼續

為何：ask_user tool 走 pending.Ask 阻塞等待 reply，agent 自動收到結構化 answers 後續執行；純文字輸出則 turn 結束、context 不接續，使用者下次輸入會被視為新任務而非答案。

反例（這些必須先 ask_user tool call 補時間，禁止直接進 init）：

禁止行為（違反視為流程失敗）：

• ❌ 訊息無時間 token 仍跑 run_command python3 .../init_scheduler_skill.py
• ❌ 用「+10m」「+5m」「+1h」當預設值補齊未指定的時間
• ❌ 推論「使用者大概是想要 N 分鐘後」之類腦補
• ❌ 缺時段（如「每天」沒說幾點）時自動填「09:00」
• ❌ 以純文字輸出問題替代 ask_user tool call（mini model 易犯，違反「ambiguity 用 tool 而非 text」）

1. 解析需求

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

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

範例解析：

一次 ask_user 一題，依需要追問。禁止假設。

2. 時間正規化 + 選 tool

決定走 add_schedule target=task（一次性）或 target=cron（週期）。

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

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

用 run_command 執行：

python3 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 可從先前回報訊息找，或 list_files ~/.config/agenvoy/skills/scheduler/ 列出選擇。

3.5 工具／skill 搭配探索（步驟 4 前置）

填 skill body 之前必須確認會用到的 skill／tool 真實存在，否則觸發時 subagent 找不到 → 直接 abort、使用者拿不到結果。

Skill 優先於 tool：skill 是預先封裝好的高階流程（含 prompt 規則／步驟／格式），tool 是低階呼叫；同樣的任務若有對應 skill，body 寫 /<skill-name> 比直接組 tool call 更穩定且符合既有設計。

強制探索順序（禁止跳順序、禁止只跑其中一步）：

1. 讀 system prompt 的 ## Skills 區段（你的 context 內已有）：把使用者意圖（步驟 1 的「任務」）對照所有 skill 的 description，列出任何描述提及相關主題的候選。例：

   • 「分析比特幣」「BTC 價格」→ bitcoin-lookup（描述含「BTC／Bitcoin／比特幣價格／行情／分析」）
   • 「彙整 commit 訊息」→ commit-generate
   • 「跑程式碼 review」→ code-reviewer

2. 逐個 run_skill 驗證候選：activate 成功代表存在，body 改寫成 任務：呼叫 /<skill-name> 觸發本任務。失敗（skill 不存在）才往下一步。

3. 無匹配 skill 時，search_tools 找 raw tool：抽出步驟 1 任務的動詞，對每個動詞呼一次 search_tools。回傳的 tool name 才能寫進 body：

   search_tools({"query": "fetch stock price", "max_results": 5})
   search_tools({"query": "yahoo finance", "max_results": 5})
   

4. search_tools 也找不到（例：使用者要求「打卡」但無此 tool 也無對應 skill）→ 回 ask_user：「目前環境沒有可完成 X 的 skill／tool，可以改成 Y 嗎？」。禁止寫不存在的 skill／tool name 進 body。

判定原則：

常用 skill／tool 速查（先想想再去 activate／search）：

scheduler-skill-creator 與 scheduler/ 下任何 skill 不算候選 —— 前者是本流程自己、不能遞迴；後者是 scheduler 用內部 skill（透過 add_schedule 綁定觸發、不能用 /<name> 從 body 呼叫）。

4. 填充 skill body

用 patch_skill 取代模板中的 [TODO: ...] 段：

• description: ← 步驟 1 收集到的「一句話描述」
• ## 任務 ← 步驟 1 收集到的「行為細節」，引用步驟 3.5 已確認存在的 tool 名稱與參數
• ## 輸出格式 ← 期望輸出形式

禁止在 skill body 內加任何「推送到 channel」「呼叫 send_http_request 給 Discord」「呼叫 MCP discord tool」之類的 notify 指令 —— scheduler 觸發後 runtime 自動把輸出送回原 caller channel（Discord 來源送回原頻道、CLI／HTTP 來源送回 action.log）。Skill body 只需專注產出任務結果文字。

5. 綁定時間

依步驟 2 結果呼叫，skill_name 用步驟 3 stdout 印出的完整 <short>-<hash8>：

add_schedule(target="task", time="<time_value>", skill_name="<short>-<hash8>")
# 或
add_schedule(target="cron", time="<cron_expression>", skill_name="<short>-<hash8>")

skill_name 不加 scheduler- 前綴（內部會直查 ~/.config/agenvoy/skills/scheduler/<short>-<hash8>/SKILL.md 確認存在）。session_id 內部自動取 caller e.SessionID，不必傳。

成功會回 ID: <hash> 等資訊。失敗（skill 不存在、cron 表達式錯誤、time 已過）就 abort 本流程，向使用者回報原因。

6. 回報

簡短告知：

• skill 已建立: ~/.config/agenvoy/skills/scheduler/<short>-<hash8>/SKILL.md
• skill name: <short>-<hash8>（無前綴，hash 自動產生避免命名衝突）
• 排程: add_schedule 的回應內容（含下次觸發時間、ID）

命名規則

禁止在任何環節加 scheduler- 前綴。scheduler 已表達於目錄路徑，加前綴只會造成 scheduler/scheduler-foo-<hash>/ 之類的重複命名。

禁止自行產生／猜測 hash suffix。Hash 必須由 init script 用 secrets.token_hex(4) 隨機生成，LLM 從 stdout 抓 [OK] skill name: 那行的值即可。

輸出路由（runtime 自動處理）

scheduler 觸發後，runtime 會把 subagent 產出的最終文字自動送回 caller 端：

所以 skill body 不需要、也禁止寫「推送到 channel」「呼叫 send_http_request 發 Discord webhook」「呼叫 MCP discord tool」之類的 notify 指令。寫了會在觸發時造成多餘的 token 與認證錯誤（subagent 沒 DISCORD_BOT_TOKEN 互動環境）。

Secret／API Key（skill body 引用 token 時必看）

被觸發的 scheduler skill 跑在獨立 subagent，不持有任何明文 secret。若 body 內呼叫的 tool（如 send_http_request、自製 api_tool、script_tool）需要 API token：

• 命名格式：{品牌}_API_KEY（SCREAMING_SNAKE_CASE），例 OPENAI_API_KEY、CODEX_API_KEY、POLYGON_API_KEY、STAGING_API_KEY
• 儲存位置：macOS keychain 中 service = agenvoy、account = key 名，組合識別 agenvoy.{key}（例 agenvoy.OPENAI_API_KEY）
• 取值方式：
  • api_tool：auth.env: "<KEY_NAME>"（schema 只記 key 名，無 agenvoy. 前綴）
  • script_tool：GET http://localhost:17989/v1/key?key=<KEY_NAME>（同樣不帶前綴）
  • skill body 純文字：直接引用 tool，不在 SKILL.md 寫明文 token、不寫 export ENV=value 之類指令
• 缺 key 處置：若觸發時 keychain 無對應 key，subagent 會在 tool 端拿到 401／空值錯誤；skill body 不負責「補登」，請使用者預先用 store_secret 落地

禁止在 scheduler skill 的 SKILL.md frontmatter／body 任何位置寫死 token 值或要求使用者在 cron 觸發時互動輸入 — subagent 無對話環境，不可能收 plaintext。

時間敏感性提醒（寫入 skill body 時注意）

被觸發的 skill 跑在獨立 subagent session，沒有當下對話上下文。skill body 必須：

• 不依賴「使用者剛才說了什麼」
• 不假設特定變數已被定義
• 引用具體 tool 名稱與參數（自包含可重現）
• cron 觸發時反覆執行，邏輯應 idempotent 或自帶 dedup

完整範例

使用者：「每 5 分鐘提醒我台積電最新股價」

步驟 1 解析：任務 = 查 2330.TW 股價；時間 = 每 5 分鐘 → recurring。兩者皆有，不問。

步驟 2 正規化：add_schedule(target="cron", time="*/5 * * * *", ...)

步驟 3 run_command python3 scripts/init_scheduler_skill.py tsmc-stock-watch

stdout：

[OK] created   : /Users/.../skills/scheduler/tsmc-stock-watch-a3f9b2c1/SKILL.md
[OK] skill name: tsmc-stock-watch-a3f9b2c1
...

抓出 full name tsmc-stock-watch-a3f9b2c1。

步驟 4 patch_skill 填入（frontmatter name 用 full name）：

---
name: tsmc-stock-watch-a3f9b2c1
description: 每 5 分鐘抓取台積電 2330.TW 即時股價並提醒。
---

# Tsmc Stock Watch

## 任務

透過 `search_web` / `search_google_news` 找到 `2330.TW` 最新報價來源，再用 `fetch_page` 讀取結果。

## 輸出格式

`台積電 2330.TW: NT
lt;price> (<change>% 從昨收)` 一行。

步驟 5 add_schedule(target="cron", time="*/5 * * * *", skill_name="tsmc-stock-watch-a3f9b2c1")

步驟 6 回報：「已排程每 5 分鐘觸發 tsmc-stock-watch-a3f9b2c1。下次觸發 HH:MM。」

不做的事

• 不用 write_file 直接建立 SKILL.md —— 必須走 init_scheduler_skill.py，避免結構錯誤（<name>.md vs <name>/SKILL.md）
• 不在 short name、frontmatter、skill_name 任何位置加 scheduler- 前綴
• 不留 [TODO: ...] 佔位符在最終 skill —— 步驟 4 須把所有 TODO 替換為具體內容
• 不用任意預設值補齊時間 —— 缺時間就 ask_user 問清楚，不要「應該是 9 點」之類腦補
• 不跳過步驟 5 的 add_schedule —— skill 建立但沒綁時間 = 排程不會觸發
• 不在 body 引用未經 search_tools 確認存在的 tool name —— 觸發時 subagent 找不到 tool 會直接 abort，使用者拿不到結果也看不到錯誤原因