MCPInstall

chezmoi-workflows

Dotfile backup and sync with chezmoi. TRIGGERS - chezmoi, dotfiles, sync dotfiles, backup configs, cross-machine sync.

Installs
297
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/terrylica/cc-skills --skill chezmoi-workflows
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads chezmoi-workflows automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Chezmoi Workflows

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

  • Backing up dotfiles to Git repository
  • Syncing configuration files across machines
  • Tracking changes to shell configs, editor settings, or other dotfiles
  • Managing templated configurations with chezmoi
  • Troubleshooting dotfile drift between source and target

Architecture

ComponentLocationPurpose
Source$(chezmoi source-path)Git repository with dotfile templates
Target~/Home directory (deployed files)
RemoteGitHub (private recommended)Cross-machine sync and backup
Config~/.config/chezmoi/chezmoi.tomlUser preferences and settings

1. Status Check

chezmoi source-path                    # Show source directory
chezmoi git -- remote -v               # Show GitHub remote
chezmoi status                         # Show drift between source and target
chezmoi managed | wc -l                # Count tracked files

2. Track File Changes

After editing a config file, add it to chezmoi:

chezmoi status                         # 1. Verify file shows as modified
chezmoi diff ~/.zshrc                  # 2. Review changes
chezmoi add ~/.zshrc                   # 3. Add to source (auto-commits if configured)
chezmoi git -- log -1 --oneline        # 4. Verify commit created
chezmoi git -- push                    # 5. Push to remote

3. Track New File

Add a previously untracked config file:

chezmoi add ~/.config/app/config.toml  # 1. Add file to source
chezmoi managed | grep app             # 2. Verify in managed list
chezmoi git -- push                    # 3. Push to remote

4. Sync from Remote

Pull changes from GitHub and apply to home directory:

chezmoi update                         # 1. Pull + apply (single command)
chezmoi verify                         # 2. Verify all files match source
chezmoi status                         # 3. Confirm no drift

5. Push All Changes

Bulk sync all modified tracked files to remote:

chezmoi status                         # 1. Review all drift
chezmoi re-add                         # 2. Re-add all managed files (auto-commits)
chezmoi git -- push                    # 3. Push to remote

6. First-Time Setup

Install chezmoi

brew install chezmoi                   # macOS

Initialize (fresh start)

/usr/bin/env bash << 'CONFIG_EOF'
chezmoi init                           # Create empty source
chezmoi add ~/.zshrc ~/.gitconfig      # Add first files
gh repo create dotfiles --private --source="$(chezmoi source-path)" --push
CONFIG_EOF

Initialize (clone existing)

chezmoi init git@github.com:<user>/dotfiles.git
chezmoi apply                          # Deploy to home directory

7. Configure Source Directory

Move source to custom location (e.g., for multi-account SSH):

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
mv "$(chezmoi source-path)" ~/path/to/dotfiles
SKILL_SCRIPT_EOF

Edit ~/.config/chezmoi/chezmoi.toml:

sourceDir = "~/path/to/dotfiles"

Verify:

chezmoi source-path                    # Should show new location

8. Change Remote

Switch to different GitHub account or repository:

chezmoi git -- remote -v                                              # View current
chezmoi git -- remote set-url origin git@github.com:<user>/<repo>.git # Change
chezmoi git -- push -u origin main                                    # Push to new remote

9. Resolve Merge Conflicts

/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status                  # 1. Identify conflicted files
chezmoi git -- diff                    # 2. Review conflicts
# Manually edit files in $(chezmoi source-path)
chezmoi git -- add <resolved-files>    # 3. Stage resolved files
chezmoi git -- commit -m "Resolve merge conflict"
chezmoi apply                          # 4. Apply to home directory
chezmoi git -- push                    # 5. Push resolution
GIT_EOF

10. Validation (SLO)

After major operations, verify system state:

chezmoi verify                         # Exit 0 = all files match source
chezmoi diff                           # Empty = no drift
chezmoi managed                        # Lists all tracked files
chezmoi git -- log --oneline -3        # Recent commit history

11. Forget (Untrack) a File

Stop tracking a file without deleting it from home directory:

chezmoi managed | grep config.local     # 1. Confirm file is tracked
chezmoi forget --force ~/.config/app/config.local.toml  # 2. Remove from source (--force skips TTY prompt)
chezmoi git -- push                     # 3. Push removal to remote
ls ~/.config/app/config.local.toml      # 4. Verify file still exists in home

When to use: Machine-specific configs, files with secrets that shouldn't be synced, files accidentally added.


12. Template Management

Create OS/architecture-conditional configs using Go templates:

Convert existing file to template

chezmoi add --template ~/.config/app/config.toml  # 1. Add as template (creates .tmpl suffix in source)
chezmoi edit ~/.config/app/config.toml             # 2. Edit template in $EDITOR (helix)
chezmoi diff ~/.config/app/config.toml             # 3. Preview what would change
chezmoi apply ~/.config/app/config.toml            # 4. Apply rendered template to home

Common template patterns

# OS-conditional block
{{ if eq .chezmoi.os "darwin" -}}
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" -}}
export HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
{{ end -}}

# Architecture-conditional
{{ if eq .chezmoi.arch "arm64" -}}
ARCH="aarch64"
{{ else -}}
ARCH="x86_64"
{{ end -}}

# Custom data from chezmoi.toml [data] section
git_name = "{{ .git.name }}"
git_email = "{{ .git.email }}"

# 1Password secret (requires op CLI)
api_key = {{ onepasswordRead "op://Vault/Item/Field" }}

Verify template renders correctly

chezmoi execute-template < "$(chezmoi source-path)/dot_config/app/config.toml.tmpl"
chezmoi cat ~/.config/app/config.toml   # Show rendered output without applying

13. Safe Update (Diff Before Apply)

Pull from remote with review step — safer than blind chezmoi update:

chezmoi git -- pull                    # 1. Pull source changes only (no apply)
chezmoi diff                           # 2. Review what WOULD change in home directory
chezmoi apply --dry-run --verbose      # 3. Dry run — shows actions without executing
chezmoi apply                          # 4. Apply after review
chezmoi status                         # 5. Confirm clean state

When to use: When pulling changes made on another machine, or after a long gap between syncs. Avoids surprise overwrites of local edits.


14. Doctor (Diagnostic)

Troubleshoot chezmoi setup and environment:

chezmoi doctor                         # Full diagnostic — checks all components

Key fields to verify:

CheckExpectedMeaning if failing
config-filefound ~/.config/chezmoi/chezmoi.tomlConfig missing or wrong path
source-dir~/gh/vjspc/dotfiles is a git working tree (clean)Source dirty or not a git repo
git-commandfound /opt/homebrew/bin/gitGit not installed
edit-commandfound /opt/homebrew/bin/hxEditor not configured
1passwordfound /opt/homebrew/bin/op1Password CLI needed for templates
age/gpginfo = optionalOnly needed for encrypted files
chezmoi doctor | grep -v "^ok"         # Show only warnings and errors

Reference

  • Setup Guide - Installation, multi-account GitHub, migration
  • Prompt Patterns - Detailed workflow examples
  • Configuration - chezmoi.toml settings, templates
  • Secret Detection - Handling detected secrets

Chezmoi docs: https://www.chezmoi.io/reference/


Troubleshooting

IssueCauseSolution
chezmoi not foundNot installedInstall via brew install chezmoi
Source path emptyNot initializedRun chezmoi init
Git remote not setMissing GitHub repoRun chezmoi git -- remote add origin URL
Apply failsTemplate errorCheck template syntax with chezmoi diff
Merge conflictsDiverged source and targetUse chezmoi merge to resolve
Secrets detectedPlain text credentialsUse chezmoi templates with 1Password/Doppler
forget needs TTYInteractive confirmationUse chezmoi forget --force <path>
Template not foundMissing .tmpl suffixUse chezmoi add --template to create .tmpl

Post-Execution Reflection

After this skill completes, check before closing:

  1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
  2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
  3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

FAQ

What does the chezmoi-workflows skill do?

Dotfile backup and sync with chezmoi. TRIGGERS - chezmoi, dotfiles, sync dotfiles, backup configs, cross-machine sync.

How do I install chezmoi-workflows?

Run npx skills add https://github.com/terrylica/cc-skills --skill chezmoi-workflows in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/chezmoi-workflows/ (personal) or .claude/skills/chezmoi-workflows/ (project).

Which AI agents can use chezmoi-workflows?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is chezmoi-workflows safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains chezmoi-workflows?

It is published by terrylica in terrylica/cc-skills. It has 297 recorded installs.

More from terrylica/cc-skills

View all →

mise-tasks

terrylica/cc-skills

Orchestrate multi-step project workflows using mise task definitions with dependency management and argument handling. Use whenever the user.

pandoc-pdf-generation

terrylica/cc-skills

PDF generation from markdown via Pandoc/XeLaTeX. TRIGGERS - markdown for PDF, print document, pandoc

Docs & Writing547 installs

mql5-indicator-patterns

terrylica/cc-skills

MQL5 indicator development patterns. TRIGGERS - MQL5 indicator, OnCalculate, indicator buffers, MetaTrader 5.

501 installs

Python logging with loguru, structlog, and orjson. TRIGGERS - loguru, structlog, structured logging

DevOps & Cloud402 installs

gdrive-access

terrylica/cc-skills

Access Google Drive via CLI with 1Password OAuth: list files, download, and sync folders. TRIGGERS - google drive, gdrive, drive folder, download drive, sync drive.

Backend & APIs356 installs

disk-hygiene

terrylica/cc-skills

Open the skill to read its SKILL.md instructions.

268 installs

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs