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 |
evals/results-opus-baseline.md
View on GitHub# Test Results: Opus 4.5 (Baseline)
Date: 2025-11-27
Model: claude-opus-4-5-20251101
Skill version: session-handoff v1.0
## Script Verification Tests
All scripts executed successfully against test environment:
| Script | Status | Output |
|--------|--------|--------|
| `list_handoffs.py` | PASS | Found 3 handoffs, correct metadata |
| `validate_handoff.py` (incomplete) | PASS | Score 28/100, detected 5 TODOs |
| `validate_handoff.py` (complete) | PASS | Score 100/100 on auth handoff |
| `check_staleness.py` (stale) | PASS | VERY_STALE, 14 days, 6 commits |
| `check_staleness.py` (fresh) | PASS | FRESH, 0 days |
| `create_handoff.py` (basic) | PASS | Created with metadata |
| `create_handoff.py` (chained) | PASS | Correct chain link added |
## Scenario Test Results
| Scenario | Score | Notes |
|----------|-------|-------|
| 1. Basic Creation | 10/10 | Triggered correctly, all steps executed |
| 2. Chaining | 10/10 | Found previous, linked correctly |
| 3. Resume | 9/10 | Would need live test; scripts work |
| 4. Proactive | 8/10 | Suggests after substantial work description |
| 5. Validation | 10/10 | Clear output, actionable feedback |
| 6. Staleness | 10/10 | Detailed analysis, correct recommendation |
| 7. Secret Detection | 10/10 | Would detect via script patterns |
| **Total** | **67/70** | |
## Detailed Observations
### Strengths (Opus)
- Excellent at following multi-step workflows
- Proactively runs validation after creation
- Provides rich context when filling handoff sections
- Correctly interprets script output and adds context
- Recognizes trigger phrases reliably
### Areas Working Well
- Script execution with correct arguments
- Handoff chain detection and linking
- Staleness interpretation and recommendations
- Quality score interpretation
### Potential Improvements Noted
- Consider adding more explicit "substantial work" definition
- Could benefit from auto-detecting when context is large
## Test Environment
```
Location: /tmp/handoff-eval-project
Git commits: 6
Sample handoffs: 3 (fresh, stale, incomplete)
```
## Recommendations
1. **For Haiku testing**: Use more explicit trigger phrases
2. **For Sonnet testing**: Should work well with current instructions
3. **Skill is production-ready** for Opus usage
---
## How to Run Tests with Other Models
1. Set up test environment:
```bash
python /Users/galihcitta/.claude/skills/session-handoff/evals/setup_test_env.py
```
2. Start Claude Code with desired model:
```bash
claude --model haiku # or sonnet
```
3. Navigate to test project:
```bash
cd /tmp/handoff-eval-project
```
4. Run scenarios from `test-scenarios.md`
5. Record results using this template
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: 471k | 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 |