long-task-coordinator

long-task-coordinator skill の概要

long-task-coordinator ができること

long-task-coordinator は、中断・引き継ぎ・ターン間の長い空白があっても進行を維持したい作業向けの調整スキルです。中核となる役割はシンプルで、壊れやすいチャット上の記憶に頼るのではなく、長く続く作業を耐久性のある state file に移し、明示的なステータス遷移、復旧チェック、次のアクション管理で運用できるようにすることです。

どんな人に向いているか

この skill は、agent orchestration、委任した調査、migration、batch job、あるいは「いったん止めて後で再開する」「別の worker に渡して後から確認する」といった流れが発生する作業に特に向いています。ワークフローの中に「明日またここから再開する」「dispatch して後で戻る」が含まれるなら、long-task-coordinator skill は有力な選択肢です。

この skill が本当に解決する課題

ユーザーが long-task-coordinator を入れる理由は、単に「計画をうまく立てるため」ではありません。長期タスクを、復旧可能で、ごまかしのない形で扱うためです。

• コンテキスト消失後でも状態を復元できる
• coordinator と worker の担当を追跡できる
• 待機中の状態を明示的に表現できる
• 完了していないのに完了したように見せるのを防げる
• 過去のチャットを推測で読み解くのではなく、保存済みの唯一の正本から再開できる

通常の planning prompt と何が違うのか

差が出るのは、ドメイン知識ではありません。ワークフローの規律です。

• 耐久性のある state file を 1 つ持つ
• READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END という固定ループで回す
• running、awaiting-result、paused、blocked、complete といった明示的な状態を使う
• 報告より先に保存することを優先し、次のセッションで確実に復旧できるようにする

long-task-coordinator が向くケース・向かないケース

long-task-coordinator を使うべきなのは、複数セッションにまたがる作業、subagent や background job を含む作業、checkpoint や retry が必要な作業です。逆に、1 回で終わる小さなタスクには向きません。repository でも、復旧が不要な軽量 planning 用途は long-task の管理を持ち込まず、planning-with-files を使うよう明示しています。

long-task-coordinator skill の使い方

long-task-coordinator のインストール方法

repository の README では、skill を client の skill directory に symlink する手動インストール方法が案内されています。例:

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 を使う場合でも、最終的なインストール先で参照されるのが repo root ではなく、実際の skills/long-task-coordinator フォルダの中身になっていることを確認してください。

最初に読むべきファイル

手早く、かつ確実に導入したいなら、読む順番は次の通りです。

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 で実用的な state-file パターンをつかめる
• evals/prompts.md で「正しい振る舞い」の具体像が見える
• README.md でインストール方法とコアループを再確認できる

この skill に渡すべき入力

long-task-coordinator skill は、次の情報を渡すと最も安定して機能します。

• タスクの目標
• 具体的な成功条件
• すでに作業が進行中かどうか
• durable state file をどこに置くか
• 現在動いている worker または subagent の割り当て
• 次の checkpoint の発火条件（時刻や条件など）
• 既知の blocker や依存関係

これらがなくても開始はできますが、前提を推測する場面が増え、coordination record の品質は下がります。

曖昧な依頼を良い invocation に変える

弱い依頼:

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.

後者のほうが出力品質が上がるのは、永続化、対象範囲、完了判定、coordination の進め方が最初から明確になるためです。

durable state file は早めに作る

運用上いちばん重要なのは、作業が入り組む前に state file を作っておくことです。reference では、たとえば次のような path が推奨されています。

• 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

ここが導入の要点です。state file を省くと、long-task-coordinator skill の価値の大半を取り逃します。

毎ラウンド recovery loop を回す

repository のコアループは、long-task-coordinator 運用の実務的な中心です。

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

実際には、次の順番で進めます。

1. まず保存済みの state を読む
2. その status がまだ正しいか確認する
3. 委任した作業から結果が返ってきていないか確認する
4. 継続・待機・再試行・一時停止・終了のどれにするか決める
5. 更新後の state を書き戻す
6. そのあとでユーザーに報告する

この順序だからこそ、次のセッションでも確実に復旧できます。

明示的な状態を使う。特に awaiting-result が重要

この skill の地味ながら非常に効く特徴が awaiting-result です。多くの agent は、dispatch したタスクがまだ進行中なだけなのに、失敗したか完了したかのように扱ってしまいます。long-task-coordinator では、より正確なモデルを使えます。

• coordinator 自身がアクティブに動いているときは running
• worker や job がまだ実行中なら awaiting-result
• 意図的に止めているなら paused
• 外部制約で進められないなら blocked
• 成功条件を本当に満たしたときだけ complete

Agent Orchestration では、この区別が skill 全体の中でも特に重要です。

委任作業での推奨ワークフロー

運用パターンとしては、次の流れが堅実です。

1. タスクと成功条件を定義する
2. state file を作る
3. worker に範囲を区切った作業を割り当てる
4. owner と結果が返る条件を記録する
5. 待機に入るなら status を awaiting-result にする
6. 記憶ではなく recovery を起点に再開する
7. 完了済み項目と次の action を更新する
8. 条件を確認したあとでのみ complete を付ける

handoff が追跡可能になるぶん、このパターンは「とにかく続けて」のような open-ended な prompt より安全です。

実用的で効く prompt パターン

long-task-coordinator をうまく使えている prompt には、recovery を促す文言が入っていることが多いです。例:

• “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.”

これらは repository の eval prompt とも直接整合しており、根拠の薄い確信を減らすのに有効です。

導入時によくある失敗

うまくいかない原因の大半は、機能不足ではなく運用の抜けです。

• ファイルではなく chat history に頼ってしまう
• 定義済みの状態を使わず、曖昧な status 文言で済ませる
• 保存済み state を更新する前に進捗報告してしまう
• 委任作業の owner を記録していない
• acceptance criteria を確認せずに完了扱いする
• coordination のオーバーヘッドが不要な短いタスクに使ってしまう

long-task-coordinator skill の FAQ

単純なタスクでも long-task-coordinator を入れる価値はあるか

通常はありません。タスクが短く、1 セッションで終わり、recovery も不要なら、long-task-coordinator はオーバーヘッドになります。repo でも、これはターンをまたいで存続する作業や、durable state が必要な作業向けだと明確に位置づけられています。

planning-with-files との違いは何か

planning-with-files は、主に構造化された planning がほしいときの軽量な選択肢です。long-task-coordinator は、再開可能性、明示的な待機状態、中断後の recovery が必要な場面向けです。単なる手順整理よりも state の完全性が重要なら、こちらを選ぶべきです。

Agent Orchestration に long-task-coordinator は向いているか

はい。もっとも適合がはっきりしている用途の 1 つです。この skill は、coordinator-worker 構成、委任実行、background job、複数セッションをまたぐ handoff を前提に設計されています。特に owner tracking と awaiting-result は Agent Orchestration で役立ちます。

特定の runtime や framework は必要か

いいえ。README でも、意図的に抽象度を高く保ち、移植しやすい設計だと説明されています。特定ドメインや runtime には依存しません。主な要件は、agent が workspace 内の durable file を読み書きできることだけです。

初心者でもこの long-task-coordinator skill を使えるか

はい。少なくとも、自分が調整しようとしているタスク自体は理解していることが前提です。skill の考え方そのものはシンプルですが、初心者は適用範囲を広げすぎがちです。中断、委任、再開可能性が絡まないなら、まずはもっと単純な planning skill から始めるほうが向いています。

long-task-coordinator を使わないほうがよいのはいつか

次のようなケースでは避けるのが無難です。

• タスクが 1 回で完了する
• 後で再開する必要がない
• 委任された worker や background process が関与しない
• state file を保守するひと手間を増やしたくない

こうした場合は、通常の prompt のほうが速いことがあります。

long-task-coordinator skill を改善するには

まず成功条件を強くする

品質を最も左右するのは、完了判定の鋭さです。たとえば “finish the migration” ではなく、次のように書きます。

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

成功条件が具体的になるほど、model が早まって task を閉じてしまいにくくなります。

state file は具体的で再発見しやすくする

state を適当な scratch file に埋もれさせないでください。docs/oauth-migration-state.md のように予測しやすい path に置くべきです。良い recovery は、次のセッションが推測なしで見つけられる file に依存します。

owner を明示的に記録する

long-task-coordinator をより安定して使うには、誰が何を持っているかを必ず記録してください。

• Origin: タスクを定義する
• Coordinator: state と順序を管理する
• Worker: 範囲が限定された作業を実行する

この小さな習慣だけで、重複作業、停滞、複数 agent 参加時の混乱を減らせます。

checkpoint 条件を prompt に入れて改善する

弱い checkpoint は「あとで確認する」です。強い checkpoint は「worker が test result を返した時点、または 15:00 UTC のどちらか早い方で再開する」です。トリガーが明確なほど、coordinator が流れてしまう可能性は下がります。

見かけだけの進捗報告を防ぐ

よくある失敗は、読み心地はよいのに信頼できない報告です。これを防ぐには、skill に次を指示してください。

• まず保存済み state を読む
• その内容がまだ正確か検証する
• 要約する前に更新を保存する
• waiting と blocked を区別する
• complete の根拠を success criteria に照らして示す

これで、セッションをまたいでも long-task-coordinator の出力が信頼しやすくなります。

eval prompt を受け入れテストとして使う

evals/prompts.md は単なる smoke test 以上に役立ちます。自分用に調整した運用を確かめるローカルチェックリストとして扱ってください。

• 中断された作業を安全に再開できるか
• 待機状態を正直に表現できているか
• 保存済み state をもとに完了を証明できるか

カスタマイズした使い方がこれらを満たせないなら、その orchestration pattern はまだ緩すぎます。

最初の運用後に見直して詰める

最初の coordination round が終わったら、state file を見直して曖昧な点を絞り込んでください。

• 曖昧な status を置き換える
• 抜けている owner を追加する
• blocker を明確にする
• 大きすぎる next action を分割する
• 実際に機能する checkpoint 条件を加える

long-task-coordinator skill は、保存される state が具体的になるほど素早く改善していきます。今後の recovery はすべて記憶ではなく、その file に依存するからです。