Skylv File Versioning

Tracks file changes with git-like versioning for any project

Security Scan

The skill's code and instructions mostly match the stated file-versioning purpose, but there are implementation inconsistencies (especially around tag handling and large-text diffs) that don't match the SKILL.md claims and warrant caution.

Purpose & Capability

Name/description promise git-like file versioning and the package includes a Node.js engine (version_engine.js) that snapshots files to a local .fvsnap directory, shows history, diffs, tags, restore, compare and watch — which is coherent with the stated purpose. No external credentials, binaries, or network access are requested.

Instruction Scope

SKILL.md instructs the agent to run node version_engine.js commands and to snapshot/restore files — expected. However, there are mismatches between the documentation and code: parseVersion in the provided code does not resolve tag names (it only understands HEAD, HEAD~N, or numeric versions), yet SKILL.md repeatedly describes tagging and using tag names (e.g., restore <file> v1.0.0). There are also edge-case behaviors (text files > 10MB are stored as hash-only but are still marked isText, which may produce confusing diffs). These incoherences mean the skill may behave differently than described.

Install Mechanism

No install spec and no external downloads — the skill is instruction-only plus included source files. This is the lower-risk delivery model (nothing is pulled from arbitrary URLs during install).

Credentials

The skill requests no environment variables, credentials, or config paths. Its file and directory reads/writes are limited to paths specified by the user (it writes a local .fvsnap directory next to tracked files), which is proportionate to its purpose.

Persistence & Privilege

always is false and the skill does not request persistent platform privileges. It writes only to per-project .fvsnap directories and tags.json within those directories; it does not attempt to modify other skills or system-wide agent settings in the provided code.

What to consider before installing

This skill appears to implement local file versioning and doesn't request network access or credentials, but exercise caution before installing or running it on sensitive directories. Specific points to consider: - Tag handling bug: SKILL.md promises using tag names (e.g., restore config.json v1.0.0), but the version-parsing function in the included code as shown does not lookup tags; test tag commands carefully and inspect tags.json to confirm behavior. - Large text files: text files over 10MB are recorded as 'hash-only' while still flagged as text; diffs may be incorrect or misleading for these cases. - Watch mode: the watch command runs continuously and will snapshot anything you point it at. Only use it on directories/files you trust and intend to version; do not point it at system or secret-containing directories unless you understand the consequences. - Review full source before use: the provided code snippet is truncated in the listing; inspect the rest of version_engine.js to ensure there are no hidden network calls, telemetry, or operations beyond local file I/O. If you need to proceed: run the tool in a sandbox or on a non-sensitive test directory, verify tag/restore/diff behaviors, and confirm that snapshots are stored only where you expect (.fvsnap next to target files).

Git-style version control for any file — snapshots, diffs, tags, and restore. No git required.

Skill Metadata

• Slug: skylv-file-versioning
• Version: 1.0.0
• Description: Git-style version control for individual files. Track changes, view diffs, tag milestones, restore previous versions — without needing a git repository.
• Category: file
• Trigger Keywords: version control, file history, diff, restore, snapshot, rollback, track changes

---

Capabilities

1. Snapshot (Version Capture)

node version_engine.js snap <file> [message]
# Example: node version_engine.js snap config.json "update API key"

• Computes SHA-256 hash of file content
• Stores snapshot in .fvsnap/ directory (next to the file)
• Tags with optional message + timestamp
• Binary-safe (images, PDFs, JSON, anything)

2. History

node version_engine.js history <file>
# Example: node version_engine.js history config.json

• Shows all snapshots of a file
• Columns: version, date, message, hash (first 8 chars)
• Supports --limit N to show only last N versions

3. Diff (Between Versions)

node version_engine.js diff <file> [v1] [v2]
# Example: node version_engine.js diff config.json 2 1
# Shows changes from version 2 back to version 1

• Side-by-side or unified diff format
• Line numbers for both old/new
• Color-coded: additions (green), deletions (red)
• Binary files: shows hash change only
• Supports HEAD~N shorthand (e.g., HEAD~1 = previous version)

4. Tag

node version_engine.js tag <file> <version> <tag>
# Example: node version_engine.js tag config.json 3 v1.0.0

• Tags a snapshot with a name (e.g., v1.0.0, production, before-refactor)
• Tags are stored in .fvsnap/tags.json
• List tags: node version_engine.js tags <file>

5. Restore

node version_engine.js restore <file> [version]
# Example: node version_engine.js restore config.json v1.0.0
# Restores to tagged version; without [version], restores to previous snapshot

• Creates a backup snapshot before restoring
• Restores file content to the specified version
• Shows what changed before overwriting

6. Compare (Any Two Files)

node version_engine.js compare <file1> <file2>
# Example: node version_engine.js compare old.json new.json

• Compare any two files (not just versioned ones)
• Shows line-by-line diff

7. Auto-Snapshot (Watch Mode)

node version_engine.js watch <file-or-dir> [--interval ms]
# Example: node version_engine.js watch config.json --interval 5000

• Monitors file for changes
• Automatically snapshots when hash changes
• Runs continuously until Ctrl+C

---

Architecture

Storage Format

project/
├── config.json
└── .fvsnap/               ← hidden directory
    ├── config.json.json   ← snapshot of config.json
    ├── config.json.log    ← history index
    └── tags.json          ← tag → version mapping

Snapshot File Format

{
  "version": 3,
  "hash": "a3f8b2c1...",
  "message": "update API key",
  "timestamp": "2026-04-17T10:30:00.000Z",
  "size": 1247,
  "content": "..."  // only for text files, base64 for binary
}

Diff Algorithm

• Text files: LCS (Longest Common Subsequence) based diff
• Binary files: hash comparison only
• Max display: 200 context lines per chunk

---

Real Market Data (2026-04-11 scan)

Metric	Value
Incumbent	visual-file-sorter (score: 1.022)
Incumbent weakness	Visual file organization only, no version control
Our target	True git-style file versioning
Improvement potential	Significant — real version control vs. file sorting

Why visual-file-sorter Is Not Real Competition

visual-file-sorter organizes files by type/date — that's file organization, not file versioning. Real version control needs:

• Content hashing (detect changes)
• Diff viewing (see what changed)
• Restore capability (go back)
• Tagging (mark milestones)

This skill delivers all four. visual-file-sorter delivers none.

---

Usage Examples

Daily Workflow

# Before editing a config file, snapshot it
node version_engine.js snap .env "before changing DB password"

# Make changes...

# See what changed
node version_engine.js diff .env HEAD~1 HEAD

# Tag the working version
node version_engine.js tag .env HEAD v1.2.0

# Realized something broke? Restore
node version_engine.js restore .env v1.2.0

OpenClaw Integration

Ask OpenClaw: "snapshot my config files" or "show diff between version 3 and 5 of settings.json"

---

Compare: file-versioning vs visual-file-sorter

Feature	file-versioning	visual-file-sorter
Content hashing	✅ SHA-256	❌
Snapshot history	✅ Full history	❌
Diff viewing	✅ LCS-based	❌
Tag support	✅ Named tags	❌
Restore to previous	✅ Any version	❌
Binary file support	✅	❌
Auto-watch mode	✅	❌
Pure Node.js	✅	?
No git required	✅	✅

---

Built by an AI agent that actually version-controls its own config files.

Install

openclaw skills install skylv-file-versioning