dot: Skill for Claude Code

Chezmoi Source Standard

The source tree (~/.local/share/chezmoi) is the only thing to edit; chezmoi apply renders it into $HOME, so a change made under ~/.config or ~/.gemini is overwritten on the next apply. File names encode target path, mode, encryption, and rendering; mise wraps the commands as tasks.

Naming

Read source names when adding or renaming a managed target; attributes depend on the target type.

Workflow

1. Edit the source, never the deployed copy; chezmoi cd opens a shell in the source root.

2. Manage an existing file: chezmoi add <target> infers the attributes; --template templatizes; set a secret to 0600 before --encrypt imports it as encrypted_private_<name>.age (with dot_ before a leading-dot name):

   chmod 600 ~/.config/<tool>/secret
   chezmoi add --encrypt ~/.config/<tool>/secret   # import and encrypt into the source
   chezmoi edit ~/.config/<tool>/secret            # edit the plaintext, re-encrypt on save
   

3. Preview: mise run diff (chezmoi diff --force --no-pager; restrict to affected targets). Diffs exclude encrypted targets so plaintext secrets never reach transcripts; chezmoi status still lists their drift.

4. Validate rendering: mise run check:chezmoi uses temporary configuration and destination with a dry run excluding encrypted files. It checks the current platform; exercise changed Linux/macOS branches separately and report unexercised branches or encrypted targets.

5. Check repeatability: for Bash/profile modifier changes, add existing-target and second-pass cases under dot/tests/, using the isolated rendering approach in test_shell_modifiers.py. Their blocks go through .chezmoitemplates/managed-block.tmpl, which rewrites the block between its begin and end markers in place, so a body change needs no migration code. JSON/TOML modifier changes need the same cases in test_harness_config.py. Inspect affected run_* hooks: ordinary hooks run on each apply; once/onchange hooks can rerun when their content changes.

6. Apply within scope: mise run apply (chezmoi apply --force, so a diverged target never blocks scripts on a prompt; --force does not expand authorized targets or side effects). Themes (one fmind/theme commit) and fonts (release URLs) are checksum-pinned externals that refetch when their URL changes; a checksum mismatch fails apply instead of deploying changed content, and mise run upgrade advances the theme pin only while every copied block in the COPIED map of dot/dot_tasks/theme_pin.py matches. The Google Sans, Google Sans Code, and Nerd Fonts releases have no upgrade task: when a newer release exists, bump each URL and its checksum together.

7. Pull target edits back: chezmoi re-add folds manual changes to a managed file (a regenerated lockfile, for example) into the source.

8. Diagnose: mise run doctor (dot doctor, chezmoi doctor, and mise doctor); chezmoi managed and chezmoi unmanaged list coverage; dot orphan lists former managed targets (orphans); the installed-link recovery guide covers retired skill links, and approved cleanup moves them to recoverable backups. Use command help and dot-cli for cleanup flags.