agentleFS
ainullmainullm/agent-checkpoint/SKILL.md

agent-checkpoint

Skill3 starsChanged 39 days agoMITView on GitHub

Ultra-efficient, zero-data-loss pre-edit snapshotting, SemVer classification, and token-optimized dual-ledger audit trail (v2.0) for autonomous AI coding agents. Triggers on: agent-checkpoint, checkpoint, snapshot, audit trail, versioning, edit file, refactor, trackback, history, revision log, rollback, diff version.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. hwl668/Agentcheckpoint★ 2same name
    2. NexaiGuy/nex-ai-skills★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Zero Data Loss (Pre-Edit Archiving): Never modify, refactor, or overwrite an existing file without archiving its exact prior state.

    line 16
  2. Very specific:

    Every tracked file receives its own isolated directory inside .snapshots/ matching its relative project path:

    line 18
  3. Very specific:

    If bucket or file does not exist: treat as initial version (v1.0.0).

    line 63
  4. Very specific:

    If exists: read latest version from the local manifest.json (< 40 tokens).

    line 64
  5. Very specific:

    Ensure directory .snapshots/<filepath>/ exists.

    line 72
  6. Distinctive:

    When requested to review or compare past revisions:

    line 95
  7. Very specific:

    Read .snapshots/<filepath>/manifest.json to identify available snapshot versions.

    line 96
  8. Distinctive:

    When requested to revert or restore an earlier version:

    line 104

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Agent-Checkpoint Protocol (v2.0 Turbo)

A universal, zero-dependency safety and provenance protocol for autonomous AI coding and research agents, optimized for minimum token consumption and clean hierarchical storage.

Core Directives

  1. Zero Data Loss (Pre-Edit Archiving): Never modify, refactor, or overwrite an existing file without archiving its exact prior state.
  2. Hierarchical File Bucketing (Clean Storage): Every tracked file receives its own isolated directory inside .snapshots/ matching its relative project path:
    .snapshots/<relative_filepath>/
    ├── manifest.json            # Sharded local index (< 40 tokens read)
    ├── v1.0.0.<ext>             # Pristine pre-edit snapshot
    └── v1.1.0.<ext>
  3. Sliding Window Retention ($K = 5$ Versions Max): To strictly bound disk space, each file bucket retains at most 5 latest snapshot versions. When creating version 6, the agent automatically prunes the oldest physical snapshot file and updates the bucket's manifest.json.
  4. Token-Optimized Dual-Ledger Synchronization:
    • Sharded Local Index (.snapshots/<filepath>/manifest.json): AI reads only this file's version state ($O(1)$ token overhead: ~30–50 tokens), avoiding global scans.
    • Micro-Changelog Stream (REVISION_LOG.md): Append-only compact table stream. Never re-read previous log history into context.
  5. Universal Scope & Guardrails:
    • Full text/code coverage across 100+ extensions (.py, .ts, .go, .rs, .cpp, .md, .json, .yaml, etc.).
    • Tabular files (.csv, .tsv, .jsonl) are snapshotted ONLY if $\le 1\text{ MB}$. Files $> 1\text{ MB}$ log metadata only.
    • Strictly exclude binary models (.pt, .onnx, .safetensors), archives (.zip), and caches (node_modules/, venv/, __pycache__/, .git/).

Standard Directory Layout

[Project_Root]/
├── .snapshots/                          # Historical snapshots directory
│   ├── auth_service.py/                 # Isolated bucket per file
│   │   ├── manifest.json                # Local version registry (< 40 tokens)
│   │   ├── v1.0.0.py                    # Archived pre-edit snapshot
│   │   └── v1.1.0.py
│   └── src/routes/api.ts/               # Preserves nested structure
│       ├── manifest.json
│       └── v1.0.0.ts
├── REVISION_LOG.md                      # Append-only compact Markdown table
├── auth_service.py                      # Active working file
└── src/routes/api.ts

Operating Procedures (SOP)

Workflow 1: File Modification & Checkpointing (Fast-Path)

Whenever instructed to modify, refactor, or update an existing file:

  1. Step 1: Check Local Bucket (.snapshots/<filepath>/manifest.json)
    • If bucket or file does not exist: treat as initial version (v1.0.0).
    • If exists: read latest version from the local manifest.json (< 40 tokens).
  2. Step 2: Classify SemVer Impact
    • MAJOR: Breaking architectural shift, interface overhaul.
    • MINOR: Additive features, new endpoints/functions.
    • PATCH: Bug fix, refactor, parameter tuning, typo.
  3. Step 3: Capture Pre-Edit Snapshot & Apply Retention ($K \le 5$)
    • Ensure directory .snapshots/<filepath>/ exists.
    • Copy current active file to .snapshots/<filepath>/v<OLD_VERSION>.<ext>.
    • Sliding Window Check: If total snapshot files in bucket $> 5$, delete the oldest snapshot.
  4. Step 4: Apply Modification to Active File
    • Apply user's requested edit on the active file.
  5. Step 5: Synchronize Dual-Ledger (Micro-Log Stream)
    • Update .snapshots/<filepath>/manifest.json:
      [
        {"version": "v1.1.0", "snapshot": "v1.0.0.py", "impact": "MINOR", "ts": "2026-10-07T03:45:00+07:00", "summary": "Added JWT refresh token"}
      ]
    • Append 1 line to REVISION_LOG.md without reading previous entries:
      | 2026-10-07 03:45 | v1.1.0 | MINOR | auth_service.py | v1.0.0.py | Added JWT refresh token |

Workflow 2: Deep Trackback & Semantic Diff

When requested to review or compare past revisions:

  1. Read .snapshots/<filepath>/manifest.json to identify available snapshot versions.
  2. Load target snapshot (e.g. .snapshots/<filepath>/v1.0.0.<ext>) and active file.
  3. Present concise Before vs After comparison highlighting algorithmic or interface changes.

Workflow 3: Instant Rollback / Recovery

When requested to revert or restore an earlier version:

  1. Locate target snapshot in .snapshots/<filepath>/v<TARGET_VERSION>.<ext>.
  2. Take safety snapshot of the current state (ensuring work-in-progress is never lost).
  3. Overwrite active file with content from the snapshot.
  4. Append 1-line rollback event to REVISION_LOG.md.

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.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

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.