Session Handoff

WHAT: Create comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves long-running agent context exhaustion problem. WHEN: (1) User requests handoff/memory/context save, (2) Context window approaches capacity, (3) Major task milestone completed, (4) Work session ending, (5) Resuming work with existing handoff. KEYWORDS: "save state", "create handoff", "context is full", "I need to pause", "resume from", "continue where we left off", "load handoff", "save progress", "session transfer", "hand off"

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose of creating, validating, listing, and resuming 'handoff' documents; it operates on local files and git state and does not request unrelated credentials or external endpoints.

Purpose & Capability

Name/description (session handoff) match the included scripts and docs. The scripts create, validate, list, and check staleness of handoff markdown files in .claude/handoffs/, and they use git metadata — all expected for this purpose.

Instruction Scope

SKILL.md directs the agent to run the bundled Python scripts and to open/edit the generated files; scripts only inspect local repo state and files and check for secrets. Minor scope notes: quick-start commands in the resume checklist include commands like `env | grep [relevant-var]` and `ps aux | grep [process-name]` which can reveal environment variable values or process details if run verbatim — these are reasonable for debugging but operators should be careful about running them in environments where secrets or sensitive processes are present.

Install Mechanism

There is no formal install spec in the skill bundle (instruction-only at runtime), which minimizes automatic install risk. README includes manual install instructions and an `npx add https://github.com/...` example pointing to an external repo; that is an out-of-band install suggestion (not executed by the skill) — users should vet any external repo URL before running install commands.

Credentials

The skill requires no environment variables, credentials, or special config paths. Scripts operate on local filesystem and git; secret-detection is built into validation. No unrelated credentials are requested in code or SKILL.md.

Persistence & Privilege

Skill does not request always:true, does not modify other skills, and only writes its own files under .claude/handoffs/ in the project. It uses subprocess git calls but does not attempt to persist credentials or alter global agent settings.

Assessment

This skill appears to do what it says: scaffold, validate, list, and evaluate 'handoff' markdown files using local git and filesystem checks. Before installing or running it: (1) Review the scripts yourself (they live in scripts/) if you have sensitive projects — they will create files under .claude/handoffs/ and run git commands in the project directory. (2) Be cautious running the example shell commands (env | grep, ps aux | grep) on machines with secrets; they can expose environment values or process information. (3) The README suggests installing from a GitHub URL — only run external install commands after reviewing/validating the remote repo. (4) The validator looks for likely secrets with regexes but can yield false positives/negatives, so manually verify any flagged content before committing or sharing handoffs. Overall the footprint is local and proportional to the stated purpose.

Create handoff documents that enable fresh agents to continue work seamlessly.

Mode Selection

Creating a handoff? User wants to save state, pause work, or context is full. → Follow CREATE Workflow

Resuming from a handoff? User wants to continue previous work or load context. → Follow RESUME Workflow

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

"Consider creating a handoff document to preserve this context. Say 'create handoff' when ready."

---

CREATE Workflow

Step 1: Generate Scaffold

Run the smart scaffold script:

python scripts/create_handoff.py [task-slug]

For continuation handoffs (linking to previous work):

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

The script creates .claude/handoffs/ directory and generates a timestamped file with pre-filled metadata (timestamp, project path, git branch, recent commits, modified files).

Step 2: Complete the Document

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

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)

See references/handoff-template.md for full structure.

Step 3: Validate

python scripts/validate_handoff.py <handoff-file>

Checks:

• No [TODO: ...] placeholders remaining
• Required sections present and populated
• No potential secrets detected (API keys, passwords, tokens)
• Referenced files exist
• Quality score (0-100)

Do not finalize handoffs with secrets detected or score below 70.

Step 4: Confirm

Report to user:

• Handoff file location
• Validation score and warnings
• Summary of captured context
• First action item for next session

---

RESUME Workflow

Step 1: Find Handoffs

python scripts/list_handoffs.py

Step 2: Check Staleness

python scripts/check_staleness.py <handoff-file>

Staleness levels:

• FRESH: Safe to resume
• SLIGHTLY_STALE: Review changes first
• STALE: Verify context carefully
• VERY_STALE: Consider creating fresh handoff

Step 3: Load and Verify

Read the handoff document completely. If part of a chain, also read the previous handoff.

Follow references/resume-checklist.md:

1. Verify project directory and git branch match
2. Check if blockers resolved
3. Validate assumptions still hold
4. Review modified files for conflicts

Step 4: Begin Work

Start with "Immediate Next Steps" item #1.

Reference as you work:

• "Critical Files" for important locations
• "Key Patterns Discovered" for conventions
• "Potential Gotchas" to avoid known issues

---

Handoff Chaining

For long-running projects, chain handoffs to maintain context lineage:

handoff-1.md (initial work)
    ↓
handoff-2.md --continues-from handoff-1.md
    ↓
handoff-3.md --continues-from handoff-2.md

When resuming from a chain, read the most recent handoff first, then reference predecessors as needed.

---

Storage

Location: .claude/handoffs/ Naming: YYYY-MM-DD-HHMMSS-[slug].md

---

Quality Criteria

Good handoffs have:

• Zero ambiguity about current state
• Clear, numbered next steps
• Rationale for decisions (not just outcomes)
• File paths with line numbers where relevant
• No secrets or credentials

---

NEVER

• Include API keys, passwords, tokens, or credentials
• Leave TODO placeholders in finalized handoffs
• Skip the validation step
• Create handoffs without the Important Context section
• Finalize handoffs with quality score below 70