# Checkpoint

> checkpoint (commit a layer of working state)

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

---

# checkpoint (commit a layer of working state)

Commit a one-page layer of this session's working state to the work's Derive lineage,
so any later session — yours tomorrow, a teammate's, another machine — continues cold
without re-explaining. Uses the Derive MCP `checkpoint` tool.

## When to fire

- A task the user asked for is complete (the natural boundary).
- Before a risky or destructive step (the layer is the restore point).
- Wrapping up a session, or the user says "checkpoint".

Don't wait for a clean ending — sessions get interrupted; checkpoint at the boundary
you're at, not the one you hoped to reach.

## How

1. **Find the lineage.** Read `.derive/lineage` at the repo root. If it exists, its
   content is the lineage's `short_id` — pass it. If not, this is the first
   checkpoint: call `checkpoint` with `work` (a short name — the feature or branch
   name) and NO `short_id`, then write the returned `short_id` to `.derive/lineage`
   so every later session finds it.
2. **Call `checkpoint`** with:
   - `state` — where the work stands, a few plain sentences a cold reader gets.
   - `decisions` — each with its why, including approaches rejected (so the next
     session doesn't re-propose them).
   - `open` — unresolved questions/threads that must not be dropped.
   - `next` — concrete next steps, most immediate first.
   - `refs` — pointers over prose: artifact short_ids, PR/issue URLs, key file paths.
3. **Replace, don't append.** Each checkpoint rewrites the whole page; versions keep
   the history. Restate only what still matters. If the tool rejects the size, trim —
   move detail into refs.

The lineage page is tool-maintained: humans should comment on it, not hand-edit it —
the next checkpoint replaces the page wholesale (comments survive; edits don't).

## Resuming

A session continuing the work reads the lineage first — the artifact's own
"Continue from here" section carries the paste-able command. If `.derive/lineage`
exists at session start and the task relates to ongoing work, read that artifact
before doing anything else.