
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- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads chezmoi-workflows automatically when relevant.
- 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
| Component | Location | Purpose |
|---|---|---|
| Source | $(chezmoi source-path) | Git repository with dotfile templates |
| Target | ~/ | Home directory (deployed files) |
| Remote | GitHub (private recommended) | Cross-machine sync and backup |
| Config | ~/.config/chezmoi/chezmoi.toml | User 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:
| Check | Expected | Meaning if failing |
|---|---|---|
| config-file | found ~/.config/chezmoi/chezmoi.toml | Config missing or wrong path |
| source-dir | ~/gh/vjspc/dotfiles is a git working tree (clean) | Source dirty or not a git repo |
| git-command | found /opt/homebrew/bin/git | Git not installed |
| edit-command | found /opt/homebrew/bin/hx | Editor not configured |
| 1password | found /opt/homebrew/bin/op | 1Password CLI needed for templates |
| age/gpg | info = optional | Only 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
| Issue | Cause | Solution |
|---|---|---|
| chezmoi not found | Not installed | Install via brew install chezmoi |
| Source path empty | Not initialized | Run chezmoi init |
| Git remote not set | Missing GitHub repo | Run chezmoi git -- remote add origin URL |
| Apply fails | Template error | Check template syntax with chezmoi diff |
| Merge conflicts | Diverged source and target | Use chezmoi merge to resolve |
| Secrets detected | Plain text credentials | Use chezmoi templates with 1Password/Doppler |
| forget needs TTY | Interactive confirmation | Use chezmoi forget --force <path> |
| Template not found | Missing .tmpl suffix | Use chezmoi add --template to create .tmpl |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- 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
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
mql5-indicator-patterns
terrylica/cc-skills
MQL5 indicator development patterns. TRIGGERS - MQL5 indicator, OnCalculate, indicator buffers, MetaTrader 5.
python-logging-best-practices
terrylica/cc-skills
Python logging with loguru, structlog, and orjson. TRIGGERS - loguru, structlog, structured logging
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.
Popular other skills
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.
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.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.