christopherlouet Session Handoff
Objective
Produce a git-committable handoff document (.claude/handoff.md) that transfers a work session's state to a different reader: another developer, another agent, another LLM, or a future session on another machine.
Native features first
Claude Code natively covers resuming your own session — do not rebuild that here:
| Need | Native answer |
|---|---|
| Resume my own session | claude --resume <id> (full context) |
Recap after a break or /compact |
/recap |
| Persistent preferences/decisions across sessions | auto memory (~/.claude/memory/) |
This skill's delta is the cross-boundary case: native memory and --resume are personal and machine-local — they do not transfer to a teammate, a CI agent, another tool, or another workstation. A committed handoff.md does.
When to use
- Handoff between developers/agents/tools (the reader is NOT this session's owner)
- Work continuing on another machine or in an environment without your
~/.claude - Documentation of work in progress that must live IN the repo
Handoff format
Context file: .claude/handoff.md
# Session Handoff
**Date:** [YYYY-MM-DD HH:MM]
**Session:** [ID or description]
**Author:** [Human or agent]
## Project context
**Project:** [Name]
**Branch:** [Branch name]
**Current commit:** [Hash]
## Work state
### Done
- [x] [Task 1] - [Detail]
### In progress
- [ ] [Task 3] - [Current state, where it stands]
- Modified files: [list]
- Next step: [description]
- Possible blocker: [description]
### To do
- [ ] [Task 4] - [Description]
## Decisions made
| Decision | Reason | Rejected alternative |
|----------|--------|---------------------|
| [Choice 1] | [Why] | [Other option] |
## Key files
| File | Role | State |
|---------|------|------|
| `src/xxx.ts` | [Description] | Modified / Created / To modify |
## Patterns and conventions discovered
- [Pattern 1 from the codebase]
## Problems encountered
| Problem | Solution/Workaround | Resolved? |
|----------|---------------------|----------|
| [Problem 1] | [Solution] | Yes/No |
## Notes for the next session
[Specific instructions, pitfalls to avoid, points of attention]
## Useful commands
```bash
# To resume
git checkout [branch]
npm test # Check that everything passes
# Next step: [description]
## Best practices
- Write the handoff DURING the work, not after
- Be specific about files and lines of code
- Document the decisions AND the reasons
- Mention the pitfalls and workarounds discovered
- NEVER assume the reader has this session's context, memory, or machine
## Rules
- ALWAYS create a handoff before handing work across a person/agent/machine boundary
- ALWAYS include the modified files and their state
- ALWAYS document the architectural decisions
- For resuming YOUR OWN session, prefer the native features above — no handoff file needed