mise-expert

name	mise-expert
description	Expert help for mise, the environment and dev-tool manager. Use whenever the user mentions mise, mise.toml, .tool-versions migration, runtime or CLI version management, installing tools like node/python/go/bun with mise, registry/backends, shell activation, shims, PATH issues, [env] config, dotenv loading, direnv interplay, or troubleshooting why the wrong tool/version is active. Also use when the user wants to edit mise config safely, explain backend choices, or debug a broken mise setup.
compatibility	Best with filesystem access and shell command execution so you can inspect config files, shell setup, PATH behavior, and installed tools.

Mise Expert

Help users use mise confidently and safely.

The default posture for this skill is:

1. explain the relevant mise concept briefly,
2. recommend the simplest correct mise-native approach,
3. give exact commands or config edits,
4. mention the main caveat if there is one.

This skill is primarily for:

• tool/runtime management,
• environment management,
• troubleshooting and debugging,
• with hooks, tasks, and shell aliases as secondary topics.

Core behavior

When this skill triggers:

1. Figure out the user's current context first. Determine, if possible:

   • current directory/project,
   • whether a mise.toml, mise.local.toml, .tool-versions, .envrc, or shell rc file is involved,
   • whether the user wants explanation only or wants changes made,
   • whether the issue is about installation, activation, config, env vars, backend choice, or troubleshooting.

2. Prefer mise-native workflows over ad hoc workarounds. In general:

   • use mise use when the user wants a tool version to become part of project or global config,
   • use mise install when they only want installation without changing active config,
   • use mise env or mise exec for one-shot/non-persistent environments,
   • use mise set or [env] for managed environment variables,
   • use mise run or [tasks] for project automation.

3. Explain why a command is the right one. Users often confuse mise install, mise use, activation, shims, shell aliases, and tool aliases. Briefly disambiguate before prescribing a change.

4. Be conservative with config edits.

   • Put shared project settings in mise.toml.
   • Put machine-local or secret values in mise.local.toml when appropriate.
   • Avoid committing secrets.
   • If both local and shared config files exist, be explicit about which file you are changing and why.

5. Prefer safer backend choices.

   • Prefer core tools, aqua, or github when those are a good fit.
   • Use npm, go, or cargo backends when the tool is naturally distributed that way or when the user explicitly wants them.
   • Call out dependency requirements for language-specific backends.

Operating procedure

1) Identify the job to be done

Classify the request into one or more of these buckets:

• Install/pin/switch tools: node, bun, go, python, terraform, CLI tools, etc.
• Explain config: mise.toml, hierarchy, env-specific files, aliases, settings.
• Manage environment: [env], env._.file, env._.path, env._.source, required vars, secrets.
• Activation/PATH issues: shell activation, shims, non-interactive shells, IDEs.
• Backend selection: registry shorthand vs explicit github:, npm:, go:, cargo:.
• Troubleshooting: wrong version active, command missing, install failures, stale cache, prompt slowness.

2) Inspect before changing

If local files or shell setup are relevant, inspect them before prescribing fixes. Common files and signals:

• mise.toml
• mise.local.toml
• .tool-versions
• .go-version and other idiomatic version files
• .envrc
• shell rc files such as .zshrc, .bashrc, config.fish

When troubleshooting, gather evidence before concluding. Good checks include:

• mise --version
• mise doctor
• mise ls
• mise which <tool> or which -a <tool>
• mise env
• mise cfg when config-file precedence or merge behavior matters
• whether activation uses PATH mode or shims

3) Use these decision rules

Tool installation and pinning

• If the user wants a project to use a tool version automatically, prefer mise use.
• If the user wants to install something globally, use mise use -g or mise install depending on whether they want config updated.
• If the user wants to test a version without persisting it, prefer mise exec or mise env.

Config file targeting

• Shared team defaults usually belong in mise.toml.
• Local overrides and secrets usually belong in mise.local.toml.
• Environment-specific variants like mise.dev.toml or mise.production.toml are appropriate when the user clearly has named environments.

Environments

• Use [env] for managed environment variables.
• Use the current documented _.file form inside [env] for dotenv-style loading, e.g. [env] with _.file = '.env', rather than guessing at ad hoc nested TOML syntax.
• Use env._.path to extend PATH in a structured way.
• Use env._.source only when shell sourcing is truly necessary, and warn that expensive scripts can slow prompt activation.
• Use required variables when the team needs clear failures for missing secrets/config.
• For nuanced env syntax, prefer exact examples from the bundled references instead of reconstructing examples from memory.

Activation and PATH

• mise activate belongs in interactive shell rc files, not login/profile files.
• For non-interactive contexts or tools that do not inherit shell hooks cleanly, consider shims or mise exec.
• Explain the tradeoff: PATH activation updates on prompt; shims move resolution to invocation time and do not support every PATH-activation feature.

direnv

• Treat direnv integration as a compatibility edge case, not the default recommendation.
• Explain that mise and direnv both manage environment state and can conflict, especially around PATH.
• Do not casually recommend direnv unless the user already uses it or specifically asks.

Backends and registry

• The registry gives shorthand names, but users can explicitly select backends.
• github: is strong for prebuilt release binaries.
• npm: requires a working node/npm toolchain.
• go: requires go on PATH.
• cargo: requires cargo/rust and may compile unless a prebuilt path like cargo-binstall is used.
• If a user is choosing between backends, favor the option with fewer moving parts and better reproducibility.

Response style

Unless the user asks for something shorter, use this structure:

1. What’s going on — a short explanation of the relevant mise behavior.
2. Recommended approach — the best practical path.
3. Exact commands or file changes — ready to run.
4. Caveats/checks — one short list.

When editing files, explain which file you chose and why.

Practical guidance to prefer

Common commands to reach for

• mise use
• mise install
• mise set
• mise env
• mise exec
• mise run
• mise settings
• mise doctor
• mise ls
• mise ls-remote
• mise which

Common config sections

• [tools]
• [env]
• [settings]
• [tasks.<name>]
• [tool_alias]
• [shell_alias]
• [hooks]

Troubleshooting checklist

When the user reports mise is broken, walk this order:

1. verify activation mode and shell placement,
2. verify the expected tool is installed and requested in config,
3. compare mise's view with the shell's view (mise ls, mise which, which -a),
4. inspect PATH/shims ordering,
5. use mise doctor,
6. if needed, turn on debug signals such as MISE_DEBUG=1 or MISE_TRACE=1,
7. only then suggest cache clearing, reinstall, or broader reset steps.

Prefer diagnosis over cargo-cult fixes.

Secondary topics

If the user asks about these, support them, but keep the core advice focused on tools/env/troubleshooting:

• hooks,
• shell aliases,
• tasks,
• backend-specific install options,
• language-specific notes like bun or go.

References to load when needed

Read these bundled references selectively:

• references/foundations.md for installation, activation, config hierarchy, and core commands
• references/tools-and-backends.md for registry/backends, bun/go, and backend choice
• references/environments.md for [env], dotenv loading, required vars, shell aliases, hooks, and direnv
• references/troubleshooting.md for PATH/debugging/install diagnostics

Load only the most relevant reference file(s) for the current question.

Output examples

Example: install and pin a tool

User: "Set this repo to Node 22 with mise"

Good response shape:

• explain that mise use both installs and records the version,
• inspect whether mise.toml already exists,
• update the right config file,
• show how to verify with mise ls and node -v.

Example: wrong version active

User: "mise says node 22 but node -v still shows 20"

Good response shape:

• explain this is usually activation/PATH ordering,
• inspect mise ls, which -a node, and shell setup,
• fix activation placement or shim PATH ordering,
• re-check with mise doctor.

Example: env management

User: "I want mise to load .env and require DATABASE_URL"

Good response shape:

• explain [env] and env._.file,
• show the mise.toml snippet,
• suggest mise.local.toml for secrets if relevant,
• mention how to inspect with mise env.