session-handoff

name	session-handoff
description	Save and restore the current role, task state, decisions, progress, blockers, and next steps across Cursor or Claude Code sessions and model switches. Use when the user asks to save context, hand off work, wrap up, resume previous work, or continue from another session.
disable-model-invocation	true

Session Handoff

This skill preserves explicit project and task context across Agent sessions, model switches, and context-window resets.

The canonical state file is:

.cursor/state/HANDOFF.md

Never claim that hidden reasoning or the model's complete internal context has been preserved. Preserve only explicit, verifiable information.

Supported Modes

Determine the mode from the user's request:

• save: Save the current context.
• resume: Restore and verify the previous context.
• update: Update the handoff after additional work.
• status: Show a concise summary without modifying files.

Save or Update Workflow

Before writing the handoff:

1. Review the current conversation and task requirements.
2. Inspect relevant source files.
3. Run git status --short when the project uses Git.
4. Inspect relevant diffs when available.
5. Record commands, tests, outputs, and errors that materially affect the task.
6. Separate confirmed facts from assumptions.
7. Do not store passwords, tokens, private keys, API keys, or other secrets.

Create or replace .cursor/state/HANDOFF.md using this structure:

Session Handoff

Last Updated

• Timestamp:
• Project:
• Branch:
• Working directory:

Agent Role

Describe the role the Agent is expected to perform, including:

• Domain expertise
• Communication style
• Required level of detail
• Whether complete files or code fragments are expected
• Important user preferences

Primary Objective

State the current task in one precise paragraph.

Acceptance Criteria

List the conditions that must be satisfied before the task is complete.

Current State

Describe what currently exists and the present implementation state.

Completed Work

List only work that has actually been completed and verified.

For each item include:

• What changed
• Relevant files
• Verification performed
• Result

Decisions and Rationale

Record important decisions in the form:

• Decision:
• Reason:
• Alternatives rejected:
• Consequences:

Files and Components

List relevant files and their roles.

Use exact repository-relative paths.

Commands and Test Results

Record:

• Commands executed
• Important output
• Tests passed
• Tests failed
• Environment or tool versions when relevant

Do not paste large logs. Summarize them and reference saved log files where available.

Current Problems and Blockers

For each blocker include:

• Observable symptom
• Confirmed cause or current hypothesis
• Evidence
• Attempts already made
• Result of each attempt

Open Questions

List unresolved questions that require user input, external information, or further investigation.

Next Actions

Provide an ordered list of concrete next actions.

Each action should state:

• Exact file or component
• Intended modification
• Verification method
• Expected result

The first action must be immediately executable by a new Agent session.

Constraints and Do-Not-Repeat Notes

Record:

• User constraints
• Compatibility requirements
• Approaches that failed
• Files that must not be modified
• Actions that should not be repeated

Resume Instructions

When resuming:

1. Read this entire file.
2. Inspect git status --short.
3. Verify that referenced files still exist.
4. Compare the current repository state with this handoff.
5. Report any mismatch before modifying code.
6. Continue from the first unfinished item under Next Actions.
7. Do not redo completed work unless verification shows it is invalid.

Resume Prompt

Write a compact prompt that can be pasted into a new Agent session. It must include:

• Role
• Objective
• Current state
• Main constraints
• First next action
• Instruction to read this file