SKILL.md

name	agent-long-task-skill
description	Use this skill for long tasks, multi-step coding tasks, batch fixes, refactoring, productization, requirement refinement, task planning, handoff, final verification, preventing missed requirements, and continuing interrupted work.

Agent Long Task Skill

Use this Skill to turn a messy, long, or multi-requirement request into an execution plan that can be tracked, executed, recovered, verified, and handed off.

Trigger Conditions

Use this Skill when the user request includes any of the following:

• Long task
• Multiple requirements
• More than 5 task items
• Multi-file changes
• Refactor
• Batch fixes
• Productization
• "fix all"
• "don't miss anything"
• "continue"
• "handoff"
• "verify"
• "complete everything"

Required Lifecycle

The workflow is not a simple checklist. Treat it as a full long-task lifecycle:

messy user request
→ requirement refinement and compression
→ structured execution document
→ task list
→ step-by-step execution
→ failure/blocker recovery attempts
→ final verification pass
→ final user-facing report

Follow these steps:

1. Receive the user's messy, vague, or multi-requirement prompt.
2. Compress and refine it into a concise, executable requirement document.
3. Preserve the user's intent while removing repetition, ambiguity, and token-heavy wording.
4. Convert every requirement into one or more task IDs.
5. Create .agent/task-plan.json with a task list and acceptance criteria before implementation.
6. Execute tasks one by one.
7. Update task status after meaningful progress.
8. If a task fails or hits resistance, attempt reasonable recovery methods within the task scope.
9. If recovery still fails, mark the task as failed or blocked, explain why, and provide the next recovery path.
10. After all tasks have been attempted, run a final verification pass.
11. Check completion status against the task list and acceptance criteria.
12. Do not treat final verification as re-executing every task from scratch.
13. Only after every required task is verified may the agent claim the long task is complete.
14. If any task remains pending, in_progress, failed, blocked, or unverified, do not claim full completion.
15. Generate .agent/final-report.md.
16. Generate .agent/handoff.md if work is too long, interrupted, blocked, or cannot be completed in one pass.

Requirement Refinement Rules

The first output should be a concise execution document, not a long restatement of the user's entire prompt.

• Do not copy the user's full messy prompt repeatedly.
• Convert vague language into concise executable requirements.
• Keep each task short and testable.
• Keep acceptance criteria specific but not verbose.
• Preserve traceability from original requirement to task ID.
• Prefer concise summaries over long explanations.

Strict Rules

• Never begin implementation before creating a task plan.
• Every user requirement must map to one or more task IDs.
• Every task must have acceptance criteria.
• Never claim completion if any task is pending, failed, blocked, or unverified.
• Never hide failed or skipped work.
• If blocked, explain the blocker and recovery path.
• If context is getting long, create handoff notes.
• Keep responses concise and execution-focused.
• Do not repeatedly ask the user for clarification unless truly blocked.
• Prefer best-effort progress with explicit assumptions.

Language and Display Rules

• Use the same language as the user's prompt for user-facing task titles, notes, summaries, handoff reports, and final reports.
• For Chinese prompts, use Chinese task UI labels by default.
• Keep machine-readable JSON enum values in English.
• Do not localize status enum values inside the status field.
• Localized labels belong in display.statusLabels, Markdown tables, summaries, and reports.
• If the user requests bilingual output, include both English and Chinese user-facing labels.

English display labels:

{
  "pending": "⚪ Pending",
  "in_progress": "🟡 In Progress",
  "done": "✅ Done",
  "failed": "🔴 Failed",
  "blocked": "🟠 Blocked",
  "verified": "🔵 Verified",
  "skipped": "🟣 Skipped"
}

Chinese display labels:

{
  "pending": "⚪ 待处理",
  "in_progress": "🟡 进行中",
  "done": "✅ 已完成",
  "failed": "🔴 失败",
  "blocked": "🟠 阻塞",
  "verified": "🔵 已验收",
  "skipped": "🟣 已跳过"
}

Chinese progress example:

任务进度：8/12
✅ 已完成：5
🟡 进行中：1
🔴 失败：1
🟠 阻塞：1
⚪ 待处理：4

For Chinese prompts, final user-facing reports should use Chinese section titles:

## 最终报告
## 关键改动
## 验收情况
## 失败项
## 阻塞项
## 已跳过项
## 剩余风险
## 建议本地重点检查

For English prompts, final user-facing reports should use English section titles:

## Final Report
## Key Changes
## Verification Performed
## Failed Items
## Blocked Items
## Skipped Items
## Remaining Risks
## Recommended Local Checks

Task Plan Files

Create these files as needed during execution:

.agent/task-plan.json
.agent/status.json
.agent/handoff.md
.agent/final-report.md

Use schemas/agent-task-plan.schema.json as the reference shape for .agent/task-plan.json.

Task Item Format

Each task item should follow this structure:

{
  "id": "T01",
  "title": "Fix homepage visual issue",
  "status": "pending",
  "priority": "high",
  "acceptance": "Homepage visual issue is corrected and verified.",
  "filesChanged": [],
  "notes": ""
}

Status Meanings

pending → not started
in_progress → currently being worked on
done → implementation work appears completed, but final verification may still be pending
verified → checked against acceptance criteria and confirmed complete
failed → attempted and failed after reasonable recovery attempts
blocked → cannot proceed due to missing information, dependency, permission, or technical blocker
skipped → intentionally skipped with a stated reason

done is not the same as verified. A task should only become verified after the final verification pass or after explicit acceptance checking. The agent must not claim full completion while important tasks are only done but not verified.

Planning Guidance

When refining the request:

• Preserve all explicit user constraints.
• Split compound requirements into separate task IDs.
• Capture assumptions instead of asking repeated clarification questions.
• Mark risky or ambiguous items early.
• Keep task titles short and action-oriented.
• Give every task a concrete acceptance criterion.

Execution Guidance

During implementation:

• Work one task item at a time.
• Move an item to in_progress before making meaningful changes.
• Move an item to done only after implementation work appears complete.
• Move an item to verified only after checking the acceptance criterion.
• Use failed, blocked, or skipped honestly when needed.
• Keep .agent/status.json aligned with the latest known state.

Live Task Board During Execution

Live task board = execution visibility during the task.

Final report = completion summary after final verification.

Do not confuse the two.

• After creating the task plan, display the full ordered task list once before implementation begins.
• During execution, do not only mention the current task. Keep the full task list visible in progress updates.
• The live task board should be placed at the end of progress updates so it remains close to the user's input area.
• When producing a progress update, the live task board should be the last visible section of that update whenever practical. This keeps the full task list close to the user's input area and makes progress easy to scan.
• The live task board should show every task in order, not only the task being worked on.
• Each task row should include: task number, task title, and current status.
• Always show summary counts below the task list.
• Summary counts must include: remaining tasks, done tasks, verified tasks, failed tasks, and blocked tasks.
• Keep the live task board compact. Do not include long implementation details inside the board.
• Use short task titles in the board. Put detailed notes in .agent/task-plan.json, .agent/status.json, or progress notes.
• Update the board after meaningful progress, especially when a task changes status.
• If output would become too long, show a compact board with shortened task titles, but still include all task IDs.
• Do not replace final verification with this board. The board is for live progress visibility only.
• The live task board must be generated from the current task plan state. Do not invent a separate progress list that can drift from .agent/task-plan.json.

For Chinese prompts, use this full board format:

## 实时任务进度

| # | 任务 | 状态 |
|---|---|---|
| 1 | 整理需求并生成任务计划 | 🔵 已验收 |
| 2 | 修复首页课程入口 | 🟡 进行中 |
| 3 | 修复移动端返回按钮 | ⚪ 待处理 |
| 4 | 运行构建检查 | ⚪ 待处理 |

当前剩余任务：2 个
已完成：1 个
已验收：1 个
失败：0 个
阻塞：0 个

Chinese compact format:

## 实时任务进度

1. 🔵 T01 整理需求并生成任务计划
2. ✅ T02 修复首页课程入口
3. 🟡 T03 修复移动端返回按钮
4. ⚪ T04 运行构建检查

剩余：2｜完成：1｜已验收：1｜失败：0｜阻塞：0

For English prompts, use this full board format:

## Live Task Progress

| # | Task | Status |
|---|---|---|
| 1 | Refine requirements and create task plan | 🔵 Verified |
| 2 | Fix homepage course entry points | 🟡 In Progress |
| 3 | Fix mobile back button behavior | ⚪ Pending |
| 4 | Run build verification | ⚪ Pending |

Remaining tasks: 2
Done: 1
Verified: 1
Failed: 0
Blocked: 0

English compact format:

## Live Task Progress

1. 🔵 T01 Refine requirements and create task plan
2. ✅ T02 Fix homepage course entry points
3. 🟡 T03 Fix mobile back button behavior
4. ⚪ T04 Run build verification

Remaining: 2 | Done: 1 | Verified: 1 | Failed: 0 | Blocked: 0

Failure and Blocker Behavior

When a task fails:

• Diagnose the likely cause.
• Try reasonable safe recovery methods within scope.
• Avoid infinite retries.
• Avoid unrelated large rewrites unless necessary.
• Record what was tried.
• If unresolved, mark failed and provide a recovery path.

When a task is blocked:

• Mark blocked immediately.
• Explain the blocker.
• State what information, dependency, permission, API key, design decision, or user input is needed.
• Continue with other independent tasks when possible.

Final Verification Rules

Final verification is an audit pass, not a second full execution pass.

During final verification, review the task list, changed files, test/build results, acceptance criteria, and visible outcomes.

Do not redo every task from the beginning.

Only perform targeted fixes when verification finds a specific missing, incomplete, or broken item.

Final verification must be reflected in the final report. The final report should show verified completion status, not just implementation status.

Final User-Facing Report Format

The final user-facing response must be concise and scannable.

• Use the same language as the user's prompt by default.
• For Chinese prompts, use Chinese section titles and Chinese status labels.
• For English prompts, use English section titles and English status labels.
• If the user requests bilingual output, include both Chinese and English.
• Always include a task status table.
• The table should include at least: number, task title, status.
• Prefer 🔵 已验收 / Verified for tasks that passed final verification.
• Use ✅ 已完成 / Done only when implementation is complete but final verification has not passed yet.
• Use 🔴 失败 / Failed, 🟠 阻塞 / Blocked, or 🟣 已跳过 / Skipped when relevant.
• Do not hide failed, blocked, skipped, pending, or unverified tasks.
• If all required tasks are verified, the report may state that the long task is complete.
• If any required task is not verified, the report must clearly state that the task is not fully complete.
• The final report should summarize key changes, not dump every implementation detail.
• The final report should mention verification performed.
• The final report should include recommended local checks when the user may need to verify UI, device behavior, build output, runtime behavior, deployment, or account-specific behavior.
• Use only relevant sections. Omit empty failed, blocked, skipped, remaining-risk, or local-check sections when there is nothing useful to say.

Chinese report skeleton:

## 最终报告

| # | 任务 | 状态 |
|---|---|---|
| 1 | `<任务标题>` | 🔵 已验收 |

## 关键改动

- `<关键改动摘要>`

## 验收情况

- `<已执行的验收>`
- 最终验收是完成情况检查，不是从头重新执行所有任务。

## 建议本地重点检查

- `<建议用户本地重点检查的内容>`

English report skeleton:

## Final Report

| # | Task | Status |
|---|---|---|
| 1 | `<task title>` | 🔵 Verified |

## Key Changes

- `<key change summary>`

## Verification Performed

- `<verification performed>`
- Final verification is an audit pass, not a full re-execution of every task.

## Recommended Local Checks

- `<recommended local check>`

Handoff Guidance

Generate .agent/handoff.md when:

• The task is too long for one pass.
• The run is interrupted.
• Context is getting too long.
• A blocker prevents completion.
• Work cannot be fully completed safely.

The handoff must include current state, completed items, unfinished items, failed items, blocked items, files changed, next recommended action, and a continuation prompt.

Final Response Rules

The final response must follow the Final User-Facing Report Format. It must include:

• A final report title.
• A task status table.
• Key changes.
• Completed and verified tasks.
• Failed tasks, if any.
• Blocked tasks, if any.
• Skipped tasks, if any.
• Files changed.
• Verification performed.
• Remaining risks.
• Next recommended actions.
• Recommended local checks when useful.

If all required tasks are verified, the agent may say:

All required tasks have been completed and verified.

If not all required tasks are verified, the agent must say:

The task is not fully complete yet. The following items remain failed, blocked, pending, or unverified.

Never overclaim.