playbooks

home / skills / vaayne / agent-kit / handoff

handoff skill

/skills/handoff

This skill generates a concise handoff prompt to preserve context when starting a new focused session.

npx playbooks add skill vaayne/agent-kit --skill handoff

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

Files (1)
SKILL.md
2.0 KB
---
name: handoff
description: Transfer context to a new focused session. Use when starting a new phase of work, handing off to a new session, or when context needs to be summarized for continuation. Triggers on "handoff", "transfer context", "start new session with context", or when the user wants to continue work in a fresh session.
---

# Handoff

Generate a session summary and write it to `handoff.md` so a new session can pick up where this one left off.

## Workflow

1. **Analyze the current session** — gather goals, progress, decisions, file changes, blockers, and next steps.
2. **Write `handoff.md`** — save the summary to `handoff.md` in the project root (overwrite if exists).
3. **Guide the user** — tell the user to start a new session with: `read handoff.md and continue the work`.

## Handoff File Template

Write `handoff.md` using this structure:

```markdown
# Handoff

## Goal

[Original objective of this session]

## Progress

- [What was completed]
- [What was partially done]

## Key Decisions

- [Decision 1 and why]
- [Decision 2 and why]

## Files Changed

- `path/to/file1` — [what changed]
- `path/to/file2` — [what changed]

## Current State

[Where things stand right now — what works, what doesn't]

## Blockers / Gotchas

- [Any issues, edge cases, or warnings for the next session]

## Next Steps

1. [Concrete next action]
2. [Follow-up action]
```

## Guidelines

- **Be self-contained** — the new session must understand the full picture without the old conversation.
- **Be concise** — include only what's relevant; skip empty sections.
- **Focus on decisions and rationale** — what was decided and why, not the full discussion.
- **List concrete files with context** — path + what changed, not just paths.
- **State next steps as actionable tasks** — clear enough to execute immediately.

## After Writing

Confirm the file was written and instruct the user:

> `handoff.md` has been saved. To continue in a new session, start with:
>
> ```
> read handoff.md and continue the work
> ```

Overview

This skill generates a concise handoff prompt to transfer conversation context into a new, focused session. It summarizes key decisions, involved files, and the next task so a fresh session can continue work without losing context. Use it to start new phases, hand off to another engineer, or preserve progress before switching threads.

How this skill works

When invoked, the skill scans the current conversation for important findings, decisions, and files referenced or modified. It then builds a self-contained prompt that lists key decisions, files involved, and a clear task description based on the user's handoff goal. The output is a ready-to-copy prompt you can paste into a new session or edit before sharing.

When to use it

  • You're starting a new session but need to preserve important context or decisions.
  • You want to hand off work to another engineer or agent with a clear summary.
  • You need a succinct summary of what was done and what should happen next.
  • You say commands like 'handoff', 'transfer context', or 'start new session with context'.
  • You are moving from planning to execution or between phases of a multi-step plan.

Best practices

  • Keep the task description specific and actionable so the next session can proceed without questions.
  • Include only relevant files and decisions; avoid copying entire transcripts.
  • Call out any gotchas, edge cases, or assumptions that affect implementation.
  • Reference the exact phase or ticket when handing off multi-phase plans.
  • Edit the generated prompt to add missing links, refs, or test instructions before starting the new session.

Example use cases

  • Handoff form validation work: summarize choices (zod, inline errors, hook used) and ask to implement the same pattern for another page.
  • Transfer a code review state: list files changed, reviewer notes, and tasks remaining for fixups.
  • Move from design to implementation: summarize accepted design decisions and provide the first development task.
  • Split a large task into phases: hand off phase two with context about what was completed in phase one.
  • Share context with another agent: produce a self-contained prompt that a new agent can use to continue work.

FAQ

How detailed should the context be?

Be concise: include key decisions, files, and any blockers or assumptions needed to continue. Avoid full transcripts.

Can I edit the generated prompt before starting the new session?

Yes—edit to add links, tests, or additional instructions. The prompt is intended to be copyable and editable.

What if no files were changed?

List the logical artifacts or endpoints discussed and describe the next task; a file list can be empty or note 'no files modified'.