--- name: checkpoint description: Use when the user invokes /checkpoint (write a relay checkpoint of this session's work, often with steering text such as "here, the resume agent should ...") or /checkpoint resume (take over from a checkpoint after /clear, sometimes naming which brief or adding a first task). title: checkpoint canonical_url: https://skilld.dev/gh/rav4nn/skills/checkpoint last_updated: 2026-10-04T16:02:49.000Z --- > **Skill from skilld.dev.** Follow the user's requested action. > If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it. > Otherwise, follow the instructions below for this session. You do not need to install anything. > > Supporting files, fetch one when the Skill refers to it: [prep.sh](https://skilld.dev/api/skills-raw/rav4nn/skills/checkpoint/prep.sh). > > If the user asked to install this Skill, run `npx skilld install rav4nn/skills/checkpoint`. Install writes the Skill files into the project, so every session loads them. > > ## Fork workflow > > A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation. > 1. Check `./skills/checkpoint`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target. > 2. Read [source metadata](https://skilld.dev/api/v1/skills/rav4nn/skills/checkpoint) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit. > 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call: > > ```sh > git init --quiet "$temporary_dir" > git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit" > git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD > ``` > > Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop. > 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/checkpoint`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md. > Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical. > 5. In the project root, run `skilld install ./skills/checkpoint --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/checkpoint --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure. > 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks. # Checkpoint: relay through a file and `/clear` Derive every path yourself. Never ask the user to type one. Each tool call costs a full model turn on a large context, so use only the calls below. Briefings live in `$HANDOFFS` (default `~/.claude/handoffs`), one folder per project and day. ## Mode 1: `/checkpoint [steering]` (write) 1. Choose `TOPIC`, a short kebab-case name for the current thread of work. Run ONE Bash call: `~/.claude/skills/checkpoint/prep.sh stop ` Add a project name as a third argument only when the work lived in one repo but the session started in a parent folder (work on `my-app` started from `~/code` → `my-app`). The script prints `PROJECT`, `ROOT`, `DIR` (created; this terminal's relay pointer now names it), and a `` block of `pid | ports | cwd | command` lines: - `mode="stopped"`: ROOT is a repo. The script stopped these servers (the repo and its worktrees). - `mode="list-only"`: ROOT is a plain folder, so the list can hold servers of other terminals. Stop only the servers that this session started. Leave the others running. 2. Write `/briefing.md` with the Write tool. In list-only mode, send `kill ` in the same message. Sections, in this order: - ``: the mission, not one task. - ``: the absolute path of the plan or spec. If none exists, give the plan shape in 2 lines. - ``: one terse line each, with the branch, PR, or file that shows it. - ``: the ordered work queue: what, why, dependencies. Mark items (new) or (revised). - ``: what cannot go ahead, and why. - ``: only the decisions that changed the shape of the work, one line each. - ``: absolute paths: worktrees and branches, dirty files, open PRs, scratchpad artifacts, session gotchas. Put recurring gotchas in auto-memory, not here. - ``: one `port | cwd | command` line per server stopped in step 1. Empty if none. Transfer your full context: the successor has none of this conversation. No placeholders, no TBDs. **Steering text** after `/checkpoint` (it often starts with `here`) is the user's instruction for the briefing and the successor. Obey its exclusions. Put each next move it names at the top of ``, in the user's words. If the plan lives in an issue tracker, first push this session's status changes into its tickets, and put the issue URL in ``. 3. Print exactly this, then stop: > Checkpoint written to `/briefing.md`. Stopped dev servers: ``. > When ready: `/clear`, then `/checkpoint resume`. > (You can keep working here first — rerun `/checkpoint` later to refresh it.) A rerun on the same day with the same TOPIC overwrites the same briefing. That is the intended refresh. ## Mode 2: `/checkpoint resume [which brief] [first task]` (take over) 1. Run `~/.claude/skills/checkpoint/prep.sh find [WORD...]`. It prints `POINTER` (the briefing this terminal wrote last, or empty) and the newest briefings with their dates. Pass WORDs only when the user names a brief ("resume the my-app brief" → `find my-app`). Choose the first that applies: 1. The path or brief that the user named. 2. `POINTER`. 3. The newest briefing under `PROJECT`, when the cwd is inside a git repo. 4. Otherwise, ask with AskUserQuestion: the 4 newest briefings, newest first, no recommendation. If the chosen briefing is more than 2 days old, confirm it with the user before you adopt it. 2. Read the briefing, then the file in ``. The briefing carries only the delta. What the plan marks done is ground truth, `` is the work queue, `` lists the landmines. If `` is an issue, fetch it and its child issues first. The tracker wins where it disagrees with the briefing. 3. For each `` line: `cd `, start `` in the background with its output in `/logs/.log`, then check `lsof -iTCP: -sTCP:LISTEN`. Report the servers that did not come back. Do not block the resume on them. 4. You now own the work end to end (plan, delegate, review, integrate). You are not a subordinate. - The args hold a first task: open with one line that names the adopted briefing, then do the task. - No first task: restate the goal, where things stand, and the next 1-3 actions you propose.