Skip to content

Sync, Versioning & Rollback

This guide covers three related concepts: syncing artifacts with upstream sources, pinning versions via lock files to ensure consistency, and rolling back to a previous state when needed. Together, these tools help you keep your artifact collection organized, versioned, and recoverable.

Overview

SkillMeat manages artifact updates across three coordinated systems:

Sync — Keep artifacts in your collection up-to-date with upstream sources (GitHub, marketplace, or other collections). Detect when your project differs from your collection (drift), preview changes, and apply them safely.

Versioning — Every change to an artifact creates a new immutable version. The manifest file pins versions (@latest, @v1.2.0, @abc1234), and the lock file records exactly what was installed. This guarantees reproducibility.

Rollback — Restore artifacts or entire collections to a previous state. Rollbacks create new versions (non-destructive), preserving your complete audit trail.

Walkthroughs available

See the Existing Project Migrant Walkthrough for migration and sync workflows, or the ML Engineer Walkthrough for advanced reproducibility patterns.

Prerequisites

Concept: Sync, Drift & Deployment Metadata

What is Drift?

Drift occurs when three versions of an artifact differ:

  1. Collection version — The artifact in your SkillMeat collection
  2. Project version — The artifact deployed in your project
  3. Deployed baseline — The version that was deployed (recorded in .skillmeat-deployed.toml)

SkillMeat tracks drift using the deployment metadata file (.claude/.skillmeat-deployed.toml in each project). This file records:

[[deployed]]
artifact_name = "my-skill"
artifact_type = "skill"
from_collection = "default"
deployed_at = "2025-12-17T10:30:00.000000"
artifact_path = "skills/my-skill"
content_hash = "abc123def456789..."

The content_hash acts as a baseline. When SkillMeat detects changes, it compares:

  • Has the collection changed? (new hash ≠ deployed hash)
  • Has your project changed? (new hash ≠ deployed hash)
  • Both changed? (both hashes differ from baseline)

This determines whether you have an outdated, modified, or conflicting artifact.

Drift Types

Drift Type Means Recommendation
No drift Project matches deployed version No action needed
Outdated Collection has a newer version than deployed Sync upstream (push strategy)
Modified Project files differ from deployed version Review local changes or overwrite with collection
Conflict Both collection and project have changes Merge manually or choose strategy (merge, overwrite, fork)

Sync Operations

Step 1: Check for Drift

Start by detecting what's out of sync in your project.

# Check drift in current directory
skillmeat sync check .

# Or specify a project path
skillmeat sync check /path/to/project

# Output shows detected artifacts
# No drift detected. Project is in sync.

Detailed output: 

skillmeat sync check /path/to/project --verbose

# Drift Detection Results: 3 artifacts
#
# Artifact       Type     Drift Type              Recommendation
# ────────────────────────────────────────────────────────────────
# canvas         skill    UPSTREAM_CHANGED        SYNC_UPSTREAM
# pdf-extractor  skill    MODIFIED_LOCALLY        REVIEW_CHANGES
# code-reviewer  command  NO_DRIFT                NO_ACTION

  1. Navigate to Projects page
  2. Open your target project
  3. Go to the Artifacts tab
  4. The Sync Status section shows drift for each deployed artifact:
  5. Green ✓: No drift
  6. Blue ↑: Upstream changed (new version available)
  7. Orange ⚠: You modified locally
  8. Red ✕: Conflicting changes
  9. Hovering over each artifact shows detailed drift information

Step 2: Preview Changes

Before syncing, preview exactly what will change.

# Preview all drifts
skillmeat sync preview /path/to/project

# Output shows affected artifacts
# Sync Preview: /path/to/project
#
# canvas (skill)
#   Status: WOULD_SYNC
#   Changes: 12 additions, 5 deletions
#   Files: +2, -1, M 3
#
# pdf-extractor (skill)
#   Status: WOULD_CONFLICT
#   Details: Local and upstream both modified
#   Action: Requires manual merge

# Preview specific artifacts
skillmeat sync preview /path/to/project canvas pdf-extractor

# Get detailed diff
skillmeat sync preview /path/to/project canvas --show-diff
  1. Open the project's Artifacts tab
  2. Click on any artifact with drift status
  3. The Diff Panel opens showing:
  4. Left side: current version (project)
  5. Right side: incoming version (collection)
  6. Green highlights: added lines
  7. Red highlights: removed lines
  8. Blue highlights: modified lines
  9. Scroll through the diff to understand changes
  10. For conflicts (red badges), review the conflict markers to understand both approaches

Step 3: Choose a Sync Strategy

When syncing, you choose how to handle changes:

Strategy: overwrite (Collection Wins)

Replace project version with collection version. Loses local changes.

# Sync with overwrite (collection replaces project)
skillmeat sync pull /path/to/project --strategy overwrite

# For non-interactive use, add --force
skillmeat sync pull /path/to/project --strategy overwrite --force
  1. In the Diff Panel, click Sync Options dropdown
  2. Select "Overwrite (use collection version)"
  3. Click Apply Sync
  4. Confirm in the dialog

Use when: - Collection is your source of truth - Local changes are temporary or experimental - You want clean, unambiguous updates

Strategy: merge (Auto-Merge Changes)

Attempt 3-way merge: combine non-conflicting changes from both sides. Conflicts require manual resolution.

# Sync with merge strategy
skillmeat sync pull /path/to/project --strategy merge

# If conflicts occur, markers appear in files
# Resolve manually, then re-sync
skillmeat sync pull /path/to/project canvas
  1. In the Diff Panel, click Sync Options dropdown
  2. Select "Merge (combine changes)"
  3. Click Apply Sync
  4. If conflicts occur:
  5. Files with <<<<<< LOCAL ... ======= ... >>>>>>> UPSTREAM markers appear
  6. Edit files to resolve (pick one side or merge both)
  7. Remove conflict markers
  8. Click Confirm Resolve in the UI

Use when: - Both sides have valid changes - You want to preserve local modifications - Conflicts can be resolved intelligently

Strategy: fork (Create Variant)

Keep both versions separate. Creates artifact-fork with project's version, leaves collection unchanged.

# Sync with fork strategy
skillmeat sync pull /path/to/project --strategy fork

# Result: original artifact + artifact-fork
skillmeat list --collection default | grep canvas
# canvas
# canvas-fork
  1. In the Diff Panel, click Sync Options dropdown
  2. Select "Fork (keep both versions)"
  3. Click Apply Sync
  4. Both versions now exist in your collection

Use when: - Versions diverged significantly - You need both variants - You'll decide later which to keep

Step 4: Apply Sync

Once you've chosen a strategy, apply it.

# Sync specific artifacts
skillmeat sync pull /path/to/project canvas

# Sync multiple artifacts
skillmeat sync pull /path/to/project canvas pdf-extractor

# Sync all drifted artifacts (prompts for each)
skillmeat sync pull /path/to/project

# Non-interactive: apply strategy to all
skillmeat sync pull /path/to/project --strategy merge --force
  1. For each drifted artifact with Drift status, click the artifact row
  2. Diff Panel opens
  3. Click Sync Options → choose strategy
  4. Click Apply Sync
  5. Status updates to "✓ Synced"

Step 5: Verify Sync

After syncing, verify the results.

# Re-check drift (should show no drift)
skillmeat sync check /path/to/project
# Output: No drift detected. Project is in sync.

# If merge created conflicts, inspect resolved files
cat /path/to/project/.claude/skills/canvas/SKILL.md
# Should show no conflict markers (if resolved)
  1. Return to Artifacts tab
  2. Verify Drift Status is now ✓ (green)
  3. If conflicts were resolved, artifact status shows "Synced"
  4. If unresolved conflicts remain, artifact status shows "⚠ Manual Review Required"

Version Management

Manifest: Pinning Versions

The manifest file (~/.skillmeat/collection/manifest.toml or ./.claude/.skillmeat-manifest.toml for project scopes) specifies which versions you want:

[tool.skillmeat]
version = "1.0.0"

[[artifacts]]
name = "canvas"
type = "skill"
source = "anthropics/skills/canvas"
version = "@latest"          # Always use the latest version

[[artifacts]]
name = "pdf-extractor"
type = "skill"
source = "user/repo/pdf"
version = "@v1.2.0"          # Pin to specific version tag

[[artifacts]]
name = "custom-skill"
type = "skill"
source = "local/path"
version = "@abc1234def5"     # Pin to specific commit SHA

Lock File: Recording Exact Installs

The lock file (.skillmeat.lock.toml) records exactly what was installed, including resolved SHAs and timestamps. This ensures reproducibility.

[lock]
version = "1.0.0"

[lock.entries.canvas]
source = "anthropics/skills/canvas"
version_spec = "@latest"
resolved_version = "v2.1.0"        # What @latest resolved to
resolved_sha = "abc123def456..."   # Exact commit hash
locked_at = "2025-12-17T10:30:00Z"

[lock.entries.pdf-extractor]
source = "user/repo/pdf"
version_spec = "@v1.2.0"
resolved_version = "v1.2.0"
resolved_sha = "xyz789abc123..."
locked_at = "2025-12-15T09:15:00Z"

Version Syntax

  • @latest — Always fetch the newest version (default)
  • @v1.2.0 — Use specific version tag (GitHub release/tag)
  • @abc1234 — Use specific commit SHA (Git commit hash)
  • Omit @ — Defaults to @latest

Pin a Specific Version

Lock an artifact to a specific version so sync and update won't automatically pull newer versions.

# Pin to a specific version tag
skillmeat pin canvas @v1.2.0

# Pin to a specific commit
skillmeat pin canvas @abc1234def5

# Update manifest (manual)
# Edit ~/.skillmeat/collection/manifest.toml:
# version = "@v1.2.0"  # instead of @latest

# Lock file updates on next sync
skillmeat sync --collection default
  1. Navigate to Artifacts → Open artifact details
  2. Go to Version History tab
  3. Find the version you want to pin
  4. Click Pin Version
  5. Manifest updates to pin this version
  6. Future syncs won't pull newer versions

Update to a Newer Version

Unpin an artifact to allow updates, or explicitly pin a newer version.

# Unpin (return to @latest)
skillmeat pin canvas @latest

# Or pin to a new specific version
skillmeat pin canvas @v2.0.0

# Update lock file
skillmeat sync --collection default
  1. Navigate to Artifacts → Open artifact details
  2. Go to Version History tab
  3. Find the new version you want
  4. Click Unpin Version (if pinned), or click Pin to This Version
  5. Click Apply and the lock file updates

Verify Version Pins

Check what versions are pinned in your manifest and lock file.

# View manifest (pins)
cat ~/.skillmeat/collection/manifest.toml

# View lock file (resolved versions)
cat ~/.skillmeat/collection/.skillmeat.lock.toml

# Compare source version with resolved version
skillmeat status --collection default
  1. Artifacts page → Open any artifact
  2. Version History tab shows:
  3. Pinned Version label (if pinned)
  4. Current Version badge (what's deployed)
  5. Timeline of all versions

Rollback Procedures

Rollback restores an artifact or entire collection to a previous state. Rollbacks are always safe and non-destructive — they create new versions, preserving your complete history.

Rollback a Single Artifact

Restore one artifact to a previous version.

# List all versions of an artifact
skillmeat history canvas --collection default

# Output shows versions with timestamps and content hashes
# Version v2.1.0 (2025-12-18T10:30:00Z)
# Version v2.0.0 (2025-12-15T09:15:00Z)
# Version v1.5.0 (2025-12-01T14:22:00Z)

# Restore to a specific version
skillmeat restore canvas @v2.0.0 --collection default

# Or restore by timestamp
skillmeat restore canvas --as-of 2025-12-15T09:15:00Z

# Verify restore (creates new version)
skillmeat history canvas --collection default
# Shows original versions + new restored version
  1. Artifacts page → Open artifact details
  2. Version History tab
  3. Find the version you want to restore to
  4. Click Restore to This Version
  5. Diff Preview appears showing changes
  6. Review the preview carefully
  7. Click Confirm Restore
  8. New version created with restored content

Restore Impact

Restoring an artifact does NOT automatically redeploy it to projects. After restore: 1. Artifact gains a new version in the collection 2. Projects keep their current deployed version 3. You can sync projects to pull the restored version if needed

Rollback Entire Collection

Restore the entire collection to a previous snapshot.

# List snapshots
skillmeat snapshot list --collection default

# Output shows snapshots with descriptions
# Snapshot ID: snap-abc123 (2025-12-18 10:30)
#   Description: "Before cleanup"
#   Artifacts: 12
# Snapshot ID: snap-xyz789 (2025-12-15 09:15)
#   Description: "After upgrade"
#   Artifacts: 11

# Restore to a snapshot
skillmeat snapshot restore snap-abc123 --collection default

# Verify restoration
skillmeat list --collection default
  1. Settings → Collection Management
  2. Snapshots tab
  3. Find the snapshot you want to restore
  4. Click Restore This Snapshot
  5. Summary Preview shows what will change:
  6. Artifacts added
  7. Artifacts removed
  8. Artifacts modified
  9. Click Confirm Restore
  10. Collection reverts to that snapshot state

Snapshot Creation

Create snapshots before major changes: 

skillmeat snapshot create "Before cleanup" --collection default

Verify Rollback

After rollback, verify the collection state.

# List artifacts
skillmeat list --collection default

# Verify specific artifact
skillmeat show canvas --collection default

# Check that old version is now current
skillmeat history canvas --collection default | head -5
  1. Artifacts page shows updated collection
  2. Click any artifact to view Version History
  3. New "Restored" version appears in timeline
  4. Old versions still visible (non-destructive)

Recovery from Failed Sync/Deploy

If sync or deployment fails, use these recovery steps:

Problem: Sync Created Conflict Markers I Can't Resolve

Recovery:

# Option 1: Restore to state before sync
skillmeat restore artifact @v_before_sync

# Option 2: Use fork strategy instead
skillmeat sync pull /path/to/project --strategy fork

# Option 3: Manually revert project files
# Inspect .skillmeat-deployed.toml to see baseline hash
cat /path/to/project/.claude/.skillmeat-deployed.toml

# Restore from collection to project
skillmeat deploy artifact --to /path/to/project --force
  1. Go to artifact Version History
  2. Find version before the failed sync
  3. Click Restore to This Version
  4. Confirm restore
  5. Redeploy to project

Problem: Accidentally Synced with Wrong Strategy (Lost Local Changes)

Recovery:

# View version history
skillmeat history artifact --collection default

# Find the version with your local changes
# (Look for timestamps before the sync)

# Restore to that version
skillmeat restore artifact @v_with_local_changes

# Now you have your local changes back
skillmeat list --collection default
  1. Open artifact Version History
  2. Scroll to find version with your changes (check timestamps)
  3. Click Restore to This Version
  4. Confirm

Problem: Project and Collection Completely Out of Sync

Recovery:

# Full re-sync with explicit strategy

# Step 1: Check what drifted
skillmeat sync check /path/to/project --verbose

# Step 2: Preview
skillmeat sync preview /path/to/project

# Step 3: Choose strategy and force
# Use merge to preserve both sides
skillmeat sync pull /path/to/project --strategy merge --force

# Step 4: Resolve any conflicts manually
# Files with conflict markers need manual editing

# Step 5: Verify
skillmeat sync check /path/to/project
  1. Projects → Open project
  2. Artifacts tab shows all drifts
  3. For each drifted artifact:
  4. Click to open Diff Panel
  5. Choose strategy (Merge recommended)
  6. Apply Sync
  7. If conflicts appear, resolve manually
  8. After all artifacts synced, Drift Status shows ✓

Next Steps