skilld
All skills
softaworks avatar

/session-handoff

@1c0662a
by softaworkssoftaworks/agent-toolkit2.5k stars
230

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/softaworks/agent-toolkit/session-handoff

This session only. Nothing lands on disk.

evalsresults-opus-baseline.md

≈676 tokens on demand. Your agent reads this file only when SKILL.md points to it.

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:

    python /Users/galihcitta/.claude/skills/session-handoff/evals/setup_test_env.py

  2. Start Claude Code with desired model:

    claude --model haiku  # or sonnet

  3. Navigate to test project:

    cd /tmp/handoff-eval-project

  4. Run scenarios from test-scenarios.md

  5. Record results using this template

Source: SKILL.md on GitHub

Third-party checks

1 warning17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The Session Handoff skill manages markdown documents to preserve context between AI agent sessions. It uses Python scripts to collect project metadata via Git and validate document quality. Analysis identified that the skill executes local shell commands (Git) and ingests external project metadata, such as commit messages, which presents a surface for indirect prompt injection.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer7mo

    4/12 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 1c0662a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Dormantupdated 9 months ago

Topics

  • session-handoff
  • context-management
  • agent-continuity
  • memory-preservation
  • long-running-tasks
  • workflow-persistence
  • handoff-documentation
  • state-capture

README badge

README badge for softaworks/agent-toolkit/session-handoff

What it does

Generates handoff documents that preserve project state, context, and pending work so fresh AI agents can resume without ambiguity. Addresses long-running sessions where context windows fill up by capturing current state, decisions made, critical files, and immediate next steps in a chainable format.

Generated from the current SKILL.md.

Frequently asked

When should I create a handoff?
Create a handoff when the user requests to save state, pause work, or says context is getting full. Also proactively suggest one after substantial work like 5+ file edits, complex debugging, or major architecture decisions.
Can I chain handoffs together for long-running projects?
Yes. Use the `--continues-from` flag when creating a new handoff to link it to a previous one, creating a context chain that new agents can follow.
What does the validation script check for?
The validator checks for remaining TODO placeholders, required sections, potential secrets (API keys, passwords, tokens), file existence, and generates a quality score. Do not finalize a handoff with detected secrets or a score below 70.
How do I know if a handoff is still usable when resuming?
Run the staleness checker, which assesses based on time elapsed, git commits, file changes, branch divergence, and missing files. It returns FRESH, SLIGHTLY_STALE, STALE, or VERY_STALE status.
Where are handoffs stored?
Handoffs are stored in `.claude/handoffs/` with timestamped filenames like `2024-01-15-143022-implementing-auth.md`.

Generated from the current SKILL.md. These answers refresh after source changes.