How to Back Up Claude Skills and Version AI Workflows

What Are You Actually Backing Up When You Save Agent Skills?

Backing up Claude Skills and AI agent workflows protects months of refined engineering judgment, structured quality assertions, and automated tool integrations. When developers search for backup Claude Skills, the underlying risk is not simply recovering a Markdown snippet; it is preserving the dependable, repeatable behaviors that power autonomous development workflows in Claude Code, Google Antigravity, and OpenAI Codex.

As detailed in the Anthropic Claude Code Overview, agent skills represent modular software capability packages. A complete backup must preserve 3 indispensable layers: the procedural SKILL.md manifest, all supporting execution scripts and references in subdirectories, and the granular Git commit history that explains why constraints were introduced.

Backing up only a top-level Markdown file leaves behind supporting validator scripts, templates, and golden test cases, causing 100% execution failure when the skill attempts to run helper tooling on a restored machine.

The Sprawl Moment: The Cost of Unbacked Skill Libraries

A lead platform architect spends four months engineering a suite of 18 high-precision agent skills across Claude Code, Google Antigravity, and Cursor. These skills automate internal API contract validation, multi-stage AWS infrastructure rollouts, and SOC2 compliance audits. Following an unexpected macOS kernel panic and clean OS reinstallation, the architect discovers that while git repos were preserved on GitHub, all custom skills residing in ~/.claude/skills and ~/.gemini/antigravity/skills were completely wiped. Re-authoring the nuanced prompt heuristics, regular expressions, and edge-case exceptions from memory takes over 30 hours of lost development time, introducing regressions across the entire team's pull request reviews.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Where Are All Your AI Skills Located Across Your Machine?

Before creating a backup archive, you must catalog every local directory where AI agent skills and custom instructions are stored. Modern developers rarely use a single tool; skills often sprawl across multiple agent directories, project-level configurations, and global dotfiles.

Check the following 3 primary filesystem roots on your workstation:

1. Claude Code Skills: Global skills in ~/.claude/skills/ and project-scoped skills in <repo>/.claude/skills/.
2. Google Antigravity Skills: Global skills in ~/.gemini/antigravity/skills/ and workspace skills in <repo>/.gemini/skills/. (See our Google Antigravity skills guide).
3. OpenAI Codex Skills: Global packages in ~/.codex/skills/ and repository rules in AGENTS.md. (See our Codex skills guide).
4. Cursor IDE Rules: Workspace-scoped rule manifests in <repo>/.cursor/rules/*.mdc.

How Do Different Skill Backup Strategies Compare?

Choosing the right backup strategy depends on whether you require quick point-in-time archives, collaborative team version control, or automated multi-agent synchronization across multiple operating systems.

How to Automate Multi-Agent Skill Backups with Shell Scripts

To create an automated, reproducible backup that captures skills across Claude Code, Google Antigravity, and OpenAI Codex, use this POSIX-compliant backup automation script. It generates a compressed, timestamped tarball and automatically stages changes into a dedicated Git repository.

Save the following script as backup-ai-skills.sh and configure it to run via cron or launchd:

#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR="${HOME}/.ai-skill-backups"
TIMESTAMP="$(date +%Y-%m-%d_%H%M%S)"
ARCHIVE_PATH="${BACKUP_DIR}/ai-skills-backup-${TIMESTAMP}.tar.gz"

mkdir -p "${BACKUP_DIR}/staging"

echo "[*] Archiving Claude Code skills..."
[ -d "${HOME}/.claude/skills" ] && cp -R "${HOME}/.claude/skills" "${BACKUP_DIR}/staging/claude-skills"

echo "[*] Archiving Google Antigravity skills..."
[ -d "${HOME}/.gemini/antigravity/skills" ] && cp -R "${HOME}/.gemini/antigravity/skills" "${BACKUP_DIR}/staging/antigravity-skills"

echo "[*] Archiving OpenAI Codex skills..."
[ -d "${HOME}/.codex/skills" ] && cp -R "${HOME}/.codex/skills" "${BACKUP_DIR}/staging/codex-skills"

echo "[*] Compressing backup archive..."
tar -czf "${ARCHIVE_PATH}" -C "${BACKUP_DIR}/staging" .
rm -rf "${BACKUP_DIR}/staging"

echo "[+] Successfully created skill backup: ${ARCHIVE_PATH}"

Refer to the official Git Documentation for best practices on structuring semantic commit messages when pairing local archive scripts with remote repository tracking.

How Do You Test and Verify a Skill Backup Before Disaster Strikes?

An untested backup is merely an assumption of safety. To guarantee that your AI agent skills will perform flawlessly following a machine migration or disk failure, execute this 5-point disaster recovery checklist in an isolated sandbox environment.

1. Step 1: Extract into a Clean Staging Directory. Extract the archive into a temporary folder (e.g. /tmp/skill-restore-test) to verify archive integrity.
2. Step 2: Verify Multi-File Hierarchy. Confirm that all scripts/, references/, and examples/ directories are intact and have appropriate read/execute permissions (chmod +x).
3. Step 3: Validate YAML Manifests. Check that all SKILL.md files parse valid YAML frontmatter without syntax errors or broken indentation.
4. Step 4: Execute a Dry-Run Agent Invocation. Launch Claude Code or Google Antigravity pointing to the restored directory and invoke the skill against a sample codebase.
5. Step 5: Assert Expected Output Shape. Confirm that the agent follows the specified rubric, runs helper scripts without missing dependency errors, and produces deterministic results.

Common Mistakes to Avoid When Backing Up Agent Skills

Avoid these common pitfalls that undermine skill recovery workflows:

• Single-File Copying: Copying only SKILL.md strips supporting Python scripts, Markdown references, and golden schemas.
• Storing Sensitive Credentials in Skills: Never hardcode API keys or database connection strings inside skill scripts; use environment variables or MCP servers instead.
• Neglecting Cross-Tool Portability: Avoid agent-specific proprietary syntax inside SKILL.md so instructions run interchangeably across Claude Code, Antigravity, and Codex.
• Relying on Manual Exports: Manual exports quickly go out of date. Use automated two-way synchronization to ensure changes are preserved in real time.

Related Resources and Next Steps

Explore the complete library of skill management guides on the Prompttly Resources Hub. Read our companion guides on Google Antigravity skills, why AI power users need a skill manager, updating Claude skills safely, and syncing skills across computers.

To stop worrying about manual backups, automatically version your library across Claude Code, Google Antigravity, and Codex, and summon any prompt in 500ms with a global hotkey, explore Prompttly Plans or download the Prompttly Mac App.

Frequently Asked Questions About Backing Up AI Agent Skills