context-handoff

Category: Operations Last Updated: January 2026

Purpose

Ensure reliable context recovery across compaction and session boundaries.

This skill creates a checkpoint of working state that enables another Claude instance (or the same instance post-compaction) to continue work without loss. It addresses the critical gap where automatic or manual compaction can occur without state being persisted.

Key Principle: After this skill runs,

current-task.md

When to Use

Manual Triggers

• User says "save my progress" or "save state"
• User is about to run

  /compact

• User is ending a session mid-task
• User requests

  /context-handoff

  or

  /checkpoint

  (alias)

Proactive Triggers (Claude Should Self-Invoke)

• Context usage approaches 70% (check with

  /context

  )
• Before a large operation that might push context over limits
• After completing significant work that should be checkpointed
• When switching between projects

Automatic Detection (Claude Should Monitor)

• Long-running tasks (> 30 minutes of work)
• After every 3-5 completed task steps
• After creating or modifying many files

Workflow

Step 1: Identify Current Work Context

DETERMINE active project:
  - Check if in a project worktree
  - Check git branch name (feature/{project-name})
  - Check recent file modifications under projects/
  - If ambiguous: Ask user

IF no active project:
  → "No active project detected. Nothing to checkpoint."
  → STOP

LOCATE current-task.md:
  - Path: projects/{project-name}/current-task.md
  - IF missing: Create from template

Step 2: Capture Critical State

This is the minimum state required for recovery. Be concise.

CAPTURE (in memory first):

1. TASK IDENTIFICATION
   - Task ID (from current work or current-task.md)
   - Task file path
   - Task title
   - Current phase

2. PROGRESS STATE
   - Completed steps (numbered list)
   - Current step number and description
   - Step progress (e.g., "Step 4 of 7, sub-step 2 of 3")

3. FILES MODIFIED (this session only)
   - List all files created or modified
   - Brief purpose for each
   - Mark any uncommitted changes

4. DECISIONS MADE (this session only)
   - Key implementation choices
   - Why each decision was made
   - Any alternatives considered

5. NEXT ACTION (CRITICAL - must be explicit)
   - Exact next step to take
   - Any preconditions
   - Files to reference

Step 3: Update current-task.md

Structure the update with Quick Recovery at top:

# Current Task State - {Project Name}

> **Last Updated**: {YYYY-MM-DD HH:MM} (by context-handoff)
> **Recovery**: Read "Quick Recovery" section first

---

## Quick Recovery (READ THIS FIRST)

| Field | Value |
|-------|-------|
| **Task** | {NNN} - {Title} |
| **Step** | {N} of {Total}: {Step description} |
| **Status** | {in-progress / blocked} |
| **Next Action** | {Explicit next action to take} |

### Files Modified This Session
- `{path}` - {purpose}
- `{path}` - {purpose}

### Critical Context
{1-3 sentences of essential context for continuation}

---

## Full State (Detailed)

[... rest of current-task.md content ...]

Step 4: Verify and Report

VERIFY current-task.md is complete:
  - Quick Recovery section has all fields
  - Next Action is explicit (not vague)
  - Files Modified matches actual changes
  - Timestamp is updated

OPTIONAL: Commit the checkpoint
  IF uncommitted changes exist:
    → "Do you want me to commit the state checkpoint? [y/n]"
    IF yes:
      git add projects/{project-name}/current-task.md
      git commit -m "checkpoint: save state for {task-id}"

REPORT to user:
  "✅ Context checkpoint saved to current-task.md

   Task: {task-id} - {title}
   Step: {N} of {total}
   Next: {next action}

   Ready for /compact or session end.
   To resume: 'continue task' or 'where was I?'"

Quick Recovery Format

The "Quick Recovery" section must answer these questions in < 30 seconds:

1. What task am I on? → Task ID, title, phase
2. Where in the task? → Step N of M
3. What files did I touch? → Files modified list
4. What do I do next? → Explicit next action

Example:

## Quick Recovery (READ THIS FIRST)

| Field | Value |
|-------|-------|
| **Task** | 045 - Deploy to Production |
| **Step** | 4 of 7: Configure Azure credentials |
| **Status** | in-progress |
| **Next Action** | Test deployment with: `az webapp deploy --slot staging` |

### Files Modified This Session
- `infrastructure/bicep/stacks/model2-full.bicep` - Added AI Search config
- `src/server/api/Sprk.Bff.Api/Program.cs` - Registered RagService

### Critical Context
OIDC federated identity configured. Staging deployment succeeded.
Need to verify health checks before promoting to production.

Integration with Other Skills

Before Compaction Flow

User: "I need to compact"
     ↓
Claude: [Invokes context-handoff]
     ↓
Claude: "✅ State saved. Ready for /compact."
     ↓
User: /compact
     ↓
[Compaction occurs]
     ↓
User: "Where was I?"
     ↓
Claude: [Invokes project-continue]
     ↓
Claude: Reads Quick Recovery section, continues work

During Long Tasks

[Claude working on task]
     ↓
[After completing step 5 of 8]
     ↓
Claude: [Proactively invokes context-handoff]
     ↓
Claude: "Checkpoint saved. Continuing with step 6..."

With project-continue

context-handoff: Creates checkpoint → current-task.md
project-continue: Reads checkpoint → restores context

Proactive Checkpoint Guidelines

When to self-checkpoint (Claude should do this automatically):

Error Handling

Examples

Example 1: Manual Pre-Compaction

User: "I need to compact, save my progress first"

Claude: [Runs context-handoff]

Output:
  "✅ Context checkpoint saved to current-task.md

   Task: 032 - Implement Email Export
   Step: 3 of 5: Create EmailExportService
   Next: Implement SendEmailAsync method using Graph API

   Files modified:
   - Services/Ai/Export/IEmailExportService.cs - Created interface
   - Services/Ai/Export/EmailExportService.cs - Started implementation

   Ready for /compact. To resume: 'continue task' or 'where was I?'"

Example 2: Proactive Checkpoint

[Claude just completed step 5 of 8]

Claude: "Step 5 complete. Let me checkpoint progress..."

[Runs context-handoff silently]

Claude: "✅ Progress saved. Continuing with Step 6: Add unit tests..."

Example 3: End of Session

User: "I'm done for today"

Claude: [Runs context-handoff]

Output:
  "✅ Session state saved.

   Task 013 at Step 4 of 6.
   Next session: Say 'continue task 013' or 'where was I?'

   Good night!"

Related Skills

project-continue

task-execute

push-to-github

Tips for AI

• Be proactive - Don't wait for user to ask; checkpoint after significant work
• Keep Quick Recovery minimal - Recovery should take < 30 seconds to read
• Next Action must be explicit - "Continue working" is NOT explicit; "Run

  dotnet test

  " IS explicit
• Timestamp is critical - Always update Last Updated when checkpointing
• Don't overwrite history - Move detailed history to "Full State" section, not delete
• Files Modified is session-scoped - Reset when task changes, not accumulate forever
• Verify before reporting - Actually read back current-task.md to confirm save worked

Post-Compaction Recovery

When Claude Code resumes after compaction:

1. User says anything → Check if there's active project context
2. Find current-task.md → Read Quick Recovery section
3. Load minimal context → Just enough to continue
4. Report state → "Recovered: Task X, Step Y, Next: Z"
5. Load full context → Via project-continue if needed

This can be automatic if the user's first message is work-related, or explicit via "where was I?".

This skill ensures no work is lost across context boundaries.