chezmoi-dotfiles-guide
Expert guidance for working with chezmoi dotfiles repositories that manage comprehensive development environments across multiple machines.
What This Skill Does
This skill provides Claude Code with deep knowledge of chezmoi dotfiles repository patterns, naming conventions, security practices, and common workflows. It enables intelligent assistance with:
Managing dotfiles using chezmoi conventionsUnderstanding template files and variable substitutionApplying configuration changes safelyMaintaining multi-machine development environmentsWorking with integrated tools (zsh, tmux, neovim, mise)Instructions
When working in a chezmoi dotfiles repository, follow these guidelines:
1. Understand the Repository Structure
Before making changes:
Identify that this is a chezmoi repository by checking for `.chezmoi*` files and `home/` directory structureRecognize chezmoi file naming conventions: - `dot_` prefix → files starting with `.` (dotfiles)
- `private_` prefix → sensitive files (not committed)
- `exact_` prefix → directories requiring exact matching
- `executable_` prefix → executable files
- `.tmpl` suffix → template files requiring variable substitution
Locate the relevant configuration category (shell, development tools, project-specific, custom scripts)2. Making Configuration Changes
When the user requests changes to dotfiles:
**ALWAYS** edit files in the chezmoi source directory structure (under `home/`), never the target files directlyUse `chezmoi diff` to preview changes before applyingFor template files (`.tmpl`), understand variable substitution patternsFor new files, determine the correct chezmoi prefix based on file requirementsAfter editing, recommend `chezmoi apply` (or `cha` alias) to apply changesFor specific files, use `chezmoi apply <target_file>` to apply only that file's changes3. Security-First Approach
Handle sensitive information carefully:
Use `private_` prefix for files containing secretsTemplate sensitive values using chezmoi data variablesNever commit actual credentials or API keysRecognize 1Password CLI integration patterns for secret managementSuggest templating when you see hardcoded sensitive values4. Multi-Machine Awareness
Consider machine-specific configurations:
Check for machine detection logic in templates (work vs personal vs remote)Use conditional templating based on machine typeRespect environment-specific configurations5. Working with Integrated Tools
Understand the tool ecosystem:
**Shell**: Modular zsh configuration in `home/exact_dot_my_zsh_plugins/`**Version Management**: mise handles all language runtimes**Session Management**: tmux with custom layouts and utilities**Editor**: Neovim with Lua configuration**Project Environments**: direnv-based `.envrc` files for per-project setup6. Essential Commands Reference
Provide these commands when relevant:
`chezmoi apply` - Apply all configuration changes`chezmoi apply <target_file>` - Apply specific file changes`chezmoi diff` - Preview what would change`chezmoi add <file>` - Add new file to chezmoi management`chezmoi re-add` - Update managed files with local changes`chezmoi cd` - Navigate to chezmoi source directory7. Best Practices
Follow these principles:
**Edit existing files** rather than creating new ones whenever possible**Never create documentation files** unless explicitly requested**Preview changes** with `diff` before applying**Use templates** for any values that differ between machines or contain secrets**Follow naming conventions** strictly when adding new files**Test changes incrementally** with `chezmoi apply <specific-file>`Example Usage
**User:** "Add a new git alias for interactive rebase"
**Claude Code should:**
1. Read `home/private_dot_config/git/config.tmpl`
2. Add the alias in the appropriate `[alias]` section
3. Show the diff with `chezmoi diff`
4. Recommend `chezmoi apply` to apply the change
**User:** "Create a new tmux session script"
**Claude Code should:**
1. Create file in `home/dot_local/bin/` with `executable_` prefix
2. Use chezmoi naming: `executable_tmux-my-script`
3. Write the script content
4. Recommend `chezmoi apply` followed by testing the script
**User:** "Add API key for new service"
**Claude Code should:**
1. Identify this requires a template file with `private_` prefix
2. Edit or create `.envrc.tmpl` in appropriate project directory
3. Use template variable (e.g., `{{ .api_key_service }}`) instead of hardcoded value
4. Explain how to set the variable in chezmoi data
5. Recommend `chezmoi apply`
Constraints
Do NOT apply changes automatically - always let the user run `chezmoi apply`Do NOT commit sensitive information in template filesDo NOT create files outside the chezmoi source structureDo NOT modify target files directly (always work in `home/` structure)Do NOT create README or documentation files unless explicitly requestedDo ONLY what is asked - no extra improvements or refactoring