Skip to content

README.md

Latest commit

 

History

History
195 lines (148 loc) · 6.87 KB

README.md

File metadata and controls

195 lines (148 loc) · 6.87 KB
Raw

Session Handoff Skill

Overview

The Session Handoff skill creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. It solves the long-running agent context exhaustion problem by preserving complete context, decisions, and state across sessions.

Purpose

When working on complex, multi-session projects with AI agents, context gets lost between sessions. This skill provides a structured approach to:

  • Preserve context - Capture all critical information before context window fills
  • Enable continuity - Allow new agents to pick up exactly where you left off
  • Document decisions - Record architectural choices and their rationale
  • Track progress - Maintain clear status of completed and pending work
  • Chain sessions - Link related handoffs for long-running projects

When to Use

User-Triggered

  • User says "save state", "create handoff", "I need to pause"
  • User requests "load handoff", "resume from", "continue where we left off"
  • User mentions "context is getting full" or "save this for later"

Agent-Triggered (Proactive)

  • Context window approaching capacity (>80% full)
  • Major task milestone completed
  • Work session ending with significant progress
  • After substantial work (5+ file edits, complex debugging, architecture decisions)
  • Before switching to a different task

Resumption Scenarios

  • Starting a new session on an existing project
  • Different agent needs to continue the work
  • Need to recall decisions made in previous sessions
  • Picking up after a long break

How It Works

The skill operates in two primary modes:

CREATE Mode

Generates a comprehensive handoff document capturing current state:

  1. Generate Scaffold - Smart script pre-fills metadata (timestamp, git status, modified files)
  2. Complete Document - Fill in critical sections (state, context, decisions, next steps)
  3. Validate - Automated checks for completeness, quality, and security
  4. Confirm - Present location and summary to user

RESUME Mode

Loads and validates existing handoff documents:

  1. Find Handoffs - List available handoffs in project
  2. Check Staleness - Assess if context is still current
  3. Load Document - Read handoff (and chain if linked)
  4. Verify Context - Validate assumptions and environment
  5. Begin Work - Start from "Immediate Next Steps"

Key Features

Smart Scaffolding

The create_handoff.py script automatically captures:

  • Timestamp and project path
  • Current git branch and recent commits
  • Modified and unstaged files
  • Handoff chain links (if continuing from previous)

Validation & Quality Assurance

The validate_handoff.py script checks:

  • No incomplete [TODO: ...] placeholders
  • All required sections populated
  • No potential secrets (API keys, passwords, tokens)
  • Referenced files exist
  • Quality score (0-100)

Staleness Detection

The check_staleness.py script assesses:

  • Time elapsed since handoff creation
  • Git commits made since handoff
  • Files changed since handoff
  • Branch divergence
  • Missing referenced files

Handoff Chaining

For long-running projects, chain handoffs together:

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

Each handoff links to its predecessor, providing context breadcrumbs for new agents.

Usage Examples

Creating a Handoff

Basic handoff creation:

python scripts/create_handoff.py implementing-user-auth

Continuation handoff (linked to previous):

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

Validate before finalizing:

python scripts/validate_handoff.py .claude/handoffs/2024-01-15-143022-implementing-auth.md

Resuming from a Handoff

List available handoffs:

python scripts/list_handoffs.py

Check if handoff is current:

python scripts/check_staleness.py .claude/handoffs/2024-01-15-143022-implementing-auth.md

Load and continue work:

  1. Read the handoff document completely
  2. Verify context using resume checklist
  3. Start with first item in "Immediate Next Steps"

Handoff Document Structure

A complete handoff includes:

  1. Metadata - Timestamp, project path, git branch, commits
  2. Current State Summary - What's happening right now
  3. Important Context - Critical information for next agent
  4. Decisions Made - Architectural choices with rationale
  5. Immediate Next Steps - Clear, actionable first steps
  6. Pending Work - Remaining tasks and priorities
  7. Critical Files - Important locations and their purpose
  8. Key Patterns Discovered - Conventions and approaches
  9. Potential Gotchas - Known issues and workarounds
  10. Handoff Chain - Links to previous/next handoffs

See references/handoff-template.md for the complete template.

Storage Location

Handoffs are stored in: .claude/handoffs/

Naming convention: YYYY-MM-DD-HHMMSS-[slug].md

Example: 2024-01-15-143022-implementing-auth.md

Scripts Reference

Script Purpose Usage
create_handoff.py Generate new handoff with smart scaffolding python scripts/create_handoff.py [slug] [--continues-from <file>]
list_handoffs.py List available handoffs in a project python scripts/list_handoffs.py [path]
validate_handoff.py Check completeness, quality, and security python scripts/validate_handoff.py <file>
check_staleness.py Assess if handoff context is still current python scripts/check_staleness.py <file>

Quality Standards

Do not finalize a handoff if:

  • Validation score is below 70
  • Secrets are detected
  • [TODO: ...] placeholders remain
  • Required sections are empty

Best practices:

  • Write clear, specific next steps (not vague goals)
  • Document the "why" behind decisions, not just the "what"
  • Include code snippets for critical patterns
  • Reference specific file paths and line numbers
  • Update handoffs as work progresses

References

Benefits

  • Zero ambiguity - New agents know exactly what to do
  • Context preservation - No loss of critical information
  • Decision history - Understand why choices were made
  • Reduced onboarding - Faster agent startup on existing work
  • Quality assurance - Automated validation prevents incomplete handoffs
  • Security - Secret detection prevents credential leaks
  • Long-term memory - Handoff chains maintain project history