agentleFS
alunduilalunduil/alunduil-chezmoi/.claude/skills/add-tool/SKILL.md

add-tool

Skill2 starsChanged 4 days ago0BSDView on GitHub

Decide where a new tool slots into the chezmoi bootstrap and host-status. Use when adding a CLI/binary to the host bootstrap so it lands in the right install pass and host-status reports it when missing or logged out.

  • Installs packages

21 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-provider and release.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • PydanticSkill

    add-provider

    Add a new inference provider to genai-prices, including provider data, matching, usage extractors, update automation, cassettes, agentic checks, generated artifacts, and Python/JavaScript/Go parity tests. Use for a new provider, not a new model on an existing provider.

    Also in 3 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 4 projects that use this

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 20 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All passes live under .chezmoiscripts/.

    line 47
  2. Very specific:

    Add the tool under [tools] in dot_config/mise/config.toml, at an exact version, sorted by tool name.

    line 79
  3. Very specific:

    Commit config.toml, mise.lock, and any new sidecar under dot_config/mise/.mise/locks/.

    line 91
  4. Very specific:

    When the tool prints a bash completion script, add dot_local/share/bash-completion/completions/<command> holding one line that evals it, …

    line 100
  5. Very specific:

    Update host-status: a check_login line for an auth-required tool, and a commands entry for one installed outside apt and mise.

    line 112
  6. Distinctive:

    Add a Shell completion file if the tool generates one.

    line 115
  7. Distinctive:

    Run sensors before claiming done:

    line 117

“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 host-status entry.

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): add a check_login line to check_logins in dot_local/bin/executable_host-status.tmpl, testing local state the login leaves behind (a credential file, or a command that reads it without the network). Auth state is runtime, never managed by chezmoi.
  • No (zellij, lazygit, act, gh-poi): no login line.

Missing-tool report

host-status derives apt packages from .chezmoidata/packages.yaml and pinned tools from mise ls --missing, so those need no entry. A tool installed any other way (npm, cargo, uv, ghcup, an upstream installer) goes in its commands array.

Install mechanism

All passes live under .chezmoiscripts/.

Pick the canonical installer for the ecosystem:

SourceWherePattern
Debian package.chezmoidata/packages.yamlappend to packages.apt
Pinned binary releasedot_config/mise/config.tomlmise entry below
npm packagerun_before_03npm install -g, command -v
Cargo craterun_before_09cargo install, command -v
PyPI packagerun_after_install-via-mise-toolsmirror the beets block

Raise a release binary that mise can't verify against its publisher, such as one signed only with GPG, with the user before adding it.

Auth and install axes are independent: gcx is auth-required and a mise tool.

Install a gh extension as a mise tool, then link ~/.local/share/gh/extensions/gh-<name>/gh-<name> to its shim, as gh-poi does.

Pin the version

Annotate each PyPI *_VERSION pin, --with extras included, with # renovate: datasource=pypi depName=<pkg> on the line above it.

A mise tool needs no annotation: Renovate's mise manager reads config.toml and updates mise.lock in the same PR.

mise entry

Add the tool under [tools] in dot_config/mise/config.toml, at an exact version, sorted by tool name. Use the short name when mise registry <tool> lists one; otherwise use "github:<owner>/<repo>". Then lock it with just lock-tools.

script/checks/pinned-tools runs <last segment of the config.toml name> --version and expects it to exit 0. Add any tool that needs another command to RUN_COMMANDS there, or an empty entry for a library with nothing to run. A TUI also goes in TUI, which runs it in a pseudo-terminal and expects it still running at the timeout.

Commit config.toml, mise.lock, and any new sidecar under dot_config/mise/.mise/locks/.

A pass that runs the new tool is run_after_, since shims resolve through the ~/.config/mise that apply deploys. Call use_mise_shims from script/lib/bootstrap.sh, then the tool by name.

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 mise entry.
  4. Update host-status: a check_login line for an auth-required tool, and a commands entry for one installed outside apt and mise.
  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:

    prek run --all-files
    bats --recursive dot_local dot_claude etc script
    script/checks/chezmoi-apply
    script/checks/pinned-tools

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.