Config Backup

Config Backup Skill

This skill helps users backup their Claude Code configuration files from ~/.claude/ to a specified target directory. It copies the commands/, skills/, and agents/ directories with options for selective backup.

What Gets Backed Up

By default, this skill backs up three directories from ~/.claude/:

• commands/ - All slash command definitions
• skills/ - All agent skills and their resources
• agents/ - All subagent definitions

These are the user-created configurations that define custom Claude Code behavior.

When to Use This Skill

Use this skill when users want to:

• Backup Claude configurations before making changes
• Copy configurations to another machine or project
• Share custom setup with others
• Migrate to a new system
• Version control configurations

Backup Workflow

Follow this workflow when performing a backup:

1. Confirm Target Directory

Always confirm the target directory, even though the default is the current working directory. Ask like this:

"Target directory: [current-working-directory]
Is this correct, or would you like to specify a different location?"

Wait for user confirmation before proceeding.

2. Select Directories to Backup

Ask the user which directories to include. Present this interactive prompt:

"Which directories would you like to backup?
- commands/
- skills/
- agents/

Backup all three, or specify which ones to include?"

If the user doesn't specify, backup all three. If they specify a subset, only backup those.

3. Execute the Backup Script

Use the backup script located at scripts/backup.sh within this skill directory. Execute it with appropriate parameters:

~/.claude/skills/config-backup/scripts/backup.sh [target-dir] [directories...]

Parameters:

• target-dir: Target directory (default: current directory if not specified)
• directories...: Space-separated list of directories to backup (commands, skills, agents)

The script will:

• Create target directory if it doesn't exist
• Use rsync if available (efficient copying), otherwise fallback to cp -r
• Overwrite existing files without prompting
• Preserve directory structure
• Exit with error if source ~/.claude/ doesn't exist

4. Report Results

After the backup completes, show the user a detailed list of what was copied:

✅ Backup complete!

Copied directories:
- commands/ (15 files)
- skills/ (8 directories, 42 files)
- agents/ (23 files)

Target: /path/to/target/directory

If any errors occurred during the backup (permission errors, missing source, etc.), report them clearly to the user.

Error Handling

The backup script handles these scenarios:

Target Directory Doesn't Exist

Creates the directory automatically. No user action needed.

Source Directory Missing

If ~/.claude/ doesn't exist, the script exits with error message:

❌ Error: Source directory ~/.claude/ not found

No Write Permissions

If target directory isn't writable, shows:

❌ Error: Permission denied writing to [target-dir]

rsync Not Available

Automatically falls back to cp -r command. User sees:

⚠️ rsync not available, using cp instead

Examples

Example 1: Backup All Directories to Current Location

User: "save my claude settings"

Assistant: "I'll backup your Claude configurations.

Target directory: /Users/choi/work/claude-config Is this correct, or would you like to specify a different location?

Which directories would you like to backup?

• commands/
• skills/
• agents/

Backup all three, or specify which ones to include?"

[User confirms]

[Executes backup, reports results]

Example 2: Backup Only Commands and Skills

User: "backup my commands and skills"

[Asks about target directory, then only backs up commands/ and skills/]

Example 3: Specify Custom Target

User: "copy ~/.claude to ~/backups/claude-config"

[Asks for confirmation, then backs up to ~/backups/claude-config]

Best Practices

• Always confirm target directory before copying to avoid accidental overwrites
• Show clear feedback about what was copied so user knows backup succeeded
• Handle errors gracefully with helpful error messages
• Use rsync when available for efficient incremental backups
• Preserve structure so restore is straightforward
• Overwrite without asking per user requirements (user should confirm target upfront)

Technical Details

Script Location

The backup script is at: ~/.claude/skills/config-backup/scripts/backup.sh

Copy Method

• Prefers rsync -av --delete for efficient copying with deletion of orphaned files
• Falls back to cp -rf if rsync unavailable
• Always preserves permissions and timestamps
• Creates target directories as needed with mkdir -p

Directory Structure

The backup preserves this structure:

target-dir/
├── commands/
│   ├── command1.md
│   └── command2.md
├── skills/
│   ├── skill1/
│   └── skill2/
└── agents/
    ├── agent1.md
    └── agent2.md

See Also

• Troubleshooting common issues: references/troubleshooting.md
• Detailed backup workflow examples: examples/backup-workflows.md
• The backup script implementation: scripts/backup.sh
• Claude Code skill documentation for skill structure
• Advanced usage: Pipe backup to tar for archiving, sync to remote with rsync over ssh