long-task-coordinator

Overview of long-task-coordinator skill

What long-task-coordinator does

long-task-coordinator is a coordination skill for work that must survive interruptions, handoffs, and long gaps between turns. Its core job is simple: move long-running work out of fragile chat memory and into a durable state file with explicit status transitions, recovery checks, and next-step tracking.

Who should install it

This skill is best for users doing agent orchestration, delegated research, migrations, batch jobs, or any task where you may pause, resume later, or wait on another worker. If your workflow includes “pick this back up tomorrow” or “dispatch and check back later,” the long-task-coordinator skill is a strong fit.

The real job-to-be-done

Users do not install long-task-coordinator just to “plan better.” They install it to make long work recoverable and honest:

• recover state after context loss
• track ownership across coordinator and workers
• represent waiting states explicitly
• avoid false completion claims
• resume from a saved source of truth instead of guessing from prior chat

What makes it different from a normal planning prompt

The differentiator is not domain expertise. It is workflow discipline:

• one durable state file
• a fixed loop: READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END
• explicit statuses like running, awaiting-result, paused, blocked, and complete
• a bias toward persisting before reporting, so the next session can recover reliably

Best-fit and misfit cases

Use long-task-coordinator when the task spans multiple sessions, involves subagents or background jobs, or needs checkpoints and retries. Skip it for a small one-turn task. The repository explicitly points lighter planning use cases toward planning-with-files instead of adding long-task overhead where recovery is unnecessary.

How to Use long-task-coordinator skill

long-task-coordinator install options

The repository README shows manual install by symlinking the skill into your client skill directory, for example:

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

If you use a skill manager, ensure the final installed path still exposes the actual skills/long-task-coordinator folder contents, not just the repo root.

Read these files first

For a fast but reliable adoption pass, read in this order:

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

Why this order works:

• SKILL.md defines triggering conditions and core rules
• references/workflow.md gives the usable state-file pattern
• evals/prompts.md shows what “correct behavior” looks like
• README.md confirms installation and the core loop

What input the skill needs

The long-task-coordinator skill works best when you provide:

• the task goal
• concrete success criteria
• whether work is already in progress
• where the durable state file should live
• any active worker or subagent assignments
• the next checkpoint trigger, such as time or condition
• known blockers or dependencies

Without these, the model can still start, but it will make more assumptions and produce a weaker coordination record.

Turn a rough request into a good invocation

Weak request:

Help me keep track of this migration.

Better request:

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.

The stronger version improves output because it defines persistence, scope, completion logic, and coordination style up front.

Create a durable state file early

The most important operational habit is creating the state file before the work gets messy. The reference recommends paths like:

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

At minimum, persist:

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

This is the key adoption point: if you skip the state file, you lose most of the value of the long-task-coordinator skill.

Use the recovery loop every round

The repository’s core loop is the practical heart of long-task-coordinator usage:

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

In practice this means:

1. read the saved state first
2. verify whether the status is still true
3. check if delegated work returned
4. decide whether to continue, wait, retry, pause, or close
5. write the updated state
6. only then report to the user

This ordering is what keeps the next session recoverable.

Use explicit states, especially awaiting-result

A subtle but valuable feature of this skill is the use of awaiting-result. Many agents fake progress by acting as if a dispatched task has failed or finished when it is simply still in flight. This skill gives a cleaner model:

• running for active coordinator work
• awaiting-result when a worker or job is still executing
• paused when intentionally stopped
• blocked when external constraints prevent progress
• complete only when success criteria are actually met

For Agent Orchestration, this is one of the most useful distinctions in the whole skill.

Suggested workflow for delegated work

A good operating pattern is:

1. define the task and success criteria
2. create the state file
3. assign bounded work to a worker
4. record owner and expected return condition
5. set status to awaiting-result if waiting
6. resume with recovery, not memory
7. update completed items and next action
8. mark complete only after checking criteria

This pattern is safer than open-ended “keep going” prompts because handoffs become auditable.

Practical prompt patterns that work well

Good long-task-coordinator usage prompts tend to include recovery language. Examples:

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

These patterns align directly with the repository’s eval prompts and reduce fake certainty.

Common adoption mistakes

Most failed usage comes from process gaps, not missing features:

• relying on chat history instead of a file
• using vague status text instead of the defined states
• reporting progress before updating saved state
• failing to record owners for delegated work
• marking complete without checking acceptance criteria
• using the skill for short tasks where the coordination overhead is unnecessary

long-task-coordinator skill FAQ

Is long-task-coordinator worth installing for simple tasks

Usually no. If the task is short, single-session, and does not require recovery, long-task-coordinator adds overhead. The repo explicitly positions it for work that outlives a turn or depends on durable state.

How is it different from planning-with-files

planning-with-files is the lighter option when you mainly need structured planning. long-task-coordinator is for resumability, explicit waiting states, and recovery after interruption. Choose this one when state integrity matters more than just step organization.

Is long-task-coordinator good for Agent Orchestration

Yes. This is one of the clearest fits. The skill is designed for coordinator-worker setups, delegated execution, background jobs, and multi-session handoffs. Its owner tracking and awaiting-result state are particularly useful for Agent Orchestration.

Does it require a specific runtime or framework

No. The README describes it as intentionally abstract and portable. It does not assume a particular domain or runtime. The main requirement is that your agent can read and write a durable file in the workspace.

Can beginners use this long-task-coordinator skill

Yes, if they already understand the task they are coordinating. The skill itself is conceptually simple, but beginners can overapply it. If you are not dealing with interruptions, delegation, or resumability, start with a simpler planning skill.

When should I not use long-task-coordinator

Avoid it when:

• the task will finish in one pass
• there is no need to resume later
• no delegated worker or background process is involved
• you do not want the extra step of maintaining a state file

In those cases, ordinary prompts may be faster.

How to Improve long-task-coordinator skill

Start with stronger success criteria

The biggest quality lever is sharper completion logic. Instead of “finish the migration,” write criteria like:

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

Better criteria make it much harder for the model to close the task early.

Make the state file concrete and easy to rediscover

Do not hide the state in an arbitrary scratch file. Put it in a predictable path like docs/oauth-migration-state.md. Good recovery depends on a file the next session will actually find without guessing.

Record ownership explicitly

For better long-task-coordinator usage, always record who owns what:

• Origin: defines the task
• Coordinator: maintains state and sequencing
• Worker: executes bounded work

This small habit reduces duplication, stalled work, and confusion when multiple agents participate.

Improve prompts with checkpoint conditions

A weak checkpoint says, “check back later.” A strong checkpoint says, “resume when the worker returns test results or at 15:00 UTC, whichever comes first.” The more explicit the trigger, the less likely the coordinator is to drift.

Prevent false progress reports

One common failure mode is smooth-sounding but unreliable reporting. Fix it by instructing the skill to:

• read saved state first
• verify whether it is still accurate
• persist updates before summarizing
• distinguish waiting from blocked
• justify complete against success criteria

This keeps long-task-coordinator outputs trustworthy across sessions.

Use the eval prompts as acceptance tests

evals/prompts.md is useful beyond smoke testing. Treat those prompts as a local checklist for your own adaptations:

• can it resume interrupted work safely?
• does it represent waiting honestly?
• does it prove completion with saved state?

If your customized usage fails those tests, your orchestration pattern is still too loose.

Iterate after the first run

After the first coordination round, inspect the state file and tighten anything ambiguous:

• replace vague statuses
• add missing owners
• clarify blockers
• split oversized next actions
• add a real checkpoint condition

The long-task-coordinator skill improves quickly when the persisted state becomes more specific, because every future recovery depends on that file rather than on memory.