softaworks/agent-toolkit / skills/session-handoff
session-handoff
VerifiedCreates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity, (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 6.9 KB |
| SKILL.md | skill md | 6.2 KB |
| evals/model-expectations.md | markdown | 5.6 KB |
| evals/results-opus-baseline.md | markdown | 2.6 KB |
| evals/setup_test_env.pyexecutable | script | 10.1 KB |
| evals/test-scenarios.md | markdown | 5.2 KB |
| references/handoff-template.md | markdown | 3.9 KB |
| references/resume-checklist.md | markdown | 2.7 KB |
| scripts/check_staleness.pyexecutable | script | 12.7 KB |
| scripts/create_handoff.pyexecutable | script | 10.4 KB |
| scripts/list_handoffs.pyexecutable | script | 3.7 KB |
| scripts/validate_handoff.pyexecutable | script | 10.6 KB |
scripts/list_handoffs.py
View on GitHub#!/usr/bin/env python3
"""
List available handoff documents in the current project.
Searches for handoff documents in .claude/handoffs/ and displays:
- Filename with date
- Title extracted from document
- Status (if marked complete)
Usage:
python list_handoffs.py # List handoffs in current project
python list_handoffs.py /path # List handoffs in specified path
"""
import os
import re
import sys
from datetime import datetime
from pathlib import Path
def extract_title(filepath: Path) -> str:
"""Extract the title from a handoff document."""
try:
content = filepath.read_text()
# Look for first H1 header
match = re.search(r'^#\s+(?:Handoff:\s*)?(.+)$', content, re.MULTILINE)
if match:
title = match.group(1).strip()
# Clean up placeholder text
if title.startswith("[") and title.endswith("]"):
return "[Untitled - needs completion]"
return title[:50] + "..." if len(title) > 50 else title
except Exception:
pass
return "[Unable to read title]"
def check_completion_status(filepath: Path) -> str:
"""Check if handoff appears complete or has TODOs remaining."""
try:
content = filepath.read_text()
todo_count = content.count("[TODO:")
if todo_count == 0:
return "Complete"
elif todo_count <= 3:
return f"In Progress ({todo_count} TODOs)"
else:
return f"Needs Work ({todo_count} TODOs)"
except Exception:
return "Unknown"
def parse_date_from_filename(filename: str) -> datetime | None:
"""Extract date from filename like 2024-01-15-143022-slug.md"""
match = re.match(r'(\d{4}-\d{2}-\d{2})-(\d{6})', filename)
if match:
try:
date_str = match.group(1)
time_str = match.group(2)
return datetime.strptime(f"{date_str} {time_str}", "%Y-%m-%d %H%M%S")
except ValueError:
pass
return None
def list_handoffs(project_path: str) -> list[dict]:
"""List all handoff documents in a project."""
handoffs_dir = Path(project_path) / ".claude" / "handoffs"
if not handoffs_dir.exists():
return []
handoffs = []
for filepath in handoffs_dir.glob("*.md"):
parsed_date = parse_date_from_filename(filepath.name)
handoffs.append({
"path": str(filepath),
"filename": filepath.name,
"title": extract_title(filepath),
"status": check_completion_status(filepath),
"date": parsed_date,
"size": filepath.stat().st_size,
})
# Sort by date, most recent first
handoffs.sort(key=lambda x: x["date"] or datetime.min, reverse=True)
return handoffs
def format_date(dt: datetime | None) -> str:
"""Format datetime for display."""
if dt is None:
return "Unknown date"
return dt.strftime("%Y-%m-%d %H:%M")
def main():
# Get project path
project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
handoffs = list_handoffs(project_path)
if not handoffs:
print(f"No handoffs found in {project_path}/.claude/handoffs/")
print("\nTo create a handoff, run: python create_handoff.py [task-slug]")
return
print(f"Found {len(handoffs)} handoff(s) in {project_path}/.claude/handoffs/\n")
print("-" * 80)
for h in handoffs:
print(f" Date: {format_date(h['date'])}")
print(f" Title: {h['title']}")
print(f" Status: {h['status']}")
print(f" File: {h['filename']}")
print("-" * 80)
print(f"\nTo resume from a handoff, read the document and follow the resume checklist.")
print(f"Most recent: {handoffs[0]['path']}")
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |