agentleFS
Sign inStart free
jasonmichaelbell78-creatorjasonmichaelbell78-creator/sonash-v0/.claude/skills/checkpoint/SKILL.md

checkpoint

Skill2 starsChanged 9 months agoApache-2.0View on GitHub

Save session state for recovery after compaction or failures. Default: save to local files (.claude/state/). With --mcp: also save to MCP memory for cross-session persistence.

We split this skill into the rules it gives an agent

8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 84 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When the task doesn't match this skill's scope

    line 25
  2. Distinctive:

    If uncommitted work exists and the task is at a safe point:

    line 84
  3. Very specific:

    When --mcp is specified, also save structured entities to MCP memory.

    line 94
  4. Distinctive:

    After saving, report what was preserved:

    line 137
  5. Distinctive:

    Before large file operations

    line 150
  6. Distinctive:

    Before complex multi-step tasks

    line 151
  7. Distinctive:

    When session is getting long (50+ tool calls)

    line 152
  8. Very specific:

    If MCP was used: mcp__memory__search_nodes("Session_")

    line 162

“Common” is measured: kept by at least 6 in 10 of the 84 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- prettier-ignore-start -->

Document Version: 2.0 Last Updated: 2026-02-14 Status: ACTIVE

<!-- prettier-ignore-end -->

Session Checkpoint

Save current state so you can recover after compaction or session failure.

When NOT to Use

  • Full session closure — use /session-end instead (runs metrics pipeline, compliance checks, and commits)
  • When the task doesn't match this skill's scope

Usage

/checkpoint          # Save to local files only
/checkpoint --mcp    # Save to local files + MCP memory

Local Save (default)

1. Update SESSION_CONTEXT.md Quick Recovery

## Quick Recovery

**Last Checkpoint**: YYYY-MM-DD HH:MM **Branch**: `branch-name-here` **Working
On**: [brief task description] **Files Modified**: [list or "none"] **Next
Step**: [what to do next] **Uncommitted Work**: yes/no

2. Write State Files

Update .claude/state/handoff.json:

{
  "timestamp": "ISO datetime",
  "git": {
    "branch": "current branch",
    "lastCommit": "hash + message",
    "uncommittedFiles": ["list"]
  },
  "currentTask": "what you are working on",
  "completedSteps": ["step 1", "step 2"],
  "pendingSteps": ["step 3", "step 4"],
  "notes": "anything important for resumption"
}

For multi-step tasks, also write .claude/state/task-{name}.state.json:

{
  "task": "task-name",
  "started": "ISO datetime",
  "lastUpdated": "ISO datetime",
  "steps": [
    { "name": "Step 1", "status": "completed" },
    { "name": "Step 2", "status": "in_progress" }
  ],
  "context": { "branch": "branch-name", "notes": "key info" }
}

3. Consider Committing

If uncommitted work exists and the task is at a safe point:

git add -A && git commit -m "WIP: checkpoint before potential failure"

MCP Save (--mcp flag)

When --mcp is specified, also save structured entities to MCP memory.

Create Entities

Use mcp__memory__create_entities():

entities = [
  {
    name: "Session_2026-01-28_TaskName",
    entityType: "session_context",
    observations: [
      "Working on: [task description]",
      "Completed: [what was done]",
      "Decision: [key choice made]",
      "Files: [files modified]",
      "Next: [pending work]",
    ],
  },
];

Entity Types

TypeUse For
session_contextCurrent work status, progress, next steps
architectural_decisionDesign choices with rationale
bug_investigationDebugging context, findings, hypotheses
feature_implementationFeature details, approach, progress

Naming Conventions

  • Sessions: Session_YYYY-MM-DD_BriefTaskName
  • Decisions: Decision_FeatureName_Choice
  • Bugs: Bug_ComponentName_Issue

Create Relations

Link related entities with mcp__memory__create_relations().

Confirm Save

After saving, report what was preserved:

Saved to MCP memory:
- Session context: [summary]
- Decisions: [count]
To retrieve later: mcp__memory__read_graph()

When to Use

  • Before large file operations
  • Before complex multi-step tasks
  • When session is getting long (50+ tool calls)
  • Periodically during long sessions (every 30-60 minutes)
  • Before risky operations

Compaction Recovery

On resume after compaction:

  1. Read .claude/state/handoff.json
  2. Read any .claude/state/task-*.state.json
  3. If MCP was used: mcp__memory__search_nodes("Session_")
  4. Cross-reference with git log and git status

Version History

VersionDateDescription
1.02026-02-25Initial implementation

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free