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 |
README.md
View on GitHub# 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:**
```bash
python scripts/create_handoff.py implementing-user-auth
```
**Continuation handoff (linked to previous):**
```bash
python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md
```
**Validate before finalizing:**
```bash
python scripts/validate_handoff.py .claude/handoffs/2024-01-15-143022-implementing-auth.md
```
### Resuming from a Handoff
**List available handoffs:**
```bash
python scripts/list_handoffs.py
```
**Check if handoff is current:**
```bash
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](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
- [handoff-template.md](references/handoff-template.md) - Complete template structure with guidance
- [resume-checklist.md](references/resume-checklist.md) - Verification checklist for resuming agents
- [evals/model-expectations.md](evals/model-expectations.md) - Model behavior expectations
- [evals/test-scenarios.md](evals/test-scenarios.md) - Test cases for handoff creation and resumption
## 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
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: 470k | Updated | Claude CodeCodex | Verified | 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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |