session-handoff_skill

Overview

This skill creates comprehensive handoff documents so fresh AI agents can resume work with zero ambiguity. It triggers on explicit user requests (save state, create handoff, pause), when context nears capacity, after major milestones, or proactively after substantial progress. The goal is to preserve actionable state, decisions, and next steps so sessions can continue smoothly.

How this skill works

When creating a handoff, the skill scaffolds a timestamped markdown file with project metadata, recent commits, modified files, and placeholders for Current State, Important Context, Immediate Next Steps, and Decisions Made. A validation step checks completeness, quality, and for secrets before finalizing. When resuming, it lists available handoffs, checks staleness against git and file changes, loads the document, verifies assumptions and environment, and directs the agent to the first immediate next step.

When to use it

• User asks to save state, says 'save state', 'create handoff', or 'I need to pause'.
• Context window is approaching capacity or multiple large edits have occurred.
• After completing a major milestone, complex debugging, or architectural decision.
• Proactively suggested after significant work (multiple file edits, big refactor).
• When resuming work later with 'load handoff', 'resume from', or 'continue where we left off'.

Best practices

• Fill all TODO placeholders before finalizing; do not finalize if secrets are detected.
• Capture clear, actionable first steps and name specific files/functions to edit.
• Record decisions with rationale, not just outcomes, to prevent ambiguity.
• Chain handoffs for long-running efforts using a --continues-from link to preserve lineage.
• Run staleness checks before resuming; prefer a fresh handoff if status is VERY_STALE.

Example use cases

• Mid-day pause during feature work: scaffold a handoff so another agent can continue tomorrow.
• Context window near capacity during a long debugging session: save state to avoid losing key info.
• After refactor and key decisions: record rationale and immediate test or verification steps.
• Handing work between different agent instances or models without losing thread of reasoning.
• Resuming a multi-day task: list and validate handoffs, then pick the first Immediate Next Step to continue.