Skip to content

softaworks/agent-toolkit / skills/session-handoff

session-handoff

Verified

Creates 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.

FileKindSize
README.mdmarkdown6.9 KB
SKILL.mdskill md6.2 KB
evals/model-expectations.mdmarkdown5.6 KB
evals/results-opus-baseline.mdmarkdown2.6 KB
evals/setup_test_env.pyexecutablescript10.1 KB
evals/test-scenarios.mdmarkdown5.2 KB
references/handoff-template.mdmarkdown3.9 KB
references/resume-checklist.mdmarkdown2.7 KB
scripts/check_staleness.pyexecutablescript12.7 KB
scripts/create_handoff.pyexecutablescript10.4 KB
scripts/list_handoffs.pyexecutablescript3.7 KB
scripts/validate_handoff.pyexecutablescript10.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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall