# Save Progress

> Save a checkpoint of the current task -- what has been done plus a concrete resume plan -- to the project's progress directory. Use when check-usage returns band "stop", and at intermediate checkpoints during any long task.

- Skill: `jgjake2/save-progress` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jgjake2/save-progress`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jgjake2/save-progress/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: jgjake2 (https://skillmd.com/u/jgjake2)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jgjake2/save-progress

---


# save-progress

Writes a timestamped JSON checkpoint (plus a readable `.md` copy) to `progress/`, and
updates `progress/latest.json` so resuming never requires a hand-copied filename.

## How to call it

The two fields are long multi-line prose, so they go through a JSON file rather than
command-line arguments (which would be a quoting minefield on Windows).

**Step 1** -- write the payload to `progress-payload.json`:

```json
{
    "task": "One-line description of what the overall task is",
    "progress": "Everything accomplished so far: files changed, decisions made, intermediate results, anything already verified.",
    "resumePlan": "The concrete next steps, remaining work, and any dependencies or prerequisites.",
    "notes": "Optional. Anything else the next session needs."
}
```

**Step 2** -- run:

```
node .claude/skills/save-progress/save-progress.js --payload progress-payload.json --consume
```

`--consume` deletes the payload file after a successful save.

`progress` and `resumePlan` are required and must be non-empty.

To pipe the JSON on standard input instead, pass `--stdin` explicitly:

```
... | node .claude/skills/save-progress/save-progress.js --stdin
```

`--stdin` is opt-in on purpose: without it, a harness that leaves stdin open would block
this script forever, and it runs precisely when the budget is nearly gone.

## Response

```json
{ "saved": true, "path": "...", "markdownPath": "...", "latestPointer": "...", "savedAt": "..." }
```

On failure: `{ "saved": false, "error": "..." }` with a non-zero exit code. A failed save
leaves no partial checkpoint behind.

## Writing a good checkpoint

The resume plan is read by a session with **no memory of this one**. Name files by full
path, state decisions rather than implying them, and make the first next-step something
concrete enough to start on immediately. Assume nothing carries over.

Tell the user the checkpoint path after saving.