agentleFS
ivyivy/dotfiles/.claude/skills/mise/SKILL.md

mise

Skill16 starsChanged 3 days agoISCView on GitHub

Use when adding, updating, troubleshooting, or managing mise tool dependencies. Supplements /install with mise-specific context about backends, lockfiles, and the github-first policy.

9 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 3 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

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

    Verify the tool runs. Check the binary name — it may differ from the repo name (e.g., BurntSushi/ripgrep installs rg).

    line 98
  2. Distinctive:

    Check current vs latest:

    line 103
  3. Very specific:

    If assets exist but use unusual naming, the github: backend may not auto-detect them.

    line 143
  4. Very specific:

    Use the full tag string as the version (e.g., jq-1.8.1 not 1.8.1).

    line 157
  5. Very specific:

    Never use latest — always pin to a specific version

    line 169
  6. Distinctive:

    Always regenerate lockfile after config changes

    line 170
  7. Distinctive:

    Always verify the tool runs after installing

    line 171

“Common” is measured: kept by at least 6 in 10 of the 6 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

Mise Tool Management

Mise-specific context for managing CLI tool dependencies. Use /install to add a new tool end-to-end; use /mise when you need to understand backends, troubleshoot failures, update versions, or regenerate lockfiles.

Arguments

$ARGUMENTS

Key Files

FilePurpose
home/dot_config/mise/config.tomlUser tool manifest — edit here, never ~/.config/mise/config.toml
home/dot_config/mise/mise.lockUser lockfile (auto-generated); ~/.config/mise/mise.lock is a symlink to it
home/dot_config/mise/.mise/locks/, .mise/locks/npm dependency graphs the lockfiles reference by path and digest (auto-generated)
mise.tomlProject dev tool manifest (bats, shellcheck, hk, etc.)
mise.lockProject lockfile (auto-generated)
home/run_onchange_00-install-mise-tools.sh.tmplInstall trigger — runs on config/lock hash change

Backend Priority

Per ADR-005:

PriorityBackendWhen to use
1Native (python, node)Runtimes
2github:owner/repoCLI tools with GitHub releases
3cargo:Rust tools without prebuilt binaries
4pipx:Python CLI tools
5npm:Node CLI tools

Do NOT use aqua: backend. Registry lag and attestation mismatches break chezmoi apply. The github: backend talks directly to GitHub Releases with checksum, attestation, and SLSA verification.

Instructions

Adding a tool

  1. Find the GitHub repo and latest release tag:
    gh release view --repo owner/repo --json tagName --jq '.tagName'
  2. Determine version format — most use bare numbers (0.18.2) or v-prefixed tags (mise strips the v automatically). Some tools use non-standard tags (e.g., jq uses jq-1.8.1). If the tag doesn't follow vX.Y.Z, use the full tag string as the version.
  3. Edit home/dot_config/mise/config.toml — add under the CLI tools section:
    "github:owner/repo" = "1.2.3"
  4. Apply and regenerate lockfile:
    chezmoi apply ~/.config/mise/config.toml
    mise install --yes
    mise --cd home/dot_config/mise lock
  5. Verify the tool runs. Check the binary name — it may differ from the repo name (e.g., BurntSushi/ripgrep installs rg).

Updating a tool

  1. Check current vs latest:
    mise ls
    gh release view --repo owner/repo --json tagName --jq '.tagName'
  2. Edit the version in home/dot_config/mise/config.toml
  3. Apply, install, and regenerate lockfile:
    chezmoi apply ~/.config/mise/config.toml
    mise install --yes
    mise --cd home/dot_config/mise lock

Regenerating lockfiles

There are two lockfiles pinning checksums across 7 platforms (linux-arm64, linux-arm64-musl, linux-x64, linux-x64-musl, macos-arm64, macos-x64, windows-x64). Regenerate both after any config change:

mise lock                            # project-level (mise.toml)
mise --cd home/dot_config/mise lock  # user-level (config.toml)

~/.config/mise/mise.lock is a symlink to the user lockfile in this repository, so there is no deployed copy to keep in step. Anything mise install or mise use writes to the lockfile, or to the dependency graphs under .mise/locks/, shows up as a change in the working tree. Commit the graphs with the lockfile; never reformat them, because the lockfile records a digest of each.

Troubleshooting install failures

"No matching asset found" — The tool doesn't publish binaries matching the expected platform naming. Check available assets:

gh release view --repo owner/repo --json assets --jq '.assets[].name'

If assets exist but use unusual naming, the github: backend may not auto-detect them. Options:

  • Install via cargo: backend if it's a Rust tool
  • Pull source via chezmoiexternal with a wrapper script in ~/.local/bin

"No GitHub attestations found" — This was the aqua failure mode. The github: backend handles missing attestations gracefully — it verifies when available but doesn't block when absent.

Non-standard release tags — If mise install returns 404, the tag format likely doesn't match. Check the actual tag:

gh release view --repo owner/repo --json tagName --jq '.tagName'

Use the full tag string as the version (e.g., jq-1.8.1 not 1.8.1).

Lockfile conflicts — Delete and regenerate both:

mise lock                            # project-level
mise --cd home/dot_config/mise lock  # user-level

Rules

  • Edit home/dot_config/mise/config.toml, never ~/.config/mise/config.toml
  • Pin exact versions for all tools — Renovate handles updates
  • Never use latest — always pin to a specific version
  • Always regenerate lockfile after config changes
  • Always verify the tool runs after installing

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.