Skip to main content
The better-skills backup command copies local skill folders to a temporary directory for safe editing and migration.

​
When to Use Backup

Use backup when:
  • Migrating existing skills to Better Skills vaults
  • Batch editing multiple local skills before upload
  • Preserving raw skill snapshots before making changes
  • Consolidating skills from multiple agent directories
Backup is designed for local skill folders only. It does not download skills from your vault — use better-skills clone for that.

​
Backup Command

The basic backup command scans your agent skill directories: 
better-skills backup

​
Options

better-skills backup [--source <dir>] [--out <tmp-dir>] [--agent <agent>]...
Flags:
  • --source <dir>: Backup a specific directory instead of auto-detecting agent paths
  • --out <tmp-dir>: Custom output directory (defaults to system temp folder)
  • --agent <agent>: Filter by specific agent (can be repeated)
Supported agents: opencode, claude-code, cursor

​
Examples

better-skills backup

​
Backup Folder Structure

Backup creates a timestamped folder with two subdirectories: 
/tmp/better-skills-backup/2024-03-03T14-30-00-000Z/
├── raw/       # Exact copies of discovered skills
└── work/      # Editable copies for processing

​
raw/ Directory

Exact snapshots of discovered skill folders. Purpose: Preserve original state for reference Structure: 
raw/
├── 001-react-patterns/
├── 002-api-client/
└── 003-deployment/
Folders are numbered sequentially with original skill names.

​
work/ Directory

Editable copies for preparing skills before upload. Purpose: Safe workspace for editing without affecting originals Structure: 
work/
├── 001-react-patterns/
│   ├── SKILL.md
│   └── references/
├── 002-api-client/
│   ├── SKILL.md
│   └── scripts/
└── 003-deployment/
    ├── SKILL.md
    └── assets/
Make all edits in work/ folders before running create or update.

​
Discovery Behavior

Backup scans these locations by default:
  1. OpenCode: ~/.config/opencode/skills
  2. Claude Code: ~/.claude/skills or ~/Library/Application Support/Claude/skills (macOS)
  3. Cursor: ~/.cursor/skills or ~/AppData/Roaming/Cursor/skills (Windows)
  4. Workspace: <cwd>/.agents/skills

​
Skill Detection

A folder is considered a skill if:
  • It contains a SKILL.md file
  • It does not contain .better-skills-install.json (managed by better-skills sync)
Folders with .better-skills-install.json are skipped because they are already managed by Better Skills.

​
Restore Workflow

Backup prepares skills for upload. Here’s the full workflow:
1

Run Backup

better-skills backup
Note the output paths:
✓ backup complete
tmp: /tmp/better-skills-backup/2024-03-03T14-30-00-000Z
raw: /tmp/better-skills-backup/2024-03-03T14-30-00-000Z/raw
work: /tmp/better-skills-backup/2024-03-03T14-30-00-000Z/work
summary: discovered=5, copied=5, skipped=2, failed=0
2

Review and Edit

Navigate to the work/ directory:
cd /tmp/better-skills-backup/2024-03-03T14-30-00-000Z/work
Edit skills as needed:
  • Fix frontmatter (name, description)
  • Add resource mentions
  • Rewrite local links to mention syntax
3

Rewrite Links

Convert local links to mention syntax:
better-skills rewrite-links ./001-react-patterns
Repeat for each skill folder.
4

Validate

Check each skill before upload:
better-skills validate ./001-react-patterns
Fix any reported errors.
5

Create Skills

Upload each skill to your vault:
better-skills create --from ./001-react-patterns
better-skills create --from ./002-api-client
better-skills create --from ./003-deployment
6

Sync and Verify

Download the created skills:
better-skills sync
better-skills list --all

​
Agent Filtering

Filter backup by specific agents: 
# Backup only OpenCode skills
better-skills backup --agent opencode

# Backup OpenCode and Cursor skills
better-skills backup --agent opencode --agent cursor
Auto-detection behavior:
  • If --source is provided: ignores --agent filters
  • If --agent is provided: only scans specified agent directories
  • If neither is provided: scans all supported agent directories + workspace .agents/skills

​
Use Cases

​
Migrating to Better Skills

You have existing skills in your OpenCode config: 
# Backup all OpenCode skills
better-skills backup --agent opencode

# Edit in work/ folder
cd /tmp/better-skills-backup/.../work

# Validate and create each skill
for skill in */; do
  better-skills rewrite-links "$skill"
  better-skills validate "$skill"
  better-skills create --from "$skill"
done

​
Bulk Editing Skills

Edit multiple skills before upload: 
better-skills backup --out ~/batch-edit

cd ~/batch-edit/work

# Make changes across all skills
sed -i 's/old-pattern/new-pattern/' */SKILL.md

# Validate and upload
for skill in */; do
  better-skills validate "$skill"
  better-skills create --from "$skill"
done

​
Consolidating Agent Skills

Merge skills from multiple agents: 
# Backup all agents to same output
better-skills backup --out ~/consolidated-skills

# Work directory contains all discovered skills
cd ~/consolidated-skills/work

ls
# 001-opencode-skill/
# 002-cursor-skill/
# 003-workspace-skill/

# Process each skill individually

​
Preserving Originals

Keep raw snapshots before making changes: 
better-skills backup --out ~/skill-archive-2024-03-03

# raw/ folder preserves originals
# work/ folder for safe editing

# If editing fails, refer back to raw/ copies

​
Output Format

Backup command prints JSON-compatible summary: 
{
  "backupDir": "/tmp/better-skills-backup/2024-03-03T14-30-00-000Z",
  "rawDir": "/tmp/better-skills-backup/2024-03-03T14-30-00-000Z/raw",
  "workDir": "/tmp/better-skills-backup/2024-03-03T14-30-00-000Z/work",
  "discoveredCount": 5,
  "copiedCount": 5,
  "skippedCount": 2,
  "failedCount": 0
}
Fields:
  • discoveredCount: Total skill folders found
  • copiedCount: Successfully copied to backup
  • skippedCount: Skipped (managed by better-skills sync)
  • failedCount: Copy errors
If failedCount > 0, the command exits with code 1 and lists failures.

​
Non-Interactive Usage

Backup works in non-interactive environments (CI, scripts, agents): 
# Set environment hints
AGENT=1 better-skills backup --source ~/skills --out ~/backup

# Check exit code
if [ $? -eq 0 ]; then
  echo "Backup succeeded"
else
  echo "Backup failed"
fi
Spinners are suppressed when:
  • No TTY detected
  • AGENT=1, OPENCODE=1, or CI=true environment variables set

​
Next Steps

Creating Skills

Learn how to create skills from backed up folders

Markdown Mentions

Understand mention syntax for linking resources

Build docs developers (and LLMs) love

Get started for freeTalk to us