Skip to main content
Agent skill

Manage Task Checkpoints

Inspect and recover snapshots owned by a COSH managed Task. Use when the user asks the outer COSH Agent to list Task snapshots, preview or diff an exact recovery point, switch a Task workspace, or recover a workspace-only failure and retry once. Do not use for standalone ws-ckpt workspaces.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Manage Task Checkpoints when an AI agent needs a reusable SKILL.md workflow for this job: Inspect and recover snapshots owned by a COSH managed Task. Use when the user asks the outer COSH Agent to list Task snapshots, preview or diff an exact recovery point, switch a Task workspace, or recover a workspace-only failure and retry once. Do not use for standalone ws-ckpt workspaces.

When not to use it

Skip Manage Task Checkpoints when the task is outside the productivity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/manage-task-checkpoints
# Save SKILL.md to ~/.claude/skills/manage-task-checkpoints/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/manage-task-checkpoints/SKILL.md. For a shared project, commit the folder at .claude/skills/manage-task-checkpoints/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Manage Task Checkpoints skill for this task: Use Manage Task Checkpoints when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Manage COSH Task Checkpoints

Treat this Skill as a recovery workflow, not a security boundary. Gateway and ws-ckpt enforce Task ownership, complete snapshot IDs, workspace generation, live diff, peer identity, and replay safety.

## Keep the scope Task-only

- Use this Skill only for `/task`, `tsk_...`, or an explicitly managed Task. - Use the separate `ws-ckpt` Skill for a standalone workspace. - Do not infer the managed workspace from cwd or ask the user for its path. - Do not call bare `ws-ckpt`, a lab script, or the ws-ckpt socket for a Task.

## Inspect Task snapshots

Use the Task-scoped Gateway CLI. It resolves an explicit socket, then `COSH_GATEWAY_SOCKET`, then the active packaged Gateway instance:

```bash cosh-gateway task --output jsonl list cosh-gateway task --output jsonl snapshot list <task-id> cosh-gateway task --output jsonl snapshot preview <task-id> <snapshot-id> cosh-gateway task --output jsonl snapshot diff <task-id> <snapshot-id> ```

Accept only complete Task and snapshot IDs returned by Gateway. Never guess or expand a prefix. When several Tasks or recovery points match, summarize their status and file effects and ask the user to choose by meaning rather than copying internal IDs.

Users can inspect the same state directly with:

```text /task snapshots <task-id> /task snapshot preview <task-id> <snapshot-id> /task snapshot diff <task-id> <snapshot-id> ```

## Switch safely

1. Require the Task to be terminal before switching. 2. Ensure the outer `cosh-shell` process was launched outside the managed workspace. Running `cd /tmp` inside an Agent Bash command changes only the child process and does not release the parent shell cwd. 3. Preview the exact snapshot immediately before switching. 4. Describe the files that will be removed, restored, or retained. Ask for natural-language confirmation unless the user already authorized this one exact recovery attempt. 5. Submit the exact snapshot ID, preview digest, terminal Task revision, and a fresh idempotency key for this operation. 6. Verify the resulting file state against the preview.

```bash cosh-gateway task --output jsonl snapshot switch <task-id> <snapshot-id> \ --preview-digest <digest> \ --expected-revision <revision> \ --idempotency-key <fresh-key> ```

Do not display Task IDs, snapshot IDs, revisions, digests, approval IDs, or idempotency keys in ordinary progress or final prose. Keep them in the actual command or approval card. Describe recovery points by step and affected files.

### Handle cwd and uncertain results

- On `CwdOccupied`, state that the target was not switched. Ask the user to exit the entire COSH session, start COSH from outside the workspace, and run a new preview. Do not retry the consumed operation key. - On `unknown`, `possibly_applied`, or lost transport after dispatch, stop and report the uncertainty. Never generate another key to retry blindly. - Never add `--force` or `--yes`, and never bypass Gateway with raw ws-ckpt.

## Recover and retry once

For an established workspace-file failure in a multi-step Task:

1. Stop further file writes. 2. Confirm that the failure has no network, cloud, service, credential, database, or other external side effect. 3. Prefer the nearest `pre_effect` before the bad step; use the baseline only when no suitable pre-effect checkpoint exists. 4. Preview and switch once using the workflow above. 5. Retry the failed step once with a corrected approach. Do not loop. 6. Report the human-readable recovery point, verification, retry result, and whether Gateway created a recovery snapshot that can undo the switch.

File snapshots do not restore external side effects. Stop automatic recovery and identify the remaining state when any such effect may have occurred.

Intended uses

  • Use Manage Task Checkpoints when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.