# Handoff > Write a structured session handoff before ending, clearing context, or transferring work to another agent or pane. - Skill: `wolverin0/handoff` (Agent Skill) - Install (CLI): `npx skillmds add wolverin0/handoff` - Raw SKILL.md: https://api.skillmd.com/api/skills/wolverin0/handoff/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: wolverin0 (https://skillmd.com/u/wolverin0) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/wolverin0/handoff --- # /handoff - Intelligent Session Handoff Write a comprehensive, structured handoff document so the NEXT session (or a clean restart of THIS session after /clear) can pick up with ZERO context loss on what matters. **Output file**: `handoffs/handoff--.md` relative to your current working directory. Create the `handoffs/` directory if it doesn't exist. **NEVER overwrite** an existing handoff file - always generate a unique filename. **If `$ARGUMENTS` is provided**, treat it as a focus instruction (e.g., "focus on the auth refactor, skip the test debugging"). Prioritize that area in your handoff. ## Timing contract (evolve 2026-08-23 — evidence: 2 failed runs were post-compact) - **Write the handoff BEFORE degradation, not at the cliff.** If context usage is at or past ~70%, the handoff comes BEFORE the next task — a handoff written from a compacted summary is a copy of a copy. Enforcement is deterministic, not prose: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75` fires compaction early, and the `precompact-handoff-gate` hook BLOCKS the first auto-compact of a session demanding this skill run first (it also snapshots the raw transcript to `~/.claude/compact-snapshots/`). - **If this session already compacted** (you see a "continued from a previous conversation" summary at the top): mark the handoff header with `> DEGRADADO: escrito post-compact, desde resumen — verificar contra el transcript snapshot y el repo antes de confiar en detalles.` ## Mandatory Sections Fill ALL of these. If a section is genuinely empty, write "None" - do NOT skip the heading. ### 1. `## Context` What was this session about- One paragraph, high-level. Include: - The project name and what it does (1 sentence) - What task/feature/bug you were working on - Who requested it and why (if known) ### 2. `## Current State` Concrete, verifiable state of the codebase RIGHT NOW: - Files modified (list paths, not just "some files") - Commits made in this session (short SHAs + messages) - Uncommitted changes: yes/no (run `git status --short` if unsure) - Build status: passing/failing (run the build if unsure) - Tests: passing/failing/not-run - Dev server: running on port X / not running - Any processes you started that are still alive ### 3. `## Open Threads` Work that is IN PROGRESS but NOT yet reflected in committed files: - Partially implemented features (what's done, what's not) - Debugging hypotheses you were testing - Decisions you were mid-way through making - Things you told the user you'd do but haven't started **This is the most critical section.** The next session won't know about these unless you write them down. Be specific - "I was refactoring X" is useless; "I extracted function Y from file Z into module W, the import in Z is updated but 3 callers in A, B, C still reference the old location" is useful. ### 4. `## Next Steps` Exactly what to do FIRST in the new session, ordered by priority: 1. Step 1 (most urgent / blocking) 2. Step 2 3. Step 3 - Include the exact commands to run if applicable - Include file paths to read first ### 5. `## Constraints & Gotchas` Anything learned during this session that shouldn't be re-discovered: - Approaches that FAILED and why (so the next session doesn't retry them) - Non-obvious requirements or edge cases found - Environment quirks (Windows-specific, port conflicts, etc.) - Rate limits, API quotas, or timing issues encountered ### 6. `## Relevant Files` Absolute paths to the files the next session should read FIRST: ``` /full/path/to/critical-file-1.ts /full/path/to/critical-file-2.cjs ``` Don't make the next session grep - give it the exact paths. ### 7. `## Corr ID` If a correlation ID was provided (e.g., `corr=handoff-abc123`), include it here for tracking. If none was provided, generate one: `handoff-` + 6 random alphanumeric characters. ### 8. `## Suggested Skills & Setup` What the NEXT session should invoke or load first (evolve 2026-08-23, idea from mattpocock/skills): - Skills that apply to the pending work (e.g., `/orchestrate` if it's the orchestrator pane, `/project-health` if scaffolding drifted, the project's own domain skills) - MCP servers or tools it will need that aren't obvious - The ONE file to read first if it reads nothing else ## Rules 1. **NEVER include credentials, API keys, tokens, private IPs, or personal filesystem paths** (like `C:\Users\username\...`) in the handoff file. Use relative paths or `$HOME`-based references. 2. **Be concrete, not abstract.** "Made progress on the feature" is USELESS. "Added `parseStatusBar()` to `src/status-parser.cjs`, imported in `pane-discovery.cjs:12`, exposed `ctx` field in `collectPanes()` at `dashboard-server.cjs:85`" is USEFUL. 3. **Verify before writing.** Run `git status`, check the build, check if your dev server is alive. Don't guess - report facts. 4. **The handoff file IS the contract.** The next session will read ONLY this file to understand what happened. If it's not in the file, it didn't happen. 5. **After writing the file, STOP.** Do not continue with other work. The handoff file is the last action of this session. 6. **Link, don't duplicate** (evolve 2026-08-23): if a spec, plan, ADR, brief, artifact, or commit already documents something, reference its path — never re-narrate its content into the handoff. The handoff carries what exists NOWHERE else (open threads, failed attempts, in-flight decisions); everything else is a pointer.