Chezmoi Dotfiles Conventions

Chezmoi is a general-purpose dotfile manager. This skill documents naming, templating, and agent-resource patterns that apply to any chezmoi-managed dotfiles repo. Substitute paths to your own chezmoi source directory wherever examples reference ~/.local/share/chezmoi.

File Naming

dot_ prefix maps to .. Example: dot_zshrc becomes ~/.zshrc.
private_ prefix sets restrictive permissions. Example: private_dot_ssh/.
.tmpl suffix indicates a chezmoi template using Go text/template.
run_once_before_ and run_once_after_ scripts run once during chezmoi apply.
run_onchange_ scripts re-run when their content changes.

Templates

Templates use Go text/template with chezmoi data from ~/.config/chezmoi/chezmoi.toml:

{{ .chezmoi.os }}
{{ .chezmoi.hostname }}
{{ if eq .chezmoi.os "darwin" }}macOS-specific{{ end }}

Use {{ .chezmoi.os }} guards for platform-specific blocks.

Structure

Typical source paths inside a chezmoi repo:

Source path	Target path	Purpose
`dot_config/`	`~/.config/`	App configs such as Neovim, Ghostty, Tmux, and direnv
`dot_zsh/`	`~/.zsh/`	Zsh functions and shell customizations
`dot_agents/`	`~/.agents/`	Cross-tool agent skills and subagents
`dot_agents/skills/`	`~/.agents/skills/`	Portable agent skills
`dot_agents/agents/`	`~/.agents/agents/`	Agent personas and subagents
`dot_codex/`	`~/.codex/`	Codex config, profiles, and agents
`dot_claude/`	`~/.claude/`	Claude Code config and project-scoped skills
`Brewfile.tmpl`	generated Brewfile	Homebrew package source of truth
`run_onchange_after_install-*.sh.tmpl`	chezmoi script	Pinned upstream installers

Workflow

Edit source files in the chezmoi source directory. Run chezmoi source-path to find it.
Preview changes with chezmoi diff.
Apply changes with chezmoi apply.
Track existing home files with chezmoi add <file>.

Agent Resources

Agents live in dot_agents/agents/*.md and define how to think.
Skills live in dot_agents/skills/*/SKILL.md and define what to do.
Both deploy to ~/.agents/ and are linked into tools with agentspec.
Edit the chezmoi source, not deployed copies under ~/.agents/.

Managing Resources

Use agentspec for skills and agents:

agentspec manage add "$(chezmoi source-path)/dot_agents" --all-tools
agentspec manage validate dot_agents/skills/<name>/SKILL.md
agentspec manage validate dot_agents/agents/<name>.md
agentspec manage verify --accept --name <name>
agentspec sync --fast
agentspec status

After editing a local skill or agent:

Run chezmoi apply ~/.agents.
Run agentspec manage add "$(chezmoi source-path)/dot_agents" --all-tools.
Run agentspec manage verify --accept --name <name> for each changed local resource.
Run agentspec sync --fast.

Gotchas

Do not edit deployed copies under ~/.agents/skills/ or ~/.agents/agents/; chezmoi overwrites them.
Do not hard-code one user’s source path in reusable docs. Use chezmoi source-path.
When a new skill exists in dot_agents/skills/ but appears unmanaged, adopt it with agentspec manage add <name> --all-tools.
Use private_ for sensitive configs. Do not manage SSH keys, API keys, or tokens in chezmoi.