# session-handoff

> Generate session handoff summary for continuing in new chat. Use when asked for handoff, session summary, or to prepare for continuing later.

- Author: Baz Hand
- Repository: bazhand/ai-agent-skills
- Version: 20260126213349
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/bazhand/ai-agent-skills
- Web: https://mule.run/skillshub/@@bazhand/ai-agent-skills~session-handoff:20260126213349

---

---
name: session-handoff
description: Generate session handoff summary for continuing in new chat. Use when asked for handoff, session summary, or to prepare for continuing later.
license: MIT
context: main
user-invocable: true
compatibility: Claude Code
allowed-tools:
  - Read
  - Glob
  - Write
  - Bash
  - TaskList
  - TaskGet
  - AskUserQuestion
---

# Session Handoff

Generate cognitive checkpoints that let the next session pick up mid-thought.

## Path Resolution

This skill uses `CLAUDE_CONFIG_DIR` if set, otherwise defaults to `~/.claude/`:

```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
```

Most users have the default. Custom setups (e.g., Syncthing sync to `~/.claude-user/`) set the env var.

## When to Use

Trigger when user asks to:
- "Generate handoff"
- "Create session summary"
- "Prepare for continuing later"
- "Save context for next session"

## Context

**Who uses this**: You (Claude) in a future session, starting fresh with no memory.

**Purpose**: Create a cognitive checkpoint that lets the next session pick up mid-thought, not start from scratch.

**Success**: The next session's first response directly continues the work without asking "what were we doing?"

---

## Workflow

### Step 1: Analysis Phase

Before writing the handoff, analyze in `<analysis>` tags:

```
<analysis>
1. What was the session about? (1 sentence)
2. What approaches did we try? (worked/failed/abandoned)
3. What's the current state? (plan exists? todos? code written?)
4. Where exactly did we stop? (specific question, decision, or task)
5. What would confuse a fresh session?
6. What decisions did we make? (approach chosen, alternatives rejected)
</analysis>
```

### Step 1.5: Clarify Scope (Optional)

If the session was long or complex, use `AskUserQuestion` to clarify:

```yaml
question: "What kind of handoff do you need?"
header: "Handoff type"
options:
  - label: "Full context (Recommended)"
    description: "Complete state for resuming after a long break"
  - label: "Quick summary"
    description: "Key points only, for a short break"
  - label: "Code-focused"
    description: "Emphasize code changes and technical state"
```

Skip this step for simple sessions or when the user explicitly requests a specific type.

### Step 2: Detection

Execute these commands:

```bash
# Resolve config directory (use env var or default)
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"

# Ensure handoff directory
mkdir -p "$CONFIG_DIR/handoffs"

# Find plan file
ls -t "$CONFIG_DIR/plans"/*.md 2>/dev/null | head -1

# Find transcript path
ls -t "$CONFIG_DIR/projects"/*/*.jsonl 2>/dev/null | head -1
```

Store the resolved `CONFIG_DIR` for use in Step 5.

### Step 3: Capture Todo State

1. Call `TaskList` tool to get current session tasks
2. For tasks with status `in_progress`, call `TaskGet` to retrieve full details (description, dependencies)
3. Format in handoff:
   - `[x]` for `completed`
   - `[~]` for `in_progress` — include description if available
   - `[ ]` for `pending`

Example:
```
- [x] Set up auth middleware
- [~] Implement JWT refresh (debugging token storage in auth/tokens.ts)
- [ ] Add rate limiting
```

### Step 4: Identify "Where We Left Off"

This is the MOST important section. Find:
- The last substantive topic being discussed
- Any unanswered questions
- The next action that was about to happen

**Bad**: "We were working on the auth feature"
**Good**: "We were debugging why the JWT refresh token wasn't being stored — suspected issue in `auth/tokens.ts:142` — about to add logging"

> **Tip**: If specific error messages or code patterns were discussed, use Grep to capture current file state for the Code Context section.

### Step 4.5: Secret Scan

Before writing, scan your handoff content for these patterns:

| Pattern | Example | Action |
|---------|---------|--------|
| API keys | `api_key = "sk-..."` | Replace with `[REDACTED]` |
| Passwords | `password: "hunter2"` | Replace with `[REDACTED]` |
| Tokens | `Bearer eyJ...` | Replace with `[REDACTED]` |
| Connection strings | `postgres://user:pass@host` | Replace credentials |
| GitHub PATs | `ghp_xxxxxxxxxxxx` | Replace with `[REDACTED]` |
| OpenAI keys | `sk-xxxxxxxxxxxxxxxx` | Replace with `[REDACTED]` |
| Slack tokens | `xoxb-...`, `xoxp-...` | Replace with `[REDACTED]` |
| Private keys | `-----BEGIN PRIVATE KEY-----` | Do not include |
| MongoDB URIs | `mongodb+srv://user:pass@` | Replace credentials |
| AWS keys | `AKIA...` | Replace with `[REDACTED]` |

If any secrets detected, redact before writing. Never include real credentials in handoffs.

### Step 5: Write Handoff

Write to `$CONFIG_DIR/handoffs/$(date +%Y-%m-%d)-[slug].md`

Where `CONFIG_DIR` is `$CLAUDE_CONFIG_DIR` if set, otherwise `~/.claude`.

**Slug rules**: 2-4 words, kebab-case, from objective noun/verb.
Examples: `jwt-refresh-bug`, `reveal-ui-simplify`, `handoff-optimize`

Use the template in [references/template.md](references/template.md).

**Pre-output checklist** (verify before proceeding):
- [ ] No `[TODO: ...]` placeholders remaining
- [ ] "Where We Left Off" section is specific (file:line, not vague)
- [ ] No secrets in content (Step 4.5 patterns)
- [ ] All `in_progress` tasks have context

### Step 6: Output

Return ONLY this line:

```
Read [resolved-config-dir]/handoffs/[filename].md and continue. [1 sentence: what we were working on]
```

Use the actual resolved path (e.g., `~/.claude/handoffs/` or `~/.claude-user/handoffs/`) so users can copy-paste directly.

The user will paste this as their first prompt in a new session.

---

## Quality Examples

### "Where We Left Off" — Good vs Bad

| Bad | Good |
|-----|------|
| "Working on authentication" | "Implementing JWT refresh — access token works but refresh fails silently. Last checked `auth/middleware.ts:89`. Next: add error logging" |
| "Debugging an issue" | "Safari returns `undefined` for `crypto.randomUUID()`. Confirmed in console. About to implement fallback" |
| "Planning the feature" | "Decided on approach B (WebSocket over polling). Plan written. About to start Phase 1" |

### "Objective" — Good vs Bad

| Bad | Good |
|-----|------|
| "Build a feature" | "Add real-time collaboration — users see each other's cursors" |
| "Fix bugs" | "Fix the 3 failing tests in `auth.test.ts` related to token expiry" |

---

## Additional Resources

- **[references/template.md](references/template.md)** - Full handoff template with all sections