# Checkpoint

> Save a compact continuation checkpoint so current work survives context compaction or a later session. Use when the active context is becoming long or work must pause without changing client or machine ownership. For an explicit cross-session/client transfer, use $handoff.

- Skill: `flonat/checkpoint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add flonat/checkpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flonat/checkpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: flonat (https://skillmd.com/u/flonat)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/flonat/checkpoint

---


# Checkpoint — Save Session State

Snapshot the current session's progress to a YAML file so it can be restored after context compaction or in a new session. This is NOT a session log (narrative) or context save (profile/focus) — it's a machine-readable state dump for continuity.

## When to Use

- Before a session is likely to hit context compression (many tool calls, long outputs)
- At phase boundaries in multi-phase work
- When the user says "save state", "checkpoint", "save progress"
- Proactively when you sense context is getting large — don't wait to be asked

## When This Skill Is Invoked

### Step 1: Gather State

Collect the following from the current conversation context:

1. **Project** — which project directory are we working in?
2. **Task** — what was the user's original request this session?
3. **Files modified** — list every file you've created or edited this session (use `git diff --name-only` if in a git repo, plus any new untracked files)
4. **Decisions made** — key choices and their rationale (e.g., "chose LaTeX over Markdown because...", "used sonnet for cron jobs to reduce cost")
5. **Current step** — where in the plan are we? What just completed? What's next?
6. **Blocked items** — anything that couldn't be completed and why
7. **Open questions** — unresolved ambiguities that need user input

### Step 2: Write Checkpoint

Write to `.planning/checkpoint.yaml` in the active project directory. If no project directory is obvious, write to the Task Management root.

```yaml
# Auto-generated by checkpoint — do not edit manually
created: "YYYY-MM-DDTHH:MM:SS"
session_id: "<from $CLAUDE_SESSION_ID if available>"
project: "<project directory basename>"

task: |
  <one-paragraph description of what the user asked for>

files_modified:
  - path: "relative/path/to/file.md"
    action: "created|edited|deleted"
    summary: "what was changed and why"

decisions:
  - decision: "what was decided"
    rationale: "why"

progress:
  completed:
    - "step 1 description"
    - "step 2 description"
  current: "what step we're on now"
  next:
    - "next step 1"
    - "next step 2"

blocked:
  - item: "what's blocked"
    reason: "why"

open_questions:
  - "question that needs user input"

context_files:
  - "list of files that should be re-read on restore"
```

### Step 3: Confirm

Report to the user:
```
Checkpoint saved to .planning/checkpoint.yaml
- N files modified
- N decisions recorded
- Current step: [description]
- Next: [first next step]
```

## Schema Rules

- **`files_modified`**: Only files touched THIS session, not all project files
- **`decisions`**: Only non-obvious choices. Skip mechanical decisions ("used latexmk" is obvious; "chose TWFE over CS estimator" is not)
- **`context_files`**: List files that `restore` should re-read to reconstruct working context. Include CLAUDE.md, the plan file, and any files being actively edited
- **`progress.current`**: Must be specific enough that `restore` can pick up exactly where we left off
- **Timestamps**: Always ISO format, always local timezone

## Multiple Checkpoints

Each `checkpoint` invocation overwrites the previous checkpoint. There is only one active checkpoint per project. If you need history, the git log preserves it.

## Anti-Patterns

- Do NOT write narrative prose — this is structured data for machine consumption
- Do NOT include file contents — only paths and summaries
- Do NOT checkpoint trivially (single-file edits with no decisions) — it's overhead without value
- Do NOT use this instead of `session-log` — session logs are for humans, checkpoints are for restore