Skill: session-handoff

Fork

Context transfer between AI sessions. Trigger when the user wants to save the context, resume a task, or hand off the work to another session.

Configuration

Property	Value
Context	fork
Allowed tools	Read, Write, Edit, Glob, Grep
Keywords	session, handoff

Detailed description

Session Handoff

Objective

Save and transfer the context of a work session to enable efficient resumption in a later session or by another agent.

When to use

• End of a work session (save the state)
• Task too complex for a single session
• Handoff between developers/agents
• Documentation of work in progress

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]
- [x] [Task 2] - [Detail]

### In progress
- [ ] [Task 3] - [Current state, where it stands]
  - Modified files: [list]
  - Next step: [description]
  - Possible blocker: [description]

### To do
- [ ] [Task 4] - [Description]
- [ ] [Task 5] - [Description]

## Decisions made

| Decision | Reason | Rejected alternative |
|----------|--------|---------------------|
| [Choice 1] | [Why] | [Other option] |
| [Choice 2] | [Why] | [Other option] |

## Key files

| File | Role | State |
|---------|------|------|
| `src/xxx.ts` | [Description] | Modified / Created / To modify |
| `tests/xxx.test.ts` | [Description] | Modified / Created / To create |

## Patterns and conventions discovered

- [Pattern 1 from the codebase]
- [Naming convention]
- [Specific architecture]

## Problems encountered

| Problem | Solution/Workaround | Resolved? |
|----------|---------------------|----------|
| [Problem 1] | [Solution] | Yes/No |
| [Problem 2] | [Workaround] | Partial |

## 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]

## Handoff workflow

### Save the context (end of session)

1. SUMMARIZE the work done
2. LIST the modified files (git diff --stat)
3. DOCUMENT the decisions made and why
4. IDENTIFY the remaining tasks and their priority
5. NOTE the unresolved problems
6. WRITE the .claude/handoff.md file

### Resume the context (start of session)

1. READ the .claude/handoff.md file
2. CHECK the repo state (git status, git log)
3. RUN the tests to confirm the state
4. IDENTIFY the next task to perform
5. CONTINUE the work

## Best practices

- Write the handoff DURING the work, not after
- Be specific about files and lines of code
- Include commands to check the state
- Document the decisions AND the reasons
- Mention the pitfalls and workarounds discovered

## Rules

- ALWAYS create a handoff before ending a complex work session
- ALWAYS include the modified files and their state
- ALWAYS document the architectural decisions
- NEVER assume the next session will have the same context

## Automatic triggering

This skill is automatically activated when:
- The matching keywords are detected in the conversation
- The task context matches the skill's domain

### Triggering examples

- _"I want to session..."_
- _"I want to handoff..."_

## Context fork


**Fork** means the skill runs in an isolated context:
- Does not pollute the main conversation
- Results are returned cleanly
- Ideal for autonomous tasks


---

## See also

- [Back to skills](/docs/skills)
- [Architecture](/docs/intro/architecture)