A Claude Code skill that remembers your work session so your teammates don't have to.
Picture this: you're building a project with your friends. You code for 3 hours. You switch from one API to another halfway through. You hit a weird bug and fix it with a workaround. You change the folder structure. Then you push to GitHub and go to sleep.
Next morning, your teammate pulls the code and opens Claude Code. Claude has no idea what happened yesterday. It reads the old docs, gets confused, starts suggesting things that don't work anymore, and burns 40,000 tokens just trying to figure out where things stand.
That's the problem. Claude Code has no memory between sessions. Every session starts from zero.
This skill fixes that. When you're done working, you type one command. Claude writes everything down in plain English — what changed, what broke, how you fixed it, what's left to do. Next session, anyone on your team reads that file and is fully caught up in 60 seconds. Claude Code reads it too and starts working immediately instead of exploring the codebase from scratch.
The result: ~90% fewer tokens wasted on orientation. Zero confusion. No repeated work.
WITHOUT session-handoff:
─────────────────────────────────────────────────────────────────
Session 1 ends → nothing written down
Session 2 starts → Claude reads 50 files to figure out the project
→ 40,000 tokens burned on orientation
→ "wait, which API are we using again?"
→ wrong assumptions about the codebase
→ broken suggestions
→ frustration 😤
WITH session-handoff:
─────────────────────────────────────────────────────────────────
Session 1 ends → /session-handoff
→ DECISIONS.md updated ✅ (what changed + why)
→ CONTEXT.md updated ✅ (current project status)
→ CLAUDE.md updated ✅ (tech stack + key facts)
→ git commit made ✅
Session 2 starts → /session-start
→ reads 3 small files (~2,000 tokens total)
→ "here's exactly where you left off"
→ "your next task is X"
→ starts coding immediately ✅
→ 95% fewer orientation tokens 🚀
Option A — One command (recommended):
curl -fsSL https://raw.githubusercontent.com/s9b/session-handoff/main/install.sh | bashOption B — Claude Code plugin marketplace:
/plugin marketplace add s9b/session-handoff
Option C — Manual (3 steps):
# 1. Copy the skills into your Claude skills folder
cp -r skill/session-handoff ~/.claude/skills/
cp -r skill/session-start ~/.claude/skills/
# 2. Copy the templates into your project
cp templates/DECISIONS.md ./
cp templates/CONTEXT.md ./
# 3. Commit them
git add DECISIONS.md CONTEXT.md
git commit -m "chore: add session-handoff knowledge files"When you're done working, just type this in Claude Code:
/session-handoff
That's it. Claude will:
- Look at everything that happened in the session (git diff, conversation history)
- Write a log entry to
DECISIONS.md— what changed, what broke, how it was fixed - Update
CLAUDE.mdif anything major changed (new API, new library, etc.) - Update
CONTEXT.mdwith current project status - Make a git commit with everything
The whole thing takes about 30 seconds.
At the start of any session, type:
/session-start
Claude reads your 3 knowledge files and tells you:
- What the project is
- What was done last session
- What's broken right now
- Exactly what to work on next
You go from zero to coding in under a minute, with 95% fewer tokens spent on orientation.
| File | What's in it | Updated when |
|---|---|---|
DECISIONS.md |
Full log of every session — changes, bugs, fixes, decisions | Every /session-handoff |
CONTEXT.md |
Current sprint status — what's done, what's next, what's broken | Every /session-handoff |
CLAUDE.md |
Project truth file — tech stack, APIs, folder structure | When something major changes |
STANDUP.md |
Daily standup snippet (Yesterday / Today / Blockers) | When you ask for it |
Here's a real entry from a hackathon project called StudyBuddy (a group study session planner). The team switched from Firebase to Supabase on day 2 after hitting Firebase's free tier limits:
## [2026-04-12] — Firebase → Supabase migration
**Team member:** Priya
**Status:** Done (but auth is flaky — see warnings)
### Task
Firebase free tier ran out mid-session. Hit the 50K daily read limit with just 3 people
testing. Migrate everything to Supabase before we can keep building.
### Changes made
| File / Module | What changed | Why |
|--------------|-------------|-----|
| src/auth/firebaseClient.js | Deleted entirely | Replaced with Supabase |
| src/auth/supabaseClient.js | Created — initializes Supabase client | New auth provider |
| src/hooks/useAuth.js | Rewrote from Firebase auth to Supabase auth | API is very different |
| .env | Replaced VITE_FIREBASE_* vars with VITE_SUPABASE_* | Config update |
| package.json | Removed firebase, added @supabase/supabase-js | Dependency swap |
### Problems & fixes
| Problem | Root cause | Fix applied |
|---------|-----------|-------------|
| Firebase free tier hit | 50K reads/day limit — our useEffect was re-fetching on every render | Moved to Supabase — unlimited reads on free tier |
| Auth broke after migration — "Cannot read properties of undefined (reading 'user')" | useAuth hook still checking firebase.auth().currentUser | Rewrote hook to use supabase.auth.getSession() |
| Row-level security blocked all reads | Supabase enables RLS by default — didn't know | Added policies: authenticated users can read/write their own rows |
### Decisions made
- Supabase over Firebase: unlimited free reads, built-in Postgres, RLS is more auditable
- Dropped old Firebase users — we're a hackathon, no real users yet, acceptable tradeoff
- All schema changes go in supabase/migrations/ as numbered SQL files. Never edit old files.
### Current state
Supabase working. Login, signup, session creation all work. Auth is slightly flaky —
sometimes the session doesn't persist after page refresh. Needs investigation next session.
### ⚠️ Don't demo the app until auth session persistence is fixed.
### Next steps
- [ ] Fix auth session persistence on page refresh — top priority
- [ ] Test auth with all three accounts
- [ ] Add study rooms featureSee examples/example-DECISIONS.md for the full 3-day story including a session expiry bug and how it was traced and fixed.
# CONTEXT.md — Current Status
> Last updated: 2026-04-13
## What are we building?
StudyBuddy — a web app where students create group study rooms and stay accountable together.
## Just completed
- Fixed session expiry bug (JWT was set to 1hr, now 7 days + auto-refresh)
- Shipped study rooms feature: create, join, live list updates
## Up next
- In-room countdown timer UI
- Basic chat (Supabase real-time messages)
- Landing page
## ⚠️ Gotchas — read before touching code
- Rooms auto-expire via Supabase cron job. Do NOT manually delete rooms.
- Supabase RLS is on for all tables. New tables need policies or reads fail silently.
- Do NOT edit old migration files — always create a new numbered one.**Date:** 2026-04-13 | **Project:** StudyBuddy
✅ Yesterday
- Fixed session expiry bug — JWT was defaulting to 1 hour, changed to 7 days + added auto-refresh
- Shipped study rooms: create a room, join rooms, live updates via Supabase real-time
🔨 Today
- Build in-room countdown timer UI
- Start on in-room chat (Supabase real-time)
- Stress test with 3 simultaneous users
🚧 Blockers
- None right now. Auth is stable, rooms are working.
📊 Overall status: On track🎓 Students & hackathon teams You and your friends are building something at 2am. You switch tasks, someone new joins, you change APIs three times. Without this, the next session is chaos — Claude doesn't know what changed and neither does your teammate. With session-handoff, anyone who joins the project can read one file and start contributing immediately. It's the difference between "wait, why did we do it this way?" and "okay, got it, let's go."
💼 Startups & small dev teams Your team commits code every day across multiple sessions and multiple people. DECISIONS.md becomes your project's memory — a searchable history of every decision ever made and why it was made. New hire joins? Tell them to read DECISIONS.md from bottom to top. They'll understand the entire history of the project in under an hour, with no hand-holding required.
🏢 Offices & enterprise teams Daily standups take 15 minutes because nobody remembers what they did yesterday. STANDUP.md writes itself. PR reviews are faster because reviewers can open DECISIONS.md and see the full context behind a change — not just the diff. Onboarding takes hours instead of weeks. See the Office Guide for team-specific best practices.
🧑💻 Solo developers
Future-you is basically a different person than current-you. Coming back to a project after two weeks? Run /session-start and you're immediately back up to speed. No more reading your own code trying to remember what you were thinking. No more re-discovering bugs you already fixed. DECISIONS.md is a letter from past-you to future-you.
Daily standups
When you run /session-handoff, add "also generate standup" to your message. Claude writes a Yesterday / Today / Blockers snippet in STANDUP.md. Copy it into Slack or Teams. Your standup is written before you've had your first coffee. Make it a team rule: everyone runs /session-handoff before logging off, and standups write themselves.
New hire onboarding Tell new hires: "Read DECISIONS.md from the very first entry to the latest." They'll see every major decision ever made, every bug ever hit, every time the tech stack changed and why — in one file. No more expensive onboarding sessions. No more "why is this code written this way?" No more repeating the same context to every new person.
PR review checklists Add to your PR template: "Does this PR include a session-handoff entry?" If the feature took multiple sessions, the reviewer can read DECISIONS.md to understand the full context — not just the diff. Reviews get faster and smarter because reviewers understand the why, not just the what.
Merge conflicts in DECISIONS.md
If two people worked at the same time and both ran /session-handoff, you'll get a merge conflict. The rule: always keep BOTH entries. Put the newest one on top. Never delete a log entry. Both perspectives are valuable.
Across multiple repos / monorepos Keep one DECISIONS.md at the repo root for big-picture decisions. For packages that change frequently, add a DECISIONS.md inside their folder too. The skill handles both.
One of the biggest costs of using Claude Code on a team is the tokens burned on orientation — Claude reading files to figure out where things stand. session-handoff cuts that dramatically.
| What you're doing | Without session-handoff | With session-handoff | Savings |
|---|---|---|---|
| Starting a new session | Claude explores ~30–50 files: ~40K tokens | Reads 3 knowledge files: ~2K tokens | 95% |
| Fixing a bug that was already fixed | Re-discovers & re-fixes: ~15K tokens | DECISIONS.md has the fix: ~500 tokens | 97% |
| Onboarding a teammate's Claude session | Full codebase scan: ~60K tokens | Reads knowledge files: ~3K tokens | 95% |
At Claude's API pricing, a team of 3 doing 5 sessions a day saves roughly 500K–1M tokens per week. That's real money — and it adds up fast at scale.
PRs are welcome. If you find a bug, open an issue. If you want to add a new template or improve the skill instructions, fork and submit a PR.
The one rule: keep it simple. This skill is meant to be dead easy to understand and use. No dependencies. No complex config. Just files and a few commands.
Made with ❤️ for hackathon teams, students, startups, and everyone who's ever lost context mid-project.
If this saved you tokens, give it a ⭐