agent-handoff

name

agent-handoff

description

Create continuation-oriented handoff/progress artifacts for another AI agent to safely resume complex work, including an operational handoff md plus a compact-session-style conversation context md. Use when the user asks to summarize current progress for a future/next/other agent, write an Agent README, update a project handoff, preserve recent conversation/history, record experiment state, preserve cluster/run/debug context, or document what has changed, what is running, known risks, exact next steps, and recent user instructions. Do not use for polished human-facing status reports unless the user explicitly asks for both audiences.

Agent Handoff

Overview

Use this skill to write handoff artifacts optimized for a future AI agent, not for a human audience. The goal is operational continuity: another agent should be able to open the artifacts, understand the current state, recover the key conversation context, avoid damaging running work, and continue with minimal rediscovery.

For a full reusable structure, read references/handoff-template.md when creating or substantially updating an operational handoff document. Read references/conversation-context-template.md when the handoff should preserve recent dialogue and compressed earlier history.

Output Pair

When the user asks for a future-agent handoff and does not request a single file only, produce two linked Markdown artifacts:

1. Operational handoff: current state, paths, services, code changes, risks, verification, and next steps.
2. Conversation context: a compact-session-like artifact with compressed earlier history plus the most recent user/assistant exchanges as fully as the current context allows.

Keep the operational handoff actionable and compact. Put conversation reconstruction in the conversation context file so the next agent can recover intent without bloating the operational document.

Core Workflow

1. Identify the receiver: a future AI agent. Prioritize exact state, paths, commands, constraints, and unresolved risks over narrative polish.
2. Reconstruct the task history from local docs, code, logs, scripts, and recent outputs. Prefer source artifacts over memory.
3. Decide the artifact set and paths. For substantial handoffs, create both the operational handoff and conversation context files, and cross-link them.
4. Separate current state from historical attempts. Make clear what is running now, what failed before, and what conclusions are still hypotheses.
5. Record operational hazards before instructions: live services, GPUs/nodes to avoid, long-running jobs, files not to overwrite, and destructive commands to avoid.
6. Include exact absolute paths for repos, scripts, logs, checkpoints, datasets, docs, and config files.
7. Include code changes with filenames and purpose. Distinguish user/Copilot/previous-agent changes when known.
8. Include verification status: what passed, what failed, what was not tested, and how to re-check without reading huge logs.
9. End with actionable next steps and copy-pastable monitoring/resume commands when useful.
10. In the conversation context artifact, preserve exact recent user instructions and assistant actions when available; compress earlier context and explicitly mark gaps.

What To Gather

Collect these facts before writing:

• Current goal and requirement changes, with dates if known.
• Active repo, branch/status, and key entry scripts.
• Environment topology: nodes, containers, GPUs, ports, services, shared storage, network limits.
• Data/model locations and sizes/counts when relevant.
• Running or stale processes: training, inference servers, retrievers, dashboards, W&B/TensorBoard.
• Latest logs/checkpoints/artifacts and how to inspect them safely.
• Known failures and root-cause status: confirmed, likely, ruled out, or unknown.
• Current hyperparameters and how they differ from defaults or previous runs.
• Next safe actions, fallback paths, and stop conditions.

Writing Rules

• Write for execution, not persuasion.
• Use headings that a future agent can scan quickly.
• Prefer tables or compact bullets for paths, services, and commands.
• Use absolute paths for local files.
• Mark uncertainty explicitly: confirmed, likely, unknown, needs verification.
• Do not paste large logs. Summarize key lines and give tail/rg commands for reinspection.
• Do not hide failed attempts. Future agents need to know what was tried and why it failed.
• Avoid vague phrases like "configured the environment"; name the exact node, container, path, package, and command.
• Do not fabricate missing conversation turns. Distinguish verbatim, summarized, and inferred.
• Redact secrets and API keys by default; note that redaction occurred when it affects reproducibility.

Recommended Structure

If the user does not specify a format, use this order:

1. Current Objective
2. TL;DR Current State
3. System / Cluster Map
4. Important Paths
5. Running Services and Jobs
6. Code Changes Made
7. Data, Models, Checkpoints, Logs
8. Experiments and Results
9. Known Issues and Root Causes
10. Safe Operating Instructions
11. Next Steps
12. Appendix: Useful Commands

Load references/handoff-template.md for a more detailed operational skeleton. Load references/conversation-context-template.md for the paired compact-session-style artifact.

Quality Bar

Before finalizing, check that a fresh agent can answer:

• What is the current objective?
• What should not be killed, overwritten, or rerun blindly?
• Which command or file should be opened first?
• What is the newest successful artifact?
• What failed most recently and why?
• What is the next safe action?
• Where is the paired conversation context, and what recent user instruction is newest?

If any answer is missing, add it before reporting completion.