context-handoff

name

context-handoff

description

Automatically triggers when the context window approaches ~80% capacity during any coding or task session in VS Code. Generates a structured handoff file (.md) summarizing all ongoing work, decisions made, files changed, and blockers — plus a ready-to-paste "continuation prompt" for a fresh session. Use this skill whenever the user says phrases like "context is filling up", "we're running out of context", "context window warning", "save progress", "handoff", "start a new session", "continue in new chat", or whenever you sense the conversation is too long to continue safely. Also trigger proactively when you notice the conversation has become very long and complex. Never let a session end without a handoff when significant work-in-progress exists.

Context Handoff Skill

When the context window is ~80% full (or the user requests a handoff), your job is to capture everything a fresh Claude session needs to continue without asking questions.

---

Step 1 — Take Stock

Before writing anything, scan the full conversation and collect:

Category	What to capture
Goal	The original task / feature / bug the user is working on
Progress	What has been completed, what is partially done
Files changed	Paths + a one-line summary of each change
Decisions made	Key technical choices and the reasons behind them
Current blocker / next step	The exact thing the user was about to do next
Environment	Language, framework, key deps, any env vars mentioned
Pending questions	Things left unresolved that the new session needs to decide

If the user mentioned their project name, repo path, or codebase layout, include it.

---

Step 2 — Write the Handoff File

Save to the project root (or current working directory) as:

CLAUDE_HANDOFF_<YYYYMMDD_HHMM>.md

Use this exact template:

# Claude Handoff — <date/time>

## 🎯 Mission
<1-3 sentence summary of the overall goal>

## ✅ Completed
- <item>
- <item>

## 🔄 In Progress
- <item — include which file/function is partially modified>

## 📁 Files Modified
| File | Change summary |
|------|----------------|
| `path/to/file.ext` | <what changed and why> |

## 🧠 Key Decisions Made
- **<decision>**: <rationale>

## ⚙️ Environment
- Language/Runtime: 
- Framework: 
- Key dependencies: 
- Relevant env vars: 

## 🚧 Blockers & Open Questions
- <anything unresolved>

## ▶️ Next Step
<The single most important thing to do next, written as a clear action>

---
*Generated by context-handoff skill. Paste the continuation prompt below into a new Claude session.*

---

Step 3 — Generate the Continuation Prompt

After the handoff file, output a fenced block the user can copy-paste directly into a new Claude session:

---COPY THIS INTO YOUR NEW CLAUDE SESSION---

You are continuing work on an ongoing coding task. Read the handoff context below carefully before doing anything.

**Project:** <name or path>
**Last session ended:** <date/time>

### Mission
<same as handoff file — 1-3 sentences>

### What's done
<bullet list>

### What's in progress
<bullet list with file names>

### Files modified so far
<table from handoff>

### Key decisions already made (don't re-litigate these)
<bullet list>

### Environment
<language, framework, deps>

### Open questions
<list>

### Your first task
<exact next step>

Please confirm you've read this, then ask me if you need any clarification before proceeding. Do not start writing code yet — confirm first.
---END OF HANDOFF---
```

---

Step 4 — Tell the User

After generating both:

1. State clearly what file was saved and where.
2. Show the continuation prompt inline (so they can copy it without opening the file).
3. Say: "Paste that prompt at the start of your new Claude session. The new session will pick up exactly where we left off."

---

Tone & Length Guidelines

• Handoff file: thorough and precise — err on the side of including more detail. A future Claude has zero memory.
• Continuation prompt: tight and scannable — the new Claude should be able to read it in 30 seconds and know exactly what to do.
• Don't summarize the conversation — synthesize it. Pull out decisions and state, not chat history.

---

Edge Cases

Situation	What to do
Early in session, not much done	Still generate handoff; mark most sections as "N/A — session just started"
User asks for handoff mid-task	Generate it immediately, don't wait for 80%
Multiple unrelated tasks in session	Create separate "In Progress" sections per task
User says "just give me the prompt"	Skip the file, only output the continuation prompt block
No file system access (e.g. chat-only)	Output the full handoff as a markdown code block for the user to save manually