Skip to main content
skill CX Codex

chezmoi-workflows — Claude Code skill: what it does, how to install

chezmoi-workflows runs dotfiles through chezmoi: adds configs to a Git repo, pulls them onto other machines, renders templates. Useful when shell and editor settings drift apart.

MIT 308 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill chezmoi-workflows -a claude-code
Open on GitHub

What chezmoi-workflows does

The skill turns chezmoi into a set of short procedures with the command order already written out. Check for drift first, add a single changed file and push it, re-add every tracked file in one pass, then pull and apply with a single call. Merge conflicts get their own walkthrough: fix the file in the source directory, stage it, apply.

Templates are covered too. Go template branches on .chezmoi.os and .chezmoi.arch, values taken from the [data] table in chezmoi.toml, secrets read through onepasswordRead. One section covers chezmoi forget --force for configs that should stay on a single machine. The skill file also tells the agent to correct itself when a step stops matching reality.

Setup leans on brew install chezmoi and gh repo create to spin up a private dotfiles repo, so GitHub CLI is part of the picture. Every later step ends with chezmoi git -- push. Point it at no remote and nothing crosses machines.

What it helps with

  • add a changed .zshrc to the dotfiles repo and push it
  • deploy configs onto a fresh machine in one command
  • work through a merge conflict inside the chezmoi source
  • keep one config file different on macOS and Linux with a template
  • untrack a secrets file while leaving it on disk

Example prompts for the agent

  • Add ~/.zshrc to chezmoi, show me the diff, then push it
  • Set up my dotfiles on this new laptop: chezmoi init from my repo and chezmoi apply
  • Turn ~/.config/app/config.toml into a template so the Homebrew prefix differs between macOS and Linux

How to install chezmoi-workflows

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill chezmoi-workflows -a claude-code

2Manually: put the files in place

~/.claude/skills/chezmoi-workflows/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/chezmoi-workflows/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about chezmoi-workflows

How do I install chezmoi-workflows in Claude Code?

Run npx skills add terrylica/cc-skills --skill chezmoi-workflows -a claude-code. The skill lands at ~/.claude/skills/chezmoi-workflows/SKILL.md.

What does chezmoi-workflows do?

It lays out chezmoi routines step by step: spotting drift, adding files to the source, bulk re-add, fetching from the remote, resolving conflicts. Templates with OS and architecture conditions have their own section.

What has to be in place before it works?

chezmoi itself, installed in the walkthrough with brew install chezmoi on macOS. Repo creation calls gh, and the secret example in a template relies on the op CLI.

Source text

SKILL.md · MIT
---
name: chezmoi-workflows
description: Dotfile backup and sync with chezmoi. TRIGGERS - chezmoi, dotfiles, sync dotfiles, backup configs, cross-machine sync.
allowed-tools: Read, Edit, Bash
---

# 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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
brew install chezmoi                   # macOS
```

### Initialize (fresh start)

```bash
/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)

```bash
chezmoi init [email protected]:<user>/dotfiles.git
chezmoi apply                          # Deploy to home directory
```

---

## 7. Configure Source Directory

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

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

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

```toml
sourceDir = "~/path/to/dotfiles"
```

Verify:

```bash
chezmoi source-path                    # Should show new location
```

---

## 8. Change Remote

Switch to different GitHub account or repository:

```bash
chezmoi git -- remote -v                                              # View current
chezmoi git -- remote set-url origin [email protected]:<user>/<repo>.git # Change
chezmoi git -- push -u origin main                                    # Push to new remote
```

---

## 9. Resolve Merge Conflicts

```bash
/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:

```bash
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:

```bash
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

```bash
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

```bash
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`:

```bash
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:

```bash
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    |

```bash
chezmoi doctor | grep -v "^ok"         # Show only warnings and errors
```

---

## Reference

- [Setup Guide](./references/setup.md) - Installation, multi-account GitHub, migration
- [Prompt Patterns](./references/prompt-patterns.md) - Detailed workflow examples
- [Configuration](./references/configuration.md) - chezmoi.toml settings, templates
- [Secret Detection](./references/secret-detection.md) - 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:

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.

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for DevOps and infrastructure →

From the same set79

The whole set →
pandoc-pdf-generation pandoc-pdf-generation — a skill for Claude Code and five other platforms that converts Markdown to PDF using Pandoc and XeLaTeX. Triggers on "markdown for PDF", "print document", or "pandoc". CX Codex +1 553installs mql5-indicator-patterns mql5-indicator-patterns — a skill for building MetaTrader 5 indicators: buffer setup, display scale and recalculation patterns that keep the chart from going blank. CX Codex +1 520installs python-logging-best-practices python-logging-best-practices is a Claude Code skill for choosing and configuring Python logging, from journald messages to structured JSONL events. CX Codex +1 408installs gdrive-access The gdrive-access skill gives your agent Google Drive from the command line: list files, download them, sync whole folders. OAuth credentials come from 1Password. CX Codex +1 357installs disk-hygiene disk-hygiene audits macOS disk usage, clears bloated developer caches, and flags forgotten large files without automated accidental deletions. CX Codex +1 273installs latex-tables Teaches the agent to build LaTeX tables with tabularray: fixed column widths, alignment, rule lines. Useful when a tblr has to be written from scratch or an old table rewritten. CX Codex +1 242installs latex-build latex-build is a Claude Code skill that builds LaTeX documents with latexmk, watches files for changes, and helps diagnose compilation errors. CX Codex +1 236installs ascii-diagram-validator The ascii-diagram-validator skill finds structural alignment problems in Markdown box diagrams and reports where they occur. Run it after editing architecture docs or README files. CX Codex +1 217installs

Project sponsors

Companies that keep this analytics open