Manage multi-session development work with structured progress files, checkpoint commits, and durable learnings. Produces SESSION.md files that survive context compaction and enable clean handoff between sessions.
Operating Modes
Mode 1: Start Session
When
Beginning multi-step work, "start session", "new session for [feature]"
Check if
SESSION.md
already exists in the project root
If yes: read it and ask whether to
continue
the existing session or
start fresh
If no: create from template (see
references/session-template.md
)
Pre-fill fields:
Project
from CLAUDE.md or directory name
Branch
from
git branch --show-current
Last Updated
current timestamp
Phase
ask user what they're working on
Read the project's CLAUDE.md to orient on context
Present a brief summary: "Session started. Working on [phase] on branch [branch]."
Mode 2: Checkpoint
When
"checkpoint", major milestone reached, before risky changes, context getting large
Update SESSION.md:
Add completed items to
What Works
Update
Current Position
with exact location (file paths, line numbers)
Clear resolved
Blockers
, add new ones
Write concrete
Resume Instructions
Capture learnings:
If any patterns, gotchas, or commands were discovered during work, add them to CLAUDE.md
One line per concept — concise, not verbose
Git checkpoint:
git
add
-A
&&
git
commit
-m
"WIP: [what was accomplished]"
Record the commit hash in SESSION.md under
Checkpoint
Confirm: "Checkpointed at [hash]. SESSION.md updated."
Mode 3: Resume Session
When
"resume", "continue from last session", "where were we", start of a new conversation
Read
SESSION.md
— if missing, inform user and offer to start a new session
Read the project's
CLAUDE.md
for context
Check what's changed since the recorded checkpoint:
git
log
--oneline
[
checkpoint-hash
]
..
HEAD
Check for uncommitted changes:
git status
Present a summary:
Phase
what we were working on
Position
where we left off
Changes since
any commits or modifications since checkpoint
Blockers
anything unresolved
Suggested next step
first item from Resume Instructions
Mode 4: Wrap Session
When
"wrap session", "done for now", "save progress", ending a session
Run a full checkpoint (Mode 2)
Review SESSION.md for completeness:
Are Resume Instructions concrete enough for a fresh session to continue?
Is Current Position specific (file paths, not vague descriptions)?
If the phase is complete:
Collapse the phase summary to 2-3 lines
Clear Resume Instructions or note "Phase complete — ready for next phase"
Confirm: "Session wrapped. Resume with 'resume session' next time."
When to Use
Scenario
Use this skill?
Multi-phase feature spanning 2+ sessions
Yes
Work that might hit context compaction
Yes
Before making risky or destructive changes
Yes (checkpoint first)
Quick bug fix or single-file edit
No
Single-session task with clear scope
No
SESSION.md Principles
Track progress, not architecture
— SESSION.md is a work log, not project documentation
Creating new SESSION.md, committing WIP checkpoints
Ask first
Overwriting an existing SESSION.md, deleting session data
Reference Files
When
Read
Creating a new SESSION.md
references/session-template.md
Context compaction tips, what survives
references/compaction-survival.md