New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Session Handoff Document

by thedotmack in thedotmack/claude-mem

Writes a HANDOFF.md capturing goal, state, files, failed attempts and next steps so a fresh agent session can continue exactly where this one stopped.

Apache-2.0Auto-check passedAgent Workflows

Install Session Handoff Document

skills CLI
$ npx skills add thedotmack/claude-mem --skill handoff -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install thedotmack/claude-mem handoff --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/thedotmack/claude-mem.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugin/skills/handoff .claude/skills/handoff && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
handoff
GitHub stars
99k
Token cost
~1.4k tokens
SKILL.md length
676 words
Files
1
Skills in repo
26
Repo updated
First seen
Licence
Apache-2.0

At a glance

Writes a HANDOFF.md capturing goal, state, files, failed attempts and next steps so a fresh agent session can continue exactly where this one stopped.

  • Works in 8 steps: Goal — One paragraph. What is the user… → Current State — What is working right… → Files in Play — List every file that has… → …
  • A long session has become confused or repetitive
  • SKILL.md covers When to Use, What to Capture, Writing Rules and Output, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

When a session gets long, repetitive or confused, the agent writes a structured `HANDOFF.md` meant for a fresh session that has never seen the conversation. It complements claude-mem, which already injects recent observations into new sessions: the handoff adds the goal, the failed attempts and why they failed, the current theory and exact next steps, with pointers into memory for deeper recall.

Seven sections are required: goal, current state (including error messages verbatim), files in play with a note on why each matters, what was tried and why it failed (the most important part), current best theory, ordered next steps with paths and commands, and key constraints such as user preferences and things the user said not to do.

When your agent uses it

  • A long session has become confused or repetitive
  • The agent keeps retrying the same failing solution
  • You want to stop now and resume in a new session later
  • /compact ran but the agent still lacks direction

Example prompts

  • “Write a handoff so I can start fresh in a new session.”
  • “You keep retrying the same fix; generate a handoff doc with what failed and why.”
  • “I need to step away, so capture where we are and we can pick this up tomorrow.”

Requirements

  • The claude-mem plugin, which supplies session memory

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

  1. Goal — One paragraph. What is the user actually trying to accomplish? State the end state, not the current sub-task. Be specific enough…
  2. Current State — What is working right now? What is broken? What is the exact symptom of the problem? Include error messages verbatim if…
  3. Files in Play — List every file that has been read, edited, or created during this session that is relevant to the current task. Use…
  4. What Has Been Tried (and Why It Failed) — This is the most important section. List every approach attempted that did not work, and explain…
  5. Current Best Theory — What do you currently believe is the right path forward, even if you haven't proven it yet? Include any evidence or…
  6. Next Steps — Concrete, ordered actions for the fresh agent to take. Be specific: file paths, function names, commands to run. The fresh…
  7. Key Constraints and Context — Any non-obvious constraints: environment specifics, user preferences expressed during this session, things…
  8. Memory Pointers — If claude-mem's search tools are available, run search for this task's key terms and list the few observation IDs that…

What it can do on your machine

Read from SKILL.md and the folder at commit fa8ab09. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Session Handoff Document loads about 1.4k tokens when it runs. Until then it costs about 80 tokens; SKILL.md has 676 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~80
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from thedotmack/claude-mem at commit fa8ab09, republished under its Apache-2.0 licence (© thedotmack). 676 words, ~1,408 tokens.

Download SKILL.mdSave it as .claude/skills/handoff/SKILL.md (or your agent's skills folder).
name
handoff
description
Generate a HANDOFF.md that captures goal, current state, files touched, failed attempts, and next steps — so a fresh Claude session can continue exactly where this one left off. Use when sessions are getting long, Claude keeps retrying the same broken solution, or the user wants to step away and resume later.

Handoff

Generate a structured HANDOFF.md file that gives a fresh Claude session everything it needs to continue this work without dragging the current degraded context forward.

claude-mem already injects recent observations into every new session, so the fresh agent starts with a timeline of what happened. The handoff adds what that timeline cannot: the goal, the failed attempts and why they failed, the current theory, and exact next steps, plus pointers into memory for deeper recall.

When to Use

  • The session is long and Claude feels confused or repetitive
  • Claude keeps trying the same failing solution over and over
  • The user wants to step away and resume later
  • /compact ran but Claude still lacks clear direction
  • The user says "handoff", "generate a handoff", "I want to start fresh", or "write a handoff doc"

What to Capture

Think hard about the full arc of this conversation before writing. The handoff must be useful to a Claude instance that has never seen this conversation.

Required Sections

  1. Goal — One paragraph. What is the user actually trying to accomplish? State the end state, not the current sub-task. Be specific enough that a fresh agent can orient immediately.

  2. Current State — What is working right now? What is broken? What is the exact symptom of the problem? Include error messages verbatim if relevant.

  3. Files in Play — List every file that has been read, edited, or created during this session that is relevant to the current task. Use absolute or repo-relative paths. Include a one-line note on why each file matters.

  4. What Has Been Tried (and Why It Failed) — This is the most important section. List every approach attempted that did not work, and explain WHY it failed (not just that it failed). A fresh agent that skips this section will repeat the same mistakes.

  5. Current Best Theory — What do you currently believe is the right path forward, even if you haven't proven it yet? Include any evidence or reasoning that supports it.

  6. Next Steps — Concrete, ordered actions for the fresh agent to take. Be specific: file paths, function names, commands to run. The fresh agent should be able to start on step 1 immediately.

  7. Key Constraints and Context — Any non-obvious constraints: environment specifics, user preferences expressed during this session, things the user explicitly said NOT to do, external dependencies, performance requirements, etc.

  8. Memory Pointers — If claude-mem's search tools are available, run search for this task's key terms and list the few observation IDs that matter most (a decision, the root cause, a failed approach), so the fresh agent can pull full details with get_observations. Also list one or two search queries worth re-running. Skip this section if the tools are not available.

Show full SKILL.md (222 more words)Show less

Writing Rules

  • Write the handoff for a fresh Claude, not for the user. The user knows what happened; the fresh Claude does not.
  • Be ruthlessly specific. Vague next steps are useless. "Fix the auth" is bad. "In src/auth/middleware.ts:47, the token expiry check uses Date.now() but should use req.timestamp — change the comparison on line 52" is good.
  • Include exact error messages, stack traces, or test output that captures the failure mode.
  • Do not pad. Every sentence should be load-bearing information for the fresh agent.
  • Do not write the handoff from the user's perspective. Write it as a briefing document addressed to the incoming agent.

Output

Write the handoff to HANDOFF.md in the current working directory (the project root).

Use this structure:

markdown
# Handoff

> Generated: [timestamp]  
> Project: [project name or directory]  
> Session summary: [one sentence describing what this session was about]

## Goal

[What the user is trying to accomplish — the actual end state]

## Current State

**Working:**
- [list what is confirmed working]

**Broken:**
- [exact symptom, error message, or failure mode]

## Files in Play

| File | Why It Matters |
|------|---------------|
| `path/to/file.ts` | [one line] |

## What Has Been Tried (and Why It Failed)

### Attempt 1: [short name]
- **What:** [what was done]
- **Why it failed:** [root cause, not just "it didn't work"]

### Attempt 2: [short name]
...

## Current Best Theory

[What you currently believe is the correct approach and why]

## Next Steps

1. [Specific, actionable step with file path or command]
2. [Next step]
3. ...

## Key Constraints

- [Non-obvious constraint or preference the user expressed]
- [Things explicitly ruled out]

## Memory Pointers

- Observations: [#ID — one line on why it matters]
- Searches worth re-running: [`search` query]

After Writing

Tell the user:

  1. That HANDOFF.md has been written
  2. To run /clear or start a new Claude Code session
  3. To open the new session and say: "Read HANDOFF.md and continue from where we left off."
  4. That claude-mem gives the fresh agent the recent timeline automatically, and HANDOFF.md is its precise briefing on top of that
  5. That HANDOFF.md is a scratch file: don't commit it (delete it once the new session has picked up, or add it to .gitignore)

Keep the message short. The user is ready to move — don't make them read a wall of text.

© thedotmack, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in plugin/skills/handoff of thedotmack/claude-mem.

Open the folder on GitHubat commit fa8ab09

Compare with similar skills

Session Handoff Document next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Session Handoff Document compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Session Handoff Document this skillthedotmack/claude-mem99k—~1.4kAutomated safety check: PassApache-2.0
Memori Long-Term MemoryMemoriLabs/Memori17k—~2kAutomated safety check: NotesCustom licence
Planning with FilesOthmanAdi/planning-with-files27k—~2.9kAutomated safety check: PassMIT
User Thoughts Memorysickn33/agentic-awesome-skills47k1 repos~2.5kAutomated safety check: PassMIT
Planning With FilesOthmanAdi/planning-with-files27k—~3kAutomated safety check: PassMIT
Harness Engineering10xChengTu/harness-engineering1021 repos~1kAutomated safety check: PassNone

Similar skills

  • Memori Long-Term Memory

    MemoriLabs/Memori

    Connects Claude Code to Memori Cloud for long-term memory, recalling stored context before substantive replies and saving new context afterward.

    17k GitHub stars~2k tokensUpdated 6 days ago
    Agent WorkflowsAuto-check: notes

  • Planning with Files

    OthmanAdi/planning-with-files

    Keeps a task plan, findings and progress log in markdown files on disk so long agent tasks survive context resets, with Gemini hooks and helper scripts.

    27k GitHub stars~2.9k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

  • User Thoughts Memory

    sickn33/agentic-awesome-skills

    Saves a user's project decisions, rules and preferences into a project-local mdbase so later sessions and other agents can recover the intent.

    47k GitHub starsUsed in 1 repo~2.5k tokens
    Agent WorkflowsAuto-check passed

  • Planning With Files

    OthmanAdi/planning-with-files

    Keeps a task plan, findings and progress log as Markdown files in the project so long multi-step agent work survives context resets.

    27k GitHub stars~3k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

  • Harness Engineering

    10xChengTu/harness-engineering

    Set up and improve harness engineering (AGENTS.md, docs/, lint rules, eval systems, project-level prompt engineering) for AI-agent-friendly codebases.

    102 GitHub starsUsed in 1 repo~1k tokens
    Agent WorkflowsAuto-check passed

  • Planning with Files for Kiro

    OthmanAdi/planning-with-files

    Keeps task_plan.md, findings.md and progress.md on disk as the agent's working memory for multi-step work, wired into Kiro steering, with no hooks.

    27k GitHub stars~2.1k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

More from thedotmack/claude-mem

All 26 skills in this repo

  • Custom Mode Creator for claude-mem

    thedotmack/claude-mem

    Walks you through creating, installing and verifying a custom claude-mem mode, including note types, tags and optional Telegram alerts for chosen memories.

    99k GitHub stars~2.4k tokensUpdated today
    Auto-check passed

  • Pull Request Babysitter

    thedotmack/claude-mem

    Keeps watching a pull request, fixing real review and CI problems and resolving stale threads, until it is clean and ready to merge.

    99k GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Claude-Mem Install for Grok Bot

    thedotmack/claude-mem

    Use this when setting up claude-mem on Grok Bot: local worker plus CMEM Pro observer (default), optional host-login observer, or remote cmem.ai. No Cursor…

    99k GitHub stars~440 tokensUpdated today
    Auto-check passed

  • Claude-Mem Cloud Sync

    thedotmack/claude-mem

    Checks claude-mem cloud sync status and guides you through connecting a cmem.ai Pro account without the sync token ever passing through the chat.

    99k GitHub stars~1k tokensUpdated today
    Auto-check: notes

  • Design Audit Against Rams' Principles

    thedotmack/claude-mem

    Audits a design against Dieter Rams' ten principles of good design, scores each with evidence, and hands off a make-plan prompt for a new, refined or redesigned outcome.

    99k GitHub stars~4.6k tokensUpdated today
    Auto-check passed

  • Claude-Mem Knowledge Agent

    thedotmack/claude-mem

    Builds focused knowledge corpora from claude-mem observations, loads them into an AI session and answers questions about past work.

    99k GitHub stars~617 tokensUpdated today
    Auto-check passed

Categories

Questions about Session Handoff Document

What does Session Handoff Document do?

Writes a HANDOFF.md capturing goal, state, files, failed attempts and next steps so a fresh agent session can continue exactly where this one stopped. md` meant for a fresh session that has never seen the conversation. It complements claude-mem, which already injects recent observations into new sessions: the handoff adds the goal, the failed attempts and why they failed, the current theory and exact next steps, with pointers into memory for deeper recall.

When should I use Session Handoff Document?

Session Handoff Document fits situations like: A long session has become confused or repetitive; the agent keeps retrying the same failing solution; you want to stop now and resume in a new session later; /compact ran but the agent still lacks direction.

How do I install Session Handoff Document in Claude Code?

Run `npx skills add thedotmack/claude-mem --skill handoff -a claude-code`. Or copy the skill folder (plugin/skills/handoff in thedotmack/claude-mem) into .claude/skills/handoff in your project. Claude Code loads it when a task matches its description.

How do I install Session Handoff Document in Codex?

Run `npx skills add thedotmack/claude-mem --skill handoff -a codex`. Or copy the skill folder (plugin/skills/handoff in thedotmack/claude-mem) into .agents/skills/handoff in your project. Codex loads it when a task matches its description.

Can I use Session Handoff Document in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add thedotmack/claude-mem --skill handoff -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/handoff, .gemini/skills/handoff, .github/skills/handoff and .opencode/skills/handoff in your project.

What does Session Handoff Document need to run?

SKILL.md names no scripts, command-line tools or credentials: Session Handoff Document is instructions for the agent only. Our summary lists: The claude-mem plugin, which supplies session memory.

Does Session Handoff Document access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Session Handoff Document safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Session Handoff Document use?

Session Handoff Document is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Session Handoff Document use?

About 1.4k tokens (SKILL.md is roughly 5.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Session Handoff Document?

Skills that share tags, products or a category with Session Handoff Document: Memori Long-Term Memory (MemoriLabs/Memori, 17k stars), Planning with Files (OthmanAdi/planning-with-files, 27k stars), User Thoughts Memory (sickn33/agentic-awesome-skills, 47k stars) and Planning With Files (OthmanAdi/planning-with-files, 27k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Session Handoff Document?

thedotmack (a GitHub user) maintains it in thedotmack/claude-mem, which has 98,732 GitHub stars. The repository holds 26 skills in this directory. The repository was last updated on October 9, 2026.

Source: thedotmack/claude-mem on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.