All skills
rav4nn avatar

/checkpoint

by Hardeep Singhrav4nn/skills4 stars

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).

Use this Skill: https://skilld.dev/gh/rav4nn/skills/checkpoint

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈72 tokens for metadata: the name and description. ≈1.1k when used: this file.

Description uses 3.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈289 characters, or 3.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 <TOPIC> 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 <dev-servers> 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 <DIR>/briefing.md with the Write tool. In list-only mode, send kill <pids> in the same message. Sections, in this order:

    • <goal>: the mission, not one task.
    • <plan-ref>: the absolute path of the plan or spec. If none exists, give the plan shape in 2 lines.
    • <completed>: one terse line each, with the branch, PR, or file that shows it.
    • <remaining>: the ordered work queue: what, why, dependencies. Mark items (new) or (revised).
    • <blocked>: what cannot go ahead, and why.
    • <decisions-log>: only the decisions that changed the shape of the work, one line each.
    • <files>: absolute paths: worktrees and branches, dirty files, open PRs, scratchpad artifacts, session gotchas. Put recurring gotchas in auto-memory, not here.
    • <dev-servers>: 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 <remaining>, 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 <plan-ref>.

  3. Print exactly this, then stop:

    Checkpoint written to <DIR>/briefing.md. Stopped dev servers: <ports, or "none">. 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 <plan-ref>. The briefing carries only the delta. What the plan marks done is ground truth, <remaining> is the work queue, <blocked> lists the landmines. If <plan-ref> is an issue, fetch it and its child issues first. The tracker wins where it disagrees with the briefing.

  3. For each <dev-servers> line: cd <cwd>, start <command> in the background with its output in <DIR>/logs/<port>.log, then check lsof -iTCP:<port> -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.

Source: SKILL.md on GitHub

Skill behaviors

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

Third-party checks

2 warnings5d3 checks · Risk SAFE
  • Gen Agent Trust Hub5d

    The skill provides a workflow for creating and resuming state checkpoints within an AI session. It uses a helper script to manage project-specific briefing files and handle local development server lifecycles, and no security risks were identified.

  • Socket5d

    1 alert: gptSecurity

  • Snyk5d

    Risk: MEDIUM · 1 issue

Provenance

Signed by skilld. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

updated 5 days ago

README badge

README badge for rav4nn/skills/checkpoint