session-handoff

A handoff-document generator for transferring work between AI coding sessions. The document records the project state so another session can continue with less repeated explanation.

In plain words
What is it for?
Use it when pausing work, saving progress, reaching a major milestone, or resuming from an earlier handoff.
Why use it?
Long tasks can outgrow a session’s available context, making important decisions and unfinished work easy to lose. A handoff preserves that information for later continuation.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/softaworks/agent-toolkit/session-handoff
Any agent
npx skills add softaworks/agent-toolkit --skill session-handoff
Clone the repo
git clone --depth 1 https://github.com/softaworks/agent-toolkit

Made for: Claude Code, Codex.

Per session 140 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,470 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00140 $0.01470
Opus 5 $0.00070 $0.00735
Sonnet 5 $0.00028 $0.00294
Haiku 4.5 $0.00014 $0.00147

Measured 2d ago against content hash 8964e1b84617, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

session-handoff scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

The scan reads SKILL.md. This mod also ships 5 executable files (evals/setup_test_env.py, scripts/check_staleness.py, scripts/create_handoff.py, …), listed below but not scanned — reading those needs a real analyzer, not pattern matching.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

skills/session-handoff/SKILL.md · 190 lines

How it starts

The opening of the file, as written. The whole thing — 190 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Handoff

Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.

Mode Selection

Determine which mode applies:

Creating a handoff? User wants to save current state, pause work, or context is getting full.

  • Follow: CREATE Workflow below

Resuming from a handoff? User wants to continue previous work, load context, or mentions an existing handoff.

  • Follow: RESUME Workflow below

Proactive suggestion? After substantial work (5+ file edits, complex debugging, major decisions), suggest:

"We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."

CREATE Workflow

Step 1: Generate Scaffold

Run the smart scaffold script to create a pre-filled handoff document:

python scripts/create_handoff.py [task-slug]

Example: python scripts/create_handoff.py implementing-user-auth

For continuation handoffs (linking to previous work):

python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md

The script will:

  • Create .claude/handoffs/ directory if needed
  • Generate timestamped filename
  • Pre-fill: timestamp, project path, git branch, recent commits, modified files
  • Add handoff chain links if continuing from previous
  • Output file path for editing

Step 2: Complete the Handoff Document

Open the generated file and fill in all [TODO: ...] sections. Prioritize these sections:

  1. Current State Summary - What's happening right now
  2. Important Context - Critical info the next agent MUST know
  3. Immediate Next Steps - Clear, actionable first steps
  4. Decisions Made - Choices with rationale (not just outcomes)

Use the template structure in references/handoff-template.md for guidance.

Step 3: Validate the Handoff

Run the validation script to check completeness and security:

Read the full file on GitHub · 190 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 190 lines · 140 tokens per session scan A 8964e1b84617

Subscribe to this mod's changes

session-handoff is a skill published in the GitHub repository softaworks/agent-toolkit (2,413 stars, last pushed 6mo ago), licensed MIT. It adds 140 tokens to every session and 1,470 once invoked, about $0.0007 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.