dotfiles git:20261005.4d84eedA

Immutable. This exact content never changes and is served at /api/v1/blob/d5dd66beba947f3c.

---
name: dotfiles
description: Chezmoi dotfiles conventions and patterns. Use when modifying dotfiles, adding new managed files, working with chezmoi templates, or syncing agent skills and subagents through agentspec.
allowed-tools: Read, Grep, Glob, Bash(chezmoi *), Bash(agentspec *)
---

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

```gotemplate
{{ .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

1. Edit source files in the chezmoi source directory. Run `chezmoi source-path` to find it.
2. Preview changes with `chezmoi diff`.
3. Apply changes with `chezmoi apply`.
4. 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:

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

1. Run `chezmoi apply ~/.agents`.
2. Run `agentspec manage add "$(chezmoi source-path)/dot_agents" --all-tools`.
3. Run `agentspec manage verify --accept --name <name>` for each changed local resource.
4. 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.
- When `diff.command` is an editor such as `nvim`, `chezmoi diff` hangs without a TTY (agents, CI, captured output). Pass `--use-builtin-diff`.
- On a fresh Mac, `#!/usr/bin/env bash` scripts run under `/bin/bash` 3.2 until Homebrew installs bash 5. Check rendered scripts with `/bin/bash -n`; 3.2 misparses a heredoc inside `$(...)` when the text contains parentheses.