SKILL.md
v1.0.0 · 1890 B · text/markdown
--- name: session-handoff description: Use before a context reset, session end, or when passing work to a fresh agent - compresses current state into a markdown doc detailed enough to resume from cold --- # Session Handoff A context reset or a fresh agent picking up mid-task loses everything that isn't written down. This skill produces one markdown document that lets work resume without re-deriving decisions already made. ## What to capture 1. **Task, one paragraph.** What is being built/fixed and why, in plain language — not a link to a ticket, an actual restatement. 2. **State right now.** What's done, what's in progress, what's untouched. Be specific: "auth middleware written and tested; route wiring not started" beats "mostly done." 3. **Key decisions and why.** Any point where more than one approach was possible and one was chosen — name the alternative and the reason it was rejected. This is the part that's genuinely expensive to re-derive. 4. **Files touched**, with a one-line note on what changed in each. 5. **Blockers and open questions.** Anything waiting on a human decision, an external system, or information not yet available. 6. **Next step**, singular and concrete — not a list of everything left, just what to do immediately upon resuming. 7. **Gotchas.** Anything a fresh agent would predictably get wrong or re-discover the hard way (a flaky test, a misleading file name, an undocumented constraint). ## Format Plain markdown, headed sections matching the list above. Optimize for a reader with zero session memory — write as if briefing a competent colleague who is walking in cold, not as a note to yourself. ## When to write one Proactively before a context window fills up, always before intentionally ending a session with work in progress, and any time work is being handed to a different agent or person.