home / skills / ykdojo / claude-code-tips / handoff

handoff skill

safe

This skill helps you generate or update a HANDOFF.md in the project root to capture goals, progress, and next steps for continuity.

npx playbooks add skill ykdojo/claude-code-tips --skill handoff

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

812 B

---
name: handoff
description: Write or update a handoff document so the next agent with fresh context can continue this work.
---

Write or update a handoff document so the next agent with fresh context can continue this work.

Steps:
1. Check if HANDOFF.md already exists in the project
2. If it exists, read it first to understand prior context before updating
3. Create or update the document with:
   - **Goal**: What we're trying to accomplish
   - **Current Progress**: What's been done so far
   - **What Worked**: Approaches that succeeded
   - **What Didn't Work**: Approaches that failed (so they're not repeated)
   - **Next Steps**: Clear action items for continuing

Save as HANDOFF.md in the project root and tell the user the file path so they can start a fresh conversation with just that path.

Overview

This skill creates or updates a HANDOFF.md so the next agent can pick up work with minimal friction. It ensures the file lives at the project root (HANDOFF.md) and captures goal, progress, lessons, and clear next steps. Use it whenever you want to hand over an ongoing task to a fresh agent or human reviewer.

How this skill works

The skill checks for an existing HANDOFF.md and, if present, reads it to preserve prior context. It then composes or updates the document with five concise sections: Goal, Current Progress, What Worked, What Didn't Work, and Next Steps, and saves the file to the project root as HANDOFF.md. Finally, it reports the file path so the next agent can begin using just that path.

When to use it

When pausing work and needing a clean restart point for a different agent
Before handing a task to another developer or automation pipeline
After debugging or experimenting so failures and wins are recorded
When multiple agents collaborate sequentially on a project
To create an onboarding snapshot for a new contributor

Best practices

Be concise: each section should be a few focused bullet points or short paragraphs
Prefer actionable next steps with owners and estimated effort when possible
Record both successful and failed approaches to avoid repeating work
Keep the Goal statement explicit and time-boxed (what, why, target state)
Update HANDOFF.md every time you reach a logical stopping point

Example use cases

You implemented half of a feature and need an agent to finish integration and tests
An experiment failed; capture the configurations tried and the failure mode for the next attempt
Switching from a human developer to an automated CI agent to continue builds
Wrapping up a debugging session so a new agent can reproduce and resolve remaining issues
Handing off repository-wide tips and environment quirks for smoother onboarding

FAQ

Where is the handoff file saved?

It is saved at the project root as HANDOFF.md; provide that path to the next agent to start.

Should I include logs or large files in HANDOFF.md?

No. Summarize relevant logs and link to artifacts or file paths instead of embedding large content.