Session Start Handoff

Session Start — Handoff Reader

This skill activates automatically at the start of every Claude Code session. Its job is to detect a HANDOFF.md, extract the essential context, and present it in a compact brief before the user says anything — so the session starts oriented, not cold.

Trigger Conditions

Activate when ALL of the following are true:

• A new Claude Code session has just started in a project directory
• HANDOFF.md exists in the project root
• The user has not said "start fresh", "ignore handoff", or "new project"

Do NOT activate:

• Mid-session
• If the user explicitly opts out
• If the handoff is empty or obviously malformed

---

Step 1 — Detect and Check the Handoff

# Check existence and age
if [ -f HANDOFF.md ]; then
  stat -f "%Sm %N" -t "%Y-%m-%dT%H:%M:%S" HANDOFF.md 2>/dev/null \
    || stat --format="%y %n" HANDOFF.md 2>/dev/null \
    || ls -la HANDOFF.md
fi

Calculate age from the modification time or the Generated: timestamp in the file:

• Under 24 hours — present without comment on age
• 1–7 days — present with a note: (from N days ago)
• Over 7 days — present with a staleness warning and ask if it's still relevant before loading

---

Step 2 — Read and Parse the Handoff

Read the file:

cat HANDOFF.md

Extract these fields:

• Goal (from ## Goal)
• Status and Progress (from ## Current State)
• Branch (from ## Branch & Commits)
• Files in Flight (from ## Files in Flight table)
• Key Decisions (from ## Key Decisions)
• Open Questions (from ## Open Questions)
• Next Step (from ## Next Step)
• Failed Attempts (from ## Failed Attempts — keep in memory but don't display unless relevant)

---

Step 3 — Present the Session Brief

Show a compact, scannable brief. Do not recite the entire file — distill it:

Continuing from your last session[, N days ago].

Goal: [one-line goal]

Status: [status] — [progress %]
Branch: [branch name]

Files in flight:
  • [file] — [short note]
  • [file] — [short note]

Key decisions made:
  • [Decision: one line]

Open questions:
  • [Question]

Next step: [Specific next action]

Ready to continue? (yes / no / tell me what you want to do instead)

Keep the entire brief under 20 lines. If there's a lot of context, summarize rather than repeat verbatim.

---

Step 4 — Wait for User Confirmation

Wait for the user to respond before taking any action.

• "yes" (or "y", "sure", "continue", "go ahead") — proceed with the Next Step as described in the handoff
• "no" (or "start fresh", "something else") — acknowledge, ask what they'd like to do instead; do not discard the handoff context from memory
• A specific instruction — follow it directly; keep handoff context in memory for reference

---

Step 5 — Carry Context Through the Session

Once the handoff is loaded, it stays active:

• Reference it when making decisions: if a new approach conflicts with a documented Key Decision, note the conflict
• Reference Failed Attempts before suggesting an approach that was already tried
• Remind the user to run /handoff at natural stopping points (end of a feature, before switching context, before ending the session)

---

Handling Edge Cases

Stale handoff (over 7 days)

Found a handoff from [date] ([N] days ago).

The work was: [Goal]

Is this still the active task? (yes / no)

If no: offer to archive it and start fresh.

Malformed or empty handoff

Found HANDOFF.md but it appears incomplete.

Would you like to:
1. Start fresh (ignore it)
2. Show me the file so I can salvage it

Multiple HANDOFF files

ls -t HANDOFF*.md 2>/dev/null | head -5

Keep only the newest. Move others to handoff-archive/:

mkdir -p handoff-archive
ls -t HANDOFF*.md | tail -n +2 | xargs -I{} mv {} handoff-archive/ 2>/dev/null || true

No HANDOFF.md

Start the session normally. At a natural pause point, mention:

Tip: run /handoff before ending this session to save your progress for next time.

Only show this tip once per session.

---

Notes

• Read the file exactly once at session start. Do not re-read on every message.
• Never hallucinate handoff content. If a section is missing, note it as absent rather than filling it in.
• Do not auto-commit or modify HANDOFF.md. That is the user's (and /handoff's) job.
• Staleness check: prefer the Generated: timestamp in the file over the file modification time (the file may have been copied or synced).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: thatcatfromspace
• Source: thatcatfromspace/claude-handoff-skill
• License: MIT

Install and usage instructions live in the source repository linked above.