add-tool

Decide where a new tool slots into the chezmoi bootstrap and README. Use when adding a CLI/binary to the host bootstrap so it lands in the right install pass and the right README block. Routes auth-re

SKILL.md

GitHub

Add a tool to bootstrap

First check the tool belongs on the host, then make two decisions independently.

Libraries with no console script

uv tool install needs an executable, so a PyPI library takes one of two shapes:

  1. An installed tool imports it (plugins, optional backends): add it as a pinned --with extra on that tool, as beets carries pyacoustid.
  2. Otherwise, keep it off the host. The caller runs uv run --with <pkg>==<version> <script> and owns the pin. Stop here: no bootstrap change, no README line.

Install a CLI front-end that wraps the library only when its command is itself wanted.

Auth axis

Does the tool need interactive auth (login, browser flow, API token) to do real work?

  • Yes (gh, claude, gcx, readwise, tailscale): list in README "Interactive logins" with a config-path comment so a fresh-host bootstrap surfaces where state lands. No PATH-check line — running the login command itself proves reachability. Auth state is runtime, never managed by chezmoi.
  • No (zellij, lazygit, act, gh-poi): list in README "PATH check" line.

Install mechanism

All passes live under .chezmoiscripts/.

Pick the canonical installer for the ecosystem:

Source Where Pattern
Debian package .chezmoidata/packages.yaml append to packages.apt
Pinned binary release .chezmoiexternal.toml external entry below
npm package run_before_03 npm install -g, command -v
Cargo crate run_before_09 cargo install, command -v
gh extension run_before_05 gh extension install --pin
PyPI package run_after_install-via-externals mirror the beets block

A release binary that needs more than a download (signature check, source build) gets a script/install/<tool> script, called from run_before_02 instead; mirror script/install/signal-cli.

Auth and install axes are independent: gcx is auth-required and a chezmoi external; gh-poi is fire-and-forget and uses gh extension install.

Pin the version

Annotate each *_VERSION pin on the line directly above it:

Source Annotation
Script-installed tool # renovate: datasource=github-releases depName=<owner>/<tool>
PyPI package # renovate: datasource=pypi depName=<pkg>, one per --with extra too

An external needs no annotation: its version lives in the download URL.

External entry

Add an entry to .chezmoiexternal.toml, mirroring vale or lazygit. Write the literal release URL, version included wherever the asset name repeats it:

[".local/bin/<tool>"]
    type = "archive-file"
    url = "https://github.com/<owner>/<tool>/releases/download/vX.Y.Z/<tool>_X.Y.Z_<arch>.tar.gz"
    path = "<tool>"
    executable = true

Renovate bumps every copy of the version in the URL. Use type = "file" for a raw binary asset. A release asset carries no checksum (ADR 0008); a GitHub source-archive tarball (archive/refs/tags/…) pins checksum.sha256.

A pass that runs the new binary is run_after_, since externals deploy during apply.

Shell completion

When the tool prints a bash completion script, add dot_local/share/bash-completion/completions/<command> holding one line that evals it, mirroring just. bash-completion sources the file on the first Tab, so the script always matches the installed version.

Procedure

  1. For a library with no console script, settle its shape first; stop if it stays off the host.

  2. Identify the auth axis and install mechanism.

  3. Wire the installer into the right .chezmoiscripts/ pass, or add the external entry.

  4. Update README:

    • Auth-required → add to "Interactive logins" with config-path comment
    • Fire-and-forget → add to "PATH check" line
  5. Annotate every pin per Pin the version.

  6. Add a Shell completion file if the tool generates one.

  7. Run sensors before claiming done:

    pre-commit run --all-files
    bats --recursive dot_local dot_claude script
    script/checks/chezmoi-apply