long-task-coordinator

Tổng quan về skill long-task-coordinator

long-task-coordinator làm gì

long-task-coordinator là một skill điều phối dành cho các công việc phải sống sót qua gián đoạn, bàn giao và những khoảng cách dài giữa các lượt làm việc. Nhiệm vụ cốt lõi của nó rất đơn giản: đưa công việc chạy dài ra khỏi bộ nhớ chat vốn mong manh và chuyển vào một file trạng thái bền vững, có chuyển trạng thái rõ ràng, kiểm tra khả năng khôi phục và theo dõi bước tiếp theo.

Ai nên cài đặt

Skill này phù hợp nhất với người dùng đang làm agent orchestration, nghiên cứu ủy quyền, migration, batch job hoặc bất kỳ đầu việc nào có thể phải tạm dừng, tiếp tục sau, hay chờ một worker khác xử lý xong. Nếu quy trình của bạn thường có kiểu “để mai làm tiếp” hoặc “giao đi rồi quay lại kiểm tra sau”, thì long-task-coordinator là lựa chọn rất hợp.

Nhu cầu thực tế mà skill này giải quyết

Người dùng không cài long-task-coordinator chỉ để “lập kế hoạch tốt hơn”. Họ cài nó để biến công việc dài hạn thành thứ có thể khôi phục và phản ánh đúng trạng thái thực:

• khôi phục trạng thái sau khi mất ngữ cảnh
• theo dõi quyền sở hữu giữa coordinator và các worker
• biểu diễn rõ các trạng thái chờ
• tránh tuyên bố hoàn thành sai sự thật
• tiếp tục từ một nguồn trạng thái đã lưu thay vì đoán lại từ lịch sử chat

Điểm khác biệt so với một prompt lập kế hoạch thông thường

Điểm khác biệt không nằm ở chuyên môn theo domain. Nó nằm ở kỷ luật vận hành:

• một file trạng thái bền vững duy nhất
• một vòng lặp cố định: READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END
• các trạng thái tường minh như running, awaiting-result, paused, blocked và complete
• ưu tiên ghi trạng thái trước rồi mới báo cáo, để phiên sau có thể khôi phục đáng tin cậy

Trường hợp phù hợp và không phù hợp

Hãy dùng long-task-coordinator khi công việc kéo dài qua nhiều phiên, có subagent hoặc background job, hoặc cần checkpoint và retry. Hãy bỏ qua nó nếu chỉ là một tác vụ nhỏ, xử lý trong một lượt. Repository cũng nói rõ rằng các nhu cầu lập kế hoạch nhẹ hơn nên dùng planning-with-files, thay vì gánh thêm overhead của long-task chỉ trong khi không cần khả năng khôi phục.

Cách dùng skill long-task-coordinator

Tùy chọn cài đặt long-task-coordinator

README của repository hướng dẫn cách cài thủ công bằng symlink skill vào thư mục skill của client, ví dụ:

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

Nếu bạn dùng skill manager, hãy đảm bảo đường dẫn sau khi cài vẫn trỏ đúng tới nội dung thật của thư mục skills/long-task-coordinator, chứ không chỉ trỏ tới root của repo.

Hãy đọc các file này trước

Nếu muốn tiếp cận nhanh nhưng vẫn chắc tay, hãy đọc theo thứ tự sau:

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

Vì sao thứ tự này hiệu quả:

• SKILL.md định nghĩa điều kiện kích hoạt và các quy tắc cốt lõi
• references/workflow.md đưa ra mẫu state-file có thể dùng ngay
• evals/prompts.md cho thấy “hành vi đúng” trông như thế nào
• README.md xác nhận cách cài đặt và vòng lặp cốt lõi

Skill cần những đầu vào nào

long-task-coordinator hoạt động tốt nhất khi bạn cung cấp:

• mục tiêu công việc
• tiêu chí hoàn thành cụ thể
• công việc đã bắt đầu hay chưa
• nơi file trạng thái bền vững sẽ được lưu
• các phân công worker hoặc subagent đang hoạt động
• mốc checkpoint tiếp theo, ví dụ theo thời gian hoặc điều kiện
• các blocker hoặc dependency đã biết

Nếu thiếu các thông tin này, model vẫn có thể bắt đầu, nhưng sẽ phải tự suy đoán nhiều hơn và bản ghi điều phối tạo ra sẽ kém chắc chắn hơn.

Biến một yêu cầu mơ hồ thành lời gọi tốt

Yêu cầu yếu:

Help me keep track of this migration.

Yêu cầu tốt hơn:

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.

Phiên bản mạnh hơn cho ra kết quả tốt hơn vì nó xác định ngay từ đầu cách lưu trạng thái, phạm vi, logic hoàn thành và kiểu điều phối.

Tạo file trạng thái bền vững càng sớm càng tốt

Thói quen vận hành quan trọng nhất là tạo file trạng thái trước khi công việc trở nên rối. Tài liệu tham chiếu gợi ý các đường dẫn như:

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

Tối thiểu hãy lưu lại:

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

Đây là điểm mấu chốt khi áp dụng: nếu bạn bỏ qua file trạng thái, bạn sẽ mất phần lớn giá trị của long-task-coordinator.

Dùng vòng lặp khôi phục ở mọi vòng làm việc

Vòng lặp cốt lõi trong repository chính là trái tim thực dụng của cách dùng long-task-coordinator:

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

Trong thực tế, điều này có nghĩa là:

1. đọc trạng thái đã lưu trước
2. xác minh xem trạng thái hiện tại còn đúng không
3. kiểm tra xem công việc đã ủy quyền có trả kết quả chưa
4. quyết định nên tiếp tục, chờ, thử lại, tạm dừng hay đóng lại
5. ghi trạng thái đã cập nhật
6. chỉ sau đó mới báo cáo cho người dùng

Chính thứ tự này giúp phiên làm việc tiếp theo có thể khôi phục được.

Dùng trạng thái tường minh, đặc biệt là awaiting-result

Một điểm tinh tế nhưng rất giá trị của skill này là cách dùng awaiting-result. Nhiều agent giả vờ có tiến triển bằng cách hành xử như thể một tác vụ đã giao đi đã thất bại hoặc đã xong, trong khi thực tế nó vẫn đang chạy. Skill này đưa ra một mô hình sạch hơn:

• running cho công việc coordinator đang trực tiếp xử lý
• awaiting-result khi worker hoặc job vẫn đang thực thi
• paused khi chủ động dừng lại
• blocked khi có ràng buộc bên ngoài chặn tiến độ
• complete chỉ khi tiêu chí hoàn thành thực sự đã được đáp ứng

Với Agent Orchestration, đây là một trong những khác biệt hữu ích nhất của toàn bộ skill.

Quy trình gợi ý cho công việc được ủy quyền

Một mẫu vận hành tốt là:

1. xác định nhiệm vụ và tiêu chí hoàn thành
2. tạo file trạng thái
3. giao một phần việc có phạm vi rõ ràng cho worker
4. ghi lại owner và điều kiện dự kiến để nhận kết quả
5. đặt trạng thái thành awaiting-result nếu đang chờ
6. tiếp tục bằng quy trình recovery, không dựa vào trí nhớ
7. cập nhật các mục đã xong và hành động tiếp theo
8. chỉ đánh dấu complete sau khi đã kiểm tra tiêu chí

Mẫu này an toàn hơn những prompt kiểu “cứ làm tiếp đi” không giới hạn, vì mọi lần bàn giao đều có thể kiểm tra lại được.

Các mẫu prompt thực tế hoạt động tốt

Prompt dùng long-task-coordinator hiệu quả thường có ngôn ngữ nhấn mạnh việc recovery. Ví dụ:

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

Các mẫu này bám sát trực tiếp với eval prompts của repository và giúp giảm tình trạng tự tin giả.

Những lỗi phổ biến khi áp dụng

Phần lớn các trường hợp dùng không hiệu quả đến từ lỗ hổng quy trình, không phải do thiếu tính năng:

• dựa vào lịch sử chat thay vì file
• dùng mô tả trạng thái mơ hồ thay vì các trạng thái đã định nghĩa
• báo cáo tiến độ trước khi cập nhật trạng thái đã lưu
• không ghi owner cho công việc được ủy quyền
• đánh dấu complete mà không kiểm tra acceptance criteria
• dùng skill cho các tác vụ ngắn trong khi overhead điều phối là không cần thiết

Câu hỏi thường gặp về skill long-task-coordinator

long-task-coordinator có đáng cài cho tác vụ đơn giản không

Thường là không. Nếu tác vụ ngắn, chỉ diễn ra trong một phiên và không cần khôi phục, long-task-coordinator sẽ tạo thêm overhead. Repo cũng định vị rất rõ: skill này dành cho công việc kéo dài hơn một lượt hoặc phụ thuộc vào trạng thái bền vững.

Nó khác gì so với planning-with-files

planning-with-files là lựa chọn nhẹ hơn khi bạn chủ yếu cần lập kế hoạch có cấu trúc. long-task-coordinator dành cho khả năng tiếp tục lại, các trạng thái chờ tường minh và khôi phục sau gián đoạn. Hãy chọn skill này khi tính toàn vẹn của trạng thái quan trọng hơn việc chỉ sắp xếp các bước.

long-task-coordinator có phù hợp cho Agent Orchestration không

Có. Đây là một trong những trường hợp phù hợp rõ ràng nhất. Skill được thiết kế cho mô hình coordinator-worker, thực thi ủy quyền, background job và bàn giao qua nhiều phiên. Cơ chế theo dõi owner và trạng thái awaiting-result đặc biệt hữu ích cho Agent Orchestration.

Nó có yêu cầu runtime hoặc framework cụ thể không

Không. README mô tả skill này là có chủ đích trừu tượng và dễ перенос giữa các môi trường. Nó không giả định một domain hay runtime cụ thể nào. Yêu cầu chính là agent của bạn có thể đọc và ghi một file bền vững trong workspace.

Người mới có dùng được skill long-task-coordinator này không

Có, nếu họ đã hiểu công việc mình đang điều phối. Bản thân skill này khá đơn giản về mặt khái niệm, nhưng người mới rất dễ lạm dụng nó. Nếu bạn không xử lý gián đoạn, ủy quyền hoặc nhu cầu resume, hãy bắt đầu bằng một skill lập kế hoạch đơn giản hơn.

Khi nào không nên dùng long-task-coordinator

Tránh dùng khi:

• tác vụ sẽ hoàn tất trong một lần xử lý
• không có nhu cầu tiếp tục lại sau đó
• không có worker được ủy quyền hay background process nào tham gia
• bạn không muốn thêm bước duy trì file trạng thái

Trong những trường hợp đó, prompt thông thường có thể nhanh hơn.

Cách cải thiện skill long-task-coordinator

Bắt đầu bằng tiêu chí hoàn thành mạnh hơn

Đòn bẩy chất lượng lớn nhất nằm ở việc làm sắc nét logic hoàn thành. Thay vì viết “finish the migration”, hãy viết tiêu chí như:

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

Tiêu chí tốt hơn sẽ khiến model khó đóng tác vụ quá sớm hơn nhiều.

Làm cho file trạng thái cụ thể và dễ tìm lại

Đừng giấu trạng thái vào một scratch file đặt tên tùy tiện. Hãy đặt nó ở một đường dẫn dễ đoán như docs/oauth-migration-state.md. Recovery tốt phụ thuộc vào việc phiên sau thực sự tìm thấy file đó mà không phải đoán.

Ghi rõ ownership

Để dùng long-task-coordinator tốt hơn, hãy luôn ghi rõ ai sở hữu phần nào:

• Origin: xác định nhiệm vụ
• Coordinator: duy trì trạng thái và thứ tự xử lý
• Worker: thực thi phần việc có phạm vi giới hạn

Thói quen nhỏ này giúp giảm trùng lặp, giảm công việc bị treo và tránh nhầm lẫn khi có nhiều agent cùng tham gia.

Cải thiện prompt bằng điều kiện checkpoint

Một checkpoint yếu sẽ nói “check back later.” Một checkpoint mạnh sẽ nói “resume when the worker returns test results or at 15:00 UTC, whichever comes first.” Trigger càng rõ, coordinator càng ít bị trôi hướng.

Ngăn báo cáo tiến độ sai lệch

Một failure mode phổ biến là báo cáo nghe rất trơn tru nhưng không đáng tin. Cách khắc phục là yêu cầu skill:

• đọc trạng thái đã lưu trước
• xác minh xem nó còn chính xác không
• lưu cập nhật trước khi tóm tắt
• phân biệt rõ waiting với blocked
• chỉ ra cơ sở đánh dấu complete dựa trên success criteria

Cách này giúp đầu ra của long-task-coordinator giữ được độ tin cậy xuyên suốt nhiều phiên.

Dùng eval prompts như bài test chấp nhận

evals/prompts.md hữu ích không chỉ để smoke test. Hãy coi các prompt đó như một checklist cục bộ cho các biến thể bạn tự điều chỉnh:

• nó có thể tiếp tục công việc bị gián đoạn một cách an toàn không?
• nó có biểu diễn trạng thái chờ một cách trung thực không?
• nó có chứng minh việc hoàn thành bằng trạng thái đã lưu không?

Nếu cách dùng tùy biến của bạn không qua được các bài test này, thì pattern orchestration của bạn vẫn còn quá lỏng.

Lặp cải tiến sau vòng chạy đầu tiên

Sau vòng điều phối đầu tiên, hãy mở file trạng thái ra và siết chặt mọi điểm còn mơ hồ:

• thay trạng thái chung chung bằng trạng thái rõ nghĩa hơn
• thêm owner còn thiếu
• làm rõ blocker
• tách các next action quá lớn
• thêm một điều kiện checkpoint thực sự

long-task-coordinator cải thiện rất nhanh khi trạng thái đã lưu trở nên cụ thể hơn, vì mọi lần recovery về sau đều dựa vào file đó chứ không dựa vào trí nhớ.