# session-handoff

> Create consistent session handoff documents for context transfer between sessions. Use when closing a session, reaching 75% token consumption, or when user requests handoff. Ensures proper YAML headers for metrics collection, LF line endings, and complete documentation of progress, decisions, and next steps.

- Author: Ashay Kubal
- Repository: ashaykubal/essential-agents-skills
- Version: 20260209215901
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-10
- Source: https://github.com/ashaykubal/essential-agents-skills
- Web: https://mule.run/skillshub/@@ashaykubal/essential-agents-skills~session-handoff:20260209215901

---

---
name: session-handoff
description: Create consistent session handoff documents for context transfer between sessions. Use when closing a session, reaching 75% token consumption, or when user requests handoff. Ensures proper YAML headers for metrics collection, LF line endings, and complete documentation of progress, decisions, and next steps.
user-invocable: true
---

# Session Handoff

Create handoff documents that enable seamless context transfer between sessions.

## Critical Requirements

### Line Endings

Use LF (Unix) line endings only. Never CRLF.
- Use the Write tool directly (handles line endings correctly)
- Never copy-paste from Windows clipboard
- If you see `^M` characters, rewrite the file

### File Naming

**Pattern**: `sessions/session_{N}_{YYYYMMDD}.md`

- `{N}`: Session number (integer, no leading zeros)
- `{YYYYMMDD}`: Date without separators

Examples: `session_5_20260104.md` (correct), `session_05_20260104.md` (wrong)

## Handoff Template

````markdown
# Session {N} Handoff

```yaml
session: {N}
date: {YYYY-MM-DD}
phase: "P{X} - {Phase Name}"
task: "P{X}.{Y} - {Task Name}"
status: {completed | in_progress | blocked}
tokens_end: "~{X}K ({Y}%)"
```

---

## Session Summary

{2-3 sentences on outcomes, not process. What was achieved?}

## What Was Accomplished

- [x] {Completed item with file path}
- [x] {Completed item with file path}
- [ ] {Incomplete item - carried forward}

## Files Created/Modified

| File | Action | Lines | Purpose |
|------|--------|-------|---------|
| {path} | Created | ~{N} | {Brief description} |
| {path} | Modified | +{N}/-{M} | {What changed} |

## Verification Status

| Check | Status | Notes |
|-------|--------|-------|
| Typecheck | {Pass/Fail/Skipped} | |
| Lint | {Pass/Fail/Skipped} | |
| Tests | {Pass/Fail/Skipped} | {X/Y if applicable} |

## Technical Decisions

### {Decision Title}
- **Decision**: {What was decided}
- **Rationale**: {Why}
- **Impact**: {What it affects}

## What's Next

1. {Specific actionable step}
2. {Next step}

## Blockers / Issues

{List blockers or "None"}

## Learnings

{Patterns discovered or "None"}
````

## Section Guidelines

### YAML Header (Required)

The YAML header enables metrics collection. All fields required:

| Field | Format | Example |
|-------|--------|---------|
| session | Integer | `session: 5` |
| date | YYYY-MM-DD | `date: 2026-01-04` |
| phase | Quoted string | `phase: "P1 - Foundation"` |
| task | Quoted string | `task: "P1.2 - Test Auditor"` |
| status | Enum | `status: completed` |
| tokens_end | Quoted string | `tokens_end: "~95K (48%)"` |

### Session Summary

Focus on **outcomes** not process. What was delivered?

Good: "Completed session-handoff skill with CRLF handling. Ready for use."
Bad: "I started by reading files, then thought about structure, then wrote..."

### What Was Accomplished

- Use `[x]` for complete, `[ ]` for incomplete
- Include file paths
- Be specific

### Technical Decisions

Document decisions that affect future work. Include rationale so future sessions understand WHY. Skip if no significant decisions.

### Blockers / Learnings

Always include these sections. Write "None" if empty - don't omit.

## Quick Checklist

Before finalizing:

- [ ] File named `session_{N}_{YYYYMMDD}.md`
- [ ] YAML header complete and valid
- [ ] All sections present (even if "None")
- [ ] Next steps are specific and actionable
- [ ] No CRLF line endings

## Examples

For detailed examples of completed and in-progress handoffs, see [references/examples.md](references/examples.md).