long-task-coordinator

long-task-coordinator skill 概覽

long-task-coordinator 的作用

long-task-coordinator 是一個用來協調長週期工作的 skill，特別適合那些必須撐過中斷、交接，以及多輪對話之間長時間空檔的任務。它的核心工作其實很單純：把長時間進行中的工作，從脆弱的聊天記憶中移出，改放進可持久保存的狀態檔，並以明確的狀態轉換、恢復檢查與下一步追蹤來管理。

什麼人適合安裝

如果你常做 agent orchestration、委派研究、系統遷移、批次作業，或任何可能需要先暫停、之後再接手、甚至等待其他 worker 回傳結果的任務，這個 skill 很適合你。只要你的工作流程裡常出現「這個明天再接著做」或「先派出去，晚點回來檢查」這種情境，long-task-coordinator 通常都很對路。

使用者真正要解決的問題

使用者安裝 long-task-coordinator，不是單純為了「把計畫寫得更好」。真正的目的，是讓長時間工作變得可恢復、而且狀態描述不自欺欺人：

• 在 context 遺失後仍能恢復狀態
• 清楚追蹤 coordinator 與 workers 之間的責任歸屬
• 明確表示「正在等待」這類狀態
• 避免錯誤宣稱任務已完成
• 從已保存的真實狀態恢復，而不是靠猜前面聊天內容

它和一般 planning prompt 有什麼不同

long-task-coordinator 的差異不在於懂不懂某個領域，而在於工作流程紀律：

• 單一且可持久保存的狀態檔
• 固定迴圈：READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END
• 使用明確狀態，例如 running、awaiting-result、paused、blocked、complete
• 優先先寫入狀態再回報，讓下一次 session 能可靠恢復

最適合與不適合的使用情境

當任務會跨越多個 session、涉及 subagents 或背景作業、或需要 checkpoint 與 retry 時，就很適合用 long-task-coordinator。如果只是一次對話就能做完的小任務，就不建議。repo 也明確指出，較輕量的規劃情境應優先考慮 planning-with-files，不要在不需要恢復能力時平白增加長任務協調的負擔。

如何使用 long-task-coordinator skill

long-task-coordinator 的安裝方式

repo 的 README 提供了手動安裝方式，也就是把 skill 用 symlink 連到你的 client skill directory，例如：

ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.claude/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.codex/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.gemini/skills/long-task-coordinator

如果你是透過 skill manager 安裝，請確認最後實際安裝的路徑，暴露出來的是 skills/long-task-coordinator 這個資料夾本身的內容，而不只是整個 repo root。

先讀這些檔案

如果你想快速上手、同時又保有足夠可靠性，建議依照這個順序閱讀：

1. skills/long-task-coordinator/SKILL.md
2. skills/long-task-coordinator/references/workflow.md
3. skills/long-task-coordinator/evals/prompts.md
4. skills/long-task-coordinator/README.md

這個順序之所以有效，是因為：

• SKILL.md 定義了觸發條件與核心規則
• references/workflow.md 提供可直接採用的狀態檔模式
• evals/prompts.md 讓你看到什麼才算是「正確行為」
• README.md 用來確認安裝方式與核心循環

這個 skill 需要哪些輸入

long-task-coordinator 在你提供以下資訊時會發揮得最好：

• 任務目標
• 明確的成功條件
• 工作是否已經在進行中
• durable state file 應該放在哪裡
• 目前有哪些 active worker 或 subagent 指派
• 下一個 checkpoint 的觸發條件，例如時間點或事件條件
• 已知 blocker 或相依項目

如果缺少這些資訊，模型還是可以開始，但會做出更多假設，最後留下的協調紀錄也會比較弱。

把模糊需求改寫成好的呼叫方式

較弱的請求：

Help me keep track of this migration.

較好的請求：

Use long-task-coordinator for this migration. Create or recover a durable state file at docs/migration-state.md. Goal: migrate service auth to OAuth2. Success criteria: tests pass, rollout notes written, old auth path disabled. We may hand work to subagents and resume across sessions. If any work is in flight, use an explicit waiting state instead of implying failure.

這個較強版本之所以效果更好，是因為它一開始就定義了持久化方式、範圍、完成判定邏輯，以及協調風格。

盡早建立 durable state file

在實務上最重要的習慣，就是在任務變複雜之前先建立狀態檔。參考文件建議的路徑像是：

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

至少要持久化保存以下內容：

• Goal
• Success criteria
• Status
• Current step
• Completed work
• Next action
• Next checkpoint
• Blockers
• Owners

這是採用 long-task-coordinator 時最關鍵的一點：如果你跳過狀態檔，這個 skill 大部分的價值也就跟著消失了。

每一輪都走一次恢復循環

repo 中的核心循環，就是 long-task-coordinator 實際好不好用的關鍵：

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

實際操作上代表：

1. 先讀取已保存的狀態
2. 驗證目前狀態是否仍然成立
3. 檢查委派出去的工作是否已有結果
4. 判斷接下來應該繼續、等待、重試、暫停，還是結束
5. 寫入更新後的狀態
6. 之後才向使用者回報

這個順序能確保下一個 session 真的有辦法恢復，而不是只能靠回憶。

使用明確狀態，尤其是 awaiting-result

這個 skill 一個細緻但很有價值的特點，就是 awaiting-result。很多 agent 會在任務派出去之後，假裝它已經失敗或完成，但其實只是仍在進行中。long-task-coordinator 提供了更乾淨的狀態模型：

• running：coordinator 正在主動處理
• awaiting-result：worker 或 job 仍在執行中
• paused：刻意暫停
• blocked：受到外部限制而無法推進
• complete：只有在成功條件真的滿足時才使用

對 Agent Orchestration 來說，這是整個 skill 最實用的區別之一。

委派工作時建議採用的流程

一個穩健的操作模式是：

1. 定義任務與成功條件
2. 建立狀態檔
3. 把範圍明確的工作指派給 worker
4. 記錄 owner 與預期回傳條件
5. 如果正在等待，就把狀態設為 awaiting-result
6. 恢復時依據狀態檔，而不是聊天記憶
7. 更新已完成事項與下一步行動
8. 只有在核對過條件後，才標示為 complete

和那種開放式的「繼續做下去」prompt 相比，這種模式安全得多，因為每次交接都有跡可循。

實務上好用的 prompt 模式

好的 long-task-coordinator 使用方式，通常都會把恢復語言寫得很清楚。例如：

• 「Use long-task-coordinator and recover from any existing state before proposing next steps.」
• 「Persist the updated status before reporting.」
• 「If a worker is still in flight, mark awaiting-result and define the next checkpoint.」
• 「Do not mark complete unless the saved state and success criteria agree.」

這些模式和 repo 裡的 eval prompts 直接對齊，也能有效降低那種看起來很有把握、其實不可靠的輸出。

常見的導入錯誤

大部分使用失敗，問題都出在流程缺口，而不是功能不夠：

• 依賴聊天紀錄，而不是檔案
• 用模糊的狀態文字，而不是定義好的狀態
• 還沒更新保存狀態就先回報進度
• 委派工作時沒有記 owner
• 還沒核對 acceptance criteria 就標成完成
• 把這個 skill 用在短任務上，導致不必要的協調成本

long-task-coordinator skill 常見問題

簡單任務也值得安裝 long-task-coordinator 嗎

通常不值得。如果任務很短、只會在單一 session 內完成，而且不需要恢復能力，long-task-coordinator 反而會增加額外成本。repo 也很明確地把它定位在那些會跨越單輪對話、或依賴 durable state 的工作上。

它和 planning-with-files 有什麼不同

planning-with-files 是較輕量的選項，適合你主要只是需要結構化規劃的情境。long-task-coordinator 則是為了可恢復性、明確等待狀態，以及中斷後的恢復而設計。當你在意的是狀態完整性，而不只是步驟整理，用這個比較合適。

long-task-coordinator 適合 Agent Orchestration 嗎

是，而且這是它最明確的適用情境之一。這個 skill 本來就是針對 coordinator-worker 架構、委派執行、背景作業，以及跨 session 交接所設計。它的 owner 追蹤與 awaiting-result 狀態，對 Agent Orchestration 特別有幫助。

它需要特定 runtime 或 framework 嗎

不需要。README 把它描述成刻意保持抽象且可攜的設計，不預設任何特定領域或 runtime。主要要求只有一個：你的 agent 必須能在工作區中讀寫 durable file。

初學者也能用這個 long-task-coordinator skill 嗎

可以，前提是你已經理解自己正在協調的任務。這個 skill 的概念本身不複雜，但初學者很容易過度套用。如果你的工作根本不涉及中斷、委派或可恢復性，建議先從更簡單的 planning skill 開始。

什麼情況不該使用 long-task-coordinator

以下情況就不建議使用：

• 任務一次就能完成
• 沒有之後再恢復的需求
• 沒有委派 worker 或背景程序參與
• 你不想多做維護狀態檔這一步

在這些情況下，一般 prompt 往往會更快。

如何改善 long-task-coordinator skill 的使用效果

先把成功條件寫得更強

影響品質最大的槓桿，是把完成判定寫得更精準。不要只寫「完成 migration」，而是改成這類條件：

• auth tests pass
• production config updated
• rollback note added
• legacy path disabled

成功條件越具體，模型就越不容易過早結案。

讓狀態檔具體，而且容易再次找到

不要把狀態藏在隨意命名的 scratch file 裡。把它放在可預期的路徑，例如 docs/oauth-migration-state.md。良好的恢復能力，仰賴的是下一個 session 不用猜就找得到那個檔案。

明確記錄 ownership

想讓 long-task-coordinator 用得更穩，務必要把責任歸屬寫清楚：

• Origin：定義任務
• Coordinator：維護狀態與流程順序
• Worker：執行範圍明確的工作

這個小習慣能有效減少重工、停滯，以及多個 agents 參與時的混亂。

用 checkpoint 條件強化 prompts

弱的 checkpoint 只會說「晚點再檢查」。強的 checkpoint 則會寫成「當 worker 回傳測試結果時恢復，或最晚於 15:00 UTC 恢復，以先發生者為準」。觸發條件越明確，coordinator 越不容易漂移失焦。

避免產生虛假的進度回報

一個常見失敗模式，是回報聽起來很順，但其實不可靠。改善方式是明確要求這個 skill：

• 先讀已保存的狀態
• 驗證狀態是否仍然正確
• 先持久化更新，再做摘要
• 清楚區分 waiting 與 blocked
• 依據成功條件來證明 complete

這樣才能讓 long-task-coordinator 在跨 session 使用時，輸出仍然值得信任。

把 eval prompts 當成驗收測試

evals/prompts.md 不只是拿來做 smoke testing，也很適合當成你自訂用法的本地檢查清單：

• 它能安全恢復被中斷的工作嗎？
• 它有誠實表達 waiting 狀態嗎？
• 它能用已保存狀態來證明完成嗎？

如果你客製化後的流程通不過這些測試，就表示你的 orchestration pattern 仍然太鬆散。

第一次跑完後再迭代調整

完成第一輪協調之後，請回頭檢查狀態檔，把任何模糊之處收斂得更具體：

• 替換模糊狀態
• 補上遺漏的 owners
• 釐清 blockers
• 把過大的 next actions 拆開
• 加入真正可觸發的 checkpoint 條件

long-task-coordinator 的效果通常在第一次執行後就能快速提升，因為之後每次恢復都不是靠記憶，而是依賴那份持久化狀態檔。