Claude Skill

chezmoi

Manage chezmoi source names, templates, secrets, diffs, and deployment in fmind/dot.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download fmind-dot-.agents_skills_chezmoi-3bbe830.zip · 2 KB

Install

skills CLI npx skills add https://github.com/fmind/dot/tree/main/.agents/skills/chezmoi
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fmind-dot@llmmart
Git git clone https://github.com/fmind/dot.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole fmind/dot collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Chezmoi Source Standard

Edit sources here per AGENTS.md; edits under ~/.config or ~/.gemini are overwritten on the next apply. mise tasks wrap chezmoi commands.

Naming

Pick the target type first, then attributes in source-state reference order (encrypted_ → private_ → dot_; wrong order yields a literal filename). Repo conventions: global skill links use dot_agents/skills/symlink_<name>.tmpl (dot-skills), modifiers use # chezmoi:modify-template, and native login seeds use create_encrypted_private_*.

Workflow

  1. Import an existing file: chezmoi add <target> infers attributes; chmod 0600 before chezmoi add --encrypt so secrets import as encrypted_private_*.age, and keep [add] secrets = "error" so plain add rejects unencrypted secrets.
  2. Preview: mise run diff (chezmoi diff --force --no-pager --exclude encrypted; narrow with mise run diff -- <target>). Diffs exclude encrypted files to keep plaintext out of transcripts; chezmoi status still shows their drift.
  3. Validate rendering: mise run check:chezmoi dry-runs against a temporary config and destination excluding encrypted files on the host OS. Exercise changed Linux/macOS branches separately and report unexercised branches or encrypted targets.
  4. Check repeatability: add existing-target and second-pass tests under dot/tests/ — Bash/profile modifiers (managed-block.tmpl, rewritten in place between markers) in test_shell_modifiers.py, JSON/TOML modifiers (config-merge.tmpl) in test_harness_config.py. Check affected run_* hooks: plain hooks run every apply; once_/onchange_ rerun when content changes.
  5. Apply in scope: mise run apply (chezmoi apply --force avoids interactive prompts on diverged targets without expanding scope). Themes (fmind/theme commit) and fonts (release URLs) are SHA-256-pinned externals; checksum mismatches fail apply. mise run upgrade advances the theme pin only when every COPIED block in dot/dot_tasks/theme_pin.py matches; font upgrades require bumping URL and checksum together.
  6. Fold target edits back: chezmoi re-add imports manual edits to managed files (e.g., Neovim lazy-lock.json); regenerate mise.lock via mise run lock, never re-add.
  7. Diagnose: mise run doctor; chezmoi managed / chezmoi unmanaged for coverage; dot orphan for former managed targets (orphans); installed-link recovery for retired skill links; dot-cli for cleanup flags.

Gotchas

  • Use # chezmoi:modify-template, not script modifiers: modifiers read .chezmoi.stdin via managed-block.tmpl or config-merge.tmpl instead of modify_*.tmpl scripts.
  • Keep secrets encrypted (*.age): never expose plaintext in sources, diffs, or logs; native seeds use create_encrypted_private_* and scoped keys live in ~/.config/dot/secrets/ (secret setup, code-security).
  • Escape foreign {{ ... }} delimiters: write {{`{{ .Destination }}`}} (including in .chezmoi.toml.tmpl); test with chezmoi execute-template < file.
  • .chezmoiignore uses templated doublestar patterns on target paths (not gitignore): skips repo-only paths (dot/, skills/, AGENTS.md) and age-dependent targets when the key is absent (dot-prefixed sources like .github/ are skipped automatically). Leading ! negates ignoring and wins regardless of order.
  • Retire targets via .chezmoiremove: deleting a source leaves its deployed target; list retired target globs in .chezmoiremove so apply deletes them recursively without prompting. Guard shared-directory entries (like skill links) with lstat/readlink checks to this checkout so third-party same-name packages survive; prune entries once retired everywhere.
  • .chezmoi.toml.tmpl seeds ~/.config/chezmoi/chezmoi.toml on chezmoi init (promptStringOnce host data, [add] secrets = "error", [edit] apply = true).

Documentation

Files (dot)
  • SKILL.md 4.8 KB
    ---
    name: chezmoi
    description: "Manage chezmoi sources, templates, age secrets, diffs, and apply in fmind/dot."
    license: MIT
    metadata:
      kind: task
      author: Médéric HURIER (Fmind)
      source: github.com/fmind/dot/tree/main/.agents/skills/chezmoi
      created: "2026-07-12"
      updated: "2026-11-11"
    ---
    
    # Chezmoi Source Standard
    
    Edit sources here per `AGENTS.md`; edits under `~/.config` or `~/.gemini` are overwritten on the next apply. [mise](../../../skills/mise/SKILL.md) tasks wrap chezmoi commands.
    
    ## Naming
    
    Pick the target type first, then attributes in [source-state reference](https://www.chezmoi.io/reference/source-state-attributes/) order (`encrypted_` → `private_` → `dot_`; wrong order yields a literal filename). Repo conventions: global skill links use `dot_agents/skills/symlink_<name>.tmpl` ([dot-skills](../dot-skills/SKILL.md)), modifiers use `# chezmoi:modify-template`, and native login seeds use `create_encrypted_private_*`.
    
    ## Workflow
    
    1. **Import an existing file**: `chezmoi add <target>` infers attributes; `chmod 0600` before `chezmoi add --encrypt` so secrets import as `encrypted_private_*.age`, and keep `[add] secrets = "error"` so plain `add` rejects unencrypted secrets.
    1. **Preview**: `mise run diff` (`chezmoi diff --force --no-pager --exclude encrypted`; narrow with `mise run diff -- <target>`). Diffs exclude encrypted files to keep plaintext out of transcripts; `chezmoi status` still shows their drift.
    1. **Validate rendering**: `mise run check:chezmoi` dry-runs against a temporary config and destination excluding encrypted files on the host OS. Exercise changed Linux/macOS branches separately and report unexercised branches or encrypted targets.
    1. **Check repeatability**: add existing-target and second-pass tests under `dot/tests/` — Bash/profile modifiers (`managed-block.tmpl`, rewritten in place between markers) in `test_shell_modifiers.py`, JSON/TOML modifiers (`config-merge.tmpl`) in `test_harness_config.py`. Check affected `run_*` hooks: plain hooks run every apply; `once_`/`onchange_` rerun when content changes.
    1. **Apply in scope**: `mise run apply` (`chezmoi apply --force` avoids interactive prompts on diverged targets without expanding scope). Themes (`fmind/theme` commit) and fonts (release URLs) are SHA-256-pinned externals; checksum mismatches fail apply. `mise run upgrade` advances the theme pin only when every `COPIED` block in `dot/dot_tasks/theme_pin.py` matches; font upgrades require bumping URL and checksum together.
    1. **Fold target edits back**: `chezmoi re-add` imports manual edits to managed files (e.g., Neovim `lazy-lock.json`); regenerate `mise.lock` via `mise run lock`, never `re-add`.
    1. **Diagnose**: `mise run doctor`; `chezmoi managed` / `chezmoi unmanaged` for coverage; `dot orphan` for former managed targets ([orphans](../../../skills/dot-cli/references/orphans.md)); [installed-link recovery](../dot-skills/references/installed-links.md) for retired skill links; [dot-cli](../../../skills/dot-cli/SKILL.md) for cleanup flags.
    
    ## Gotchas
    
    - **Use `# chezmoi:modify-template`, not script modifiers**: modifiers read `.chezmoi.stdin` via `managed-block.tmpl` or `config-merge.tmpl` instead of `modify_*.tmpl` scripts.
    - **Keep secrets encrypted (`*.age`)**: never expose plaintext in sources, diffs, or logs; native seeds use `create_encrypted_private_*` and scoped keys live in `~/.config/dot/secrets/` ([secret setup](../../../README.md#secret-management), [code-security](../../../skills/code-security/references/code-review/GUIDE.md)).
    - **Escape foreign `{{ ... }}` delimiters**: write ``{{`{{ .Destination }}`}}`` (including in `.chezmoi.toml.tmpl`); test with `chezmoi execute-template < file`.
    - **`.chezmoiignore`** uses templated doublestar patterns on target paths (not gitignore): skips repo-only paths (`dot/`, `skills/`, `AGENTS.md`) and age-dependent targets when the key is absent (dot-prefixed sources like `.github/` are skipped automatically). Leading `!` negates ignoring and wins regardless of order.
    - **Retire targets via `.chezmoiremove`**: deleting a source leaves its deployed target; list retired target globs in `.chezmoiremove` so apply deletes them recursively without prompting. Guard shared-directory entries (like skill links) with `lstat`/`readlink` checks to this checkout so third-party same-name packages survive; prune entries once retired everywhere.
    - **`.chezmoi.toml.tmpl`** seeds `~/.config/chezmoi/chezmoi.toml` on `chezmoi init` (`promptStringOnce` host data, `[add] secrets = "error"`, `[edit] apply = true`).
    
    ## Documentation
    
    - [chezmoi reference](https://www.chezmoi.io/reference/) · [source-state attributes](https://www.chezmoi.io/reference/source-state-attributes/) · [templating](https://www.chezmoi.io/user-guide/templating/) · [age encryption](https://www.chezmoi.io/user-guide/encryption/age/) · [releases](https://github.com/twpayne/chezmoi/releases)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.