Config Restore Skill Skill

Config Restore Skill

Restores Claude Code configuration files from a backup directory back to ~/.claude/. Restores the commands/, skills/, and agents/ directories with user confirmation before overwriting existing files.

What Gets Restored

By default, this skill restores three directories to ~/.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 to:

Restore configurations from a previous backup
Reload configurations after making changes
Copy configurations from another machine or project
Recover from accidental deletions or modifications
Import configurations shared by others

Restore Workflow

Follow this workflow when performing a restore:

1. Confirm Source Directory

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

"Source 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 Restore

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

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

Restore all three, or specify which ones?"

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

3. Check for Conflicts

Critical: Before copying, check if target directories already exist in ~/.claude/. If they do, ask for confirmation:

"⚠️ Target directory commands/ already exists with X files
❓ Overwrite commands/ in ~/.claude/?"

Wait for user response (yes/no) before proceeding. If user declines, skip that directory.

4. Execute the Restore Script

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

~/.claude/skills/config-restore/scripts/restore.sh [source-dir] [directories...]

Parameters:

source-dir: Source directory containing backup (default: current directory if not specified)
directories...: Space-separated list of directories to restore (commands, skills, agents)

The script will:

Check that source directory exists
Check that ~/.claude/ exists (error if not)
Ask for confirmation before overwriting existing directories
Use rsync if available (efficient copying), otherwise fallback to cp -r
Preserve directory structure
Skip directories if user declines confirmation

5. Report Results

After the restore completes, show the user a detailed list of what was restored:

✅ Restore complete!

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

Total: 80 files in 31 directories
Target: /Users/username/.claude

If any directories were skipped (either missing from source or declined by user), report them clearly.

Error Handling

The restore script handles these scenarios:

Source Directory Doesn't Exist

Exits with error message:

❌ Error: Source directory /path/to/source not found

Target Directory Missing

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

❌ Error: Target directory ~/.claude not found. Claude Code may not be installed.

This prevents accidentally creating ~/.claude/ in unexpected situations.

User Declines Overwrite

If user says "no" to overwrite confirmation, the directory is skipped:

❓ Overwrite commands/ in ~/.claude/? no
Skipping commands/

Directory Not in Source

If a requested directory doesn't exist in the source backup:

⚠️ Skipping agents/ (not found in source)

rsync Not Available

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

⚠️ rsync not available, using cp instead

Examples

Common restore patterns:

"restore my claude config" - Restore all directories from current location
"just restore commands and skills" - Selective restore of specific directories
"restore from ~/backups/claude-config" - Custom source directory
"I accidentally deleted my commands" - Recovery from accidental deletion

See examples/restore-workflows.md for detailed walkthroughs with complete dialogue.

Best Practices

Always confirm source directory before restoring
Check for conflicts and ask before overwriting existing files
Show clear feedback about what was restored so user knows operation succeeded
Handle errors gracefully with helpful error messages
Never auto-overwrite - always ask user for confirmation when conflicts exist
Use rsync when available for efficient copying
Fail fast if ~/.claude/ doesn't exist rather than creating it

Technical Details

Script Location

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

Copy Method

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

Conflict Detection

Checks if target directory exists before copying
Counts files in target to show user what will be overwritten
Prompts user for each directory with conflicts
Respects user's choice to skip or overwrite

Directory Structure

The restore preserves this structure:

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

All files are copied to ~/.claude/ maintaining the same structure.

Agent Skills: Config Restore Skill

Install this agent skill to your local

Skill Files