Guide · Agent skill
How to use the Dotfiles Backup and Sync agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Dotfiles skill is an agent skill that lets an AI agent manage your personal shell and editor configuration: your ~/.zshrc and the ~/.config folders you choose. It keeps these files in a private GitHub repository, so you can back them up, restore them, or set up a new computer from them. After this guide you will know how to install the skill, how to phrase requests so it runs the right action, and which safety checks protect your repository.
Dotfiles Backup and Syncdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Confirm prerequisites. Install bun, git, the GitHub CLI (gh) authenticated to GitHub, and gitleaks. Create or identify a private GitHub dotfiles repository.
- 2Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills.
- 3Create Config.md. Create the Config.md file at the USER customizations path and set DOTFILES_DIR, DOTFILES_BACKUPS, DOTFILES_REPO, DOTFILES_REPO_SLUG and DOTFILES_CONFIG_DIRS.
- 4Make a first backup. Ask the agent to back up your dotfiles. This creates a timestamped local copy without touching GitHub.
- 5Check status. Ask for dotfiles status to see which files differ between home and the repo before you change anything.
- 6Push or pull. Ask to push dotfiles from a machine that has your configs, or pull them on a new machine. Review the report of changed files.
What is an agent skill and what does this one do?
An agent skill is a folder of instructions and scripts that an AI agent can load when a request matches the skill's purpose. This skill is for shell, editor and terminal configuration. It works against a private GitHub dotfiles repository that you own.
It supports six intents: Push, Pull, Sync, Restore, Status and Backup. Push is the default. Pull, Sync and Status only compare files. Restore is the only intent that overwrites local files, and Backup makes a local copy that never leaves your machine.
- Push: commit and push local configs to the private repo
- Pull: fetch the latest repo into a working clone and compare it with local files
- Sync: two-way sync, used when you are unsure of the direction
- Restore: copy files from the repo or a backup back home, after a timestamped backup
- Status: report differences between local files and the repo
- Backup: create a local timestamped copy of the selected configs
Install the Dotfiles skill
Download the skill ZIP from this page and unzip it into one of two places. For all your projects, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/ so the folder becomes ~/.claude/skills/Dotfiles/
- Project install: unzip into .claude/skills/ inside your project
- Claude apps: upload the skill under Settings → Capabilities → Skills
Set up Config.md before the first run
The skill ships with no personal values. You define them in a file called Config.md at <configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Dotfiles/Config.md, where configRoot is $CLAUDE_CONFIG_DIR when that is set, and ~/.claude otherwise. The file must define DOTFILES_DIR, DOTFILES_BACKUPS, DOTFILES_REPO, DOTFILES_REPO_SLUG and DOTFILES_CONFIG_DIRS. The skill has no defaults for these keys.
Every intent starts by running the Config command. If Config.md or a required key is missing, the command exits with an error and the intent stops. The skill's Setup.md file covers first-time setup.
- DOTFILES_DIR: the local working clone of the repo
- DOTFILES_BACKUPS: the folder where timestamped backups are stored
- DOTFILES_REPO: the private remote URL
- DOTFILES_REPO_SLUG: the repository identifier
- DOTFILES_CONFIG_DIRS: the names of the ~/.config directories to back up and restore
DOTFILES_ENV="$(bun ~/.claude/skills/Dotfiles/Tools/Config.ts)" || exit 1; eval "$DOTFILES_ENV"Trigger the skill with natural requests
You do not need a command syntax. Describe what you want in plain language and the agent picks the intent. Phrases such as 'push dotfiles' or 'update dotfiles' run Push. 'Pull dotfiles' or a new machine setup request runs Pull. 'Restore dotfiles' runs Restore. 'Check dotfiles status' runs Status. 'Backup dotfiles' runs Backup.
If you are not sure which direction to go, ask to sync dotfiles and the agent uses Sync.
- 'Push my dotfiles to the private repo'
- 'Pull my dotfiles onto this new laptop'
- 'Check dotfiles status before I change my zshrc'
- 'Make a backup of my dotfiles before I experiment'
- 'Restore my zshrc from the latest backup' (review the backup first)
What the safety checks do
Before any push, the skill checks that origin matches your configured repo and that GitHub reports the repo as private. It runs this check again just before the push. It also runs a gitleaks scan on the staged changes and on every unpushed commit. If any check fails, or gitleaks is not installed, the push stops before a commit.
Local backups leave out secret-type files such as .env, *.oauth, *token*.json, client_secret*.json, credentials* and auth.json. The skill is written to never commit to public repositories.
- Remote must match DOTFILES_REPO and be private according to gh
- gitleaks must exit 0 on the staged diff and on unpushed commits
- Restore makes a timestamped backup and asks for confirmation before overwriting files
- Pull, Sync and Status leave local files unchanged
Check what differs between home and the repo
The skill compares only .zshrc and the files the repo tracks under .config. It does not diff the whole ~/.config folder, because that would list every application's data. The comparison prints one line per missing or different file, and prints nothing when the files match.
The skill's compare recipe is a short loop over .zshrc and git ls-files .config. You do not need to run it yourself; ask for a status report and the agent runs it.
- 'missing locally: <file>' means the file exists in the repo but not at home
- 'differs: <file>' means the local and repo copies are different
What people use it for
- Keep your ~/.zshrc and editor configs versioned in a private repo so you can recover them after a mistake
- Set up a new computer by pulling your existing dotfiles from your private repository
- Make a timestamped local backup of selected ~/.config folders before a risky change
- Check which local shell or editor files have drifted from the repo before you push
Frequently asked questions
How do I install the Dotfiles agent skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps, upload it under Settings → Capabilities → Skills.
What do I need to run the Dotfiles skill?
The source lists bun, git, the GitHub CLI (gh) authenticated to GitHub, gitleaks for secret scanning, a private GitHub dotfiles repository, and a Config.md file that defines DOTFILES_DIR, DOTFILES_BACKUPS, DOTFILES_REPO and DOTFILES_CONFIG_DIRS. The skill runs scripts and uses the network.
Is the Dotfiles skill free to use?
The skill is published under the MIT licence, as stated on this page. The licence terms are in the repository it comes from.
Will the skill push my secrets to GitHub?
The skill runs gitleaks on the staged changes and on unpushed commits before a push. If the scan fails, or gitleaks is missing, the push stops. Local backups also exclude files such as .env and token files.
Can it push to a public repository?
No. The skill checks that GitHub reports the configured repo as private, both before and just before the push. If the repo is public or the check cannot be read, the run stops.
Why does Restore need caution on my current machine?
Restore overwrites local files. The skill first makes a timestamped backup in your backups folder and asks for your confirmation. Review the backup before restoring on a live machine.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you already have a private GitHub repo and want your shell and editor setup versioned, backed up and easy to restore on another machine. Pick something else if you do not have a private repo, cannot install gitleaks, or want to manage app configs unrelated to shell, editor or terminal, which the skill excludes.
Download the skill