| 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:
- Review the current conversation and task requirements.
- Inspect relevant source files.
- Run
git status --short when the project uses Git.
- Inspect relevant diffs when available.
- Record commands, tests, outputs, and errors that materially affect the task.
- Separate confirmed facts from assumptions.
- 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:
- Read this entire file.
- Inspect
git status --short.
- Verify that referenced files still exist.
- Compare the current repository state with this handoff.
- Report any mismatch before modifying code.
- Continue from the first unfinished item under
Next Actions.
- 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
