session-handoff

Session Handoff

English | 简体中文

Save and restore agent role, task state, decisions, progress, blockers, and next steps across Cursor sessions, Claude Code sessions, or model switches.

Why Session Handoff

Long agent tasks lose context when you:

• Start a new chat
• Switch models (fast ↔ capable)
• Hit context-window limits
• Move between Cursor and Claude Code

Session Handoff writes a structured, verifiable snapshot to .cursor/state/HANDOFF.md so the next session can continue from documented facts instead of guessing.

It does not claim to preserve hidden reasoning or full chat history.

Features

Mode	Description
save	Create or replace the handoff file from current work
resume	Read handoff, verify repo state, continue from next actions
update	Refresh handoff after new progress
status	Summarize handoff without modifying files

Quick start

Cursor

1. Install to .cursor/skills/session-handoff/SKILL.md — see CURSOR.md

2. Before ending a session:

   /session-handoff save context
   

3. In a new session:

   /session-handoff resume
   

Claude Code

1. Install the plugin — see CLAUDE.md

2. Save:

   /session-handoff:session-handoff save current context
   

3. Resume:

   /session-handoff:session-handoff resume from HANDOFF.md
   

Installation

Method	Cursor	Claude Code
Project skill	.cursor/skills/session-handoff/SKILL.md	.claude/skills/session-handoff/
Personal skill	~/.cursor/skills/session-handoff/SKILL.md	~/.claude/skills/session-handoff/
Plugin	—	.claude-plugin/plugin.json

Detailed steps:

• CURSOR.md — Cursor installation and usage
• CLAUDE.md — Claude Code installation and usage

Clone and link (development)

git clone <repo-url> session-handoff-skill
cd session-handoff-skill

Cursor — project install:

mkdir -p .cursor/skills
ln -sf "$(pwd)/skills/session-handoff" .cursor/skills/session-handoff

Cursor — personal install:

mkdir -p ~/.cursor/skills
ln -sf "$(pwd)/skills/session-handoff" ~/.cursor/skills/session-handoff

Claude Code plugin test:

claude --plugin-dir "$(pwd)"

Repository layout

session-handoff-skill/
├── .cursor/
│   └── skills/
│       └── session-handoff/
│           └── SKILL.md     # → skills/session-handoff/SKILL.md
├── .claude-plugin/
│   ├── plugin.json          # Claude Code plugin manifest
│   └── marketplace.json     # Marketplace metadata (optional publish)
├── skills/
│   └── session-handoff/
│       └── SKILL.md         # Canonical skill source
├── CURSOR.md                # Cursor usage guide
├── CLAUDE.md                # Claude Code usage guide
├── EXAMPLES.md              # Prompt and handoff examples
├── README.md
└── README.zh.md

Handoff file

Path: .cursor/state/HANDOFF.md (in your project, not in this repo)

The file includes sections for role, objective, acceptance criteria, completed work, decisions, files, commands/tests, blockers, open questions, next actions, constraints, and a paste-ready resume prompt.

See EXAMPLES.md for a minimal example.

Cross-client workflow

The same handoff file works in Cursor and Claude Code:

1. Save in either client
2. Commit .cursor/state/HANDOFF.md (optional)
3. Resume in the other client

Security

Never store passwords, tokens, private keys, or API keys in the handoff file. Summarize errors and logs; do not paste large secret-bearing output.

Documentation

Document	Description
CURSOR.md	Cursor-specific setup and commands
CLAUDE.md	Claude Code-specific setup and commands
EXAMPLES.md	Sample prompts and handoff templates
skills/session-handoff/SKILL.md	Full skill specification

License

MIT