@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mise/references/configuration/vars-html.md

@@ -0,0 +1,167 @@
+Variables
+
+Variables [​](#variables)
+
+Define shared configuration values in `[vars]` and reference them with `{{ vars.NAME }}` in a [Tera template](https://mise.jdx.dev/templates.html). Use vars for values that mise needs to render configuration; use [`[env]`](https://mise.jdx.dev/environments/) for values that commands need as environment variables. mise does not export vars to child processes.
+
+mise-toml
+
+```
+[vars]
+node_version = "24"
+test_mode = "headless"
+
+[tools]
+node = "{{ vars.node_version }}"
+
+[tasks.test]
+run = "echo {{ vars.test_mode | quote }}"
+```
+
+Run `mise run test` to print `headless`. `test_mode` is available through the `vars` template map, but it is not exported as `$test_mode`. The `quote` filter in this example targets POSIX shells; see [template quoting](https://mise.jdx.dev/templates.html#string-manipulation).
+
+Vars are available to Tera-rendered configuration such as tool versions and options, task definitions, hooks, task includes, watch configuration, and dotfile templates. See [Templates](https://mise.jdx.dev/templates.html) for the complete template syntax and context.
+
+## When vars are resolved [​](#when-vars-are-resolved)
+
+mise resolves top-level `[vars]` entries while loading configuration, before applying any task-local vars. Each entry can reference vars resolved before it. The resulting value is stored as a string; referencing that value later does not evaluate its template again.
+
+mise-toml
+
+```
+[vars]
+mode = "headless"
+args = "--mode={{ vars.mode }}"
+```
+
+Here, `args` resolves to `--mode=headless`. A later override of `mode` changes references to `vars.mode`, but does not recalculate `args`. To change `args`, override `args` itself or move the expression into the task that needs it.
+
+## Configuration hierarchy [​](#configuration-hierarchy)
+
+Vars follow mise's [configuration hierarchy](https://mise.jdx.dev/configuration.html#configuration-hierarchy). Define shared values globally, then override them in project, local, or environment-specific config files.
+
+For example, a default can be defined globally:
+
+\~/.config/mise/config.toml
+
+mise-toml
+
+```
+[vars]
+test_mode = "headless"
+```
+
+Then overridden for a project:
+
+mise.local.toml
+
+mise-toml
+
+```
+[vars]
+test_mode = "headed"
+```
+
+## Task-local vars [​](#task-local-vars)
+
+TOML tasks can define their own vars. Task-local values override config vars while that task is rendered, but do not change the vars available elsewhere in the configuration.
+
+mise-toml
+
+```
+[vars]
+test_mode = "headless"
+
+[tasks.test]
+vars = { test_mode = "headed" }
+run = "echo {{ vars.test_mode | quote }}"
+```
+
+Here, `mise run test` prints `headed`; other tasks still see `headless` unless they define their own override. See [Task Configuration](https://mise.jdx.dev/tasks/task-configuration.html#task-vars) for task-local vars.
+
+### What a task-local var can change [​](#what-a-task-local-var-can-change)
+
+A task-local override changes direct references to that var in the task's templated fields, including fields inherited from a task template. It does not recalculate top-level vars that used the original value:
+
+mise-toml
+
+```
+[vars]
+mode = "headless"
+args = "--mode={{ vars.mode }}"
+
+[tasks.test]
+vars = { mode = "headed" }
+run = "echo {{ vars.args }} / {{ vars.mode }}"
+```
+
+`mise run test` prints:
+
+text
+
+```
+--mode=headless / headed
+```
+
+`args` was resolved before the task-local override. The reference to `vars.mode` in `run` uses the task's value, `headed`.
+
+To make the argument use the task's mode, build it in `run`:
+
+mise-toml
+
+```
+[tasks.test]
+vars = { mode = "headed" }
+run = "echo --mode={{ vars.mode }}"
+```
+
+This prints `--mode=headed`. For several tasks that share the same command, put `run` in a [task template](https://mise.jdx.dev/tasks/templates.html#parameterizing-a-template-with-vars) and let each task supply its vars.
+
+### Missing vars and defaults [​](#missing-vars-and-defaults)
+
+A top-level var cannot reference a value that exists only in a task's `vars`. Without a fallback, that reference fails when mise loads the configuration.
+
+The Tera `default` filter provides a fallback at the point where the expression is rendered:
+
+mise-toml
+
+```
+[vars]
+args = "--mode={{ vars.mode | default(value='headless') }}"
+
+[tasks.test]
+vars = { mode = "headed" }
+run = "echo {{ vars.args }} / {{ vars.mode }}"
+```
+
+This also prints `--mode=headless / headed`. The filter supplies `headless` while loading `[vars]`; it does not defer evaluation until the task supplies `mode`. Use a fallback when a missing value is expected, and put expressions that depend on task-local values in the task or its template.
+
+## Value directives [​](#value-directives)
+
+Vars support the same value-producing directives as [`[env]`](https://mise.jdx.dev/environments/), including defaults, required values, redaction, files, sources, and [secrets](https://mise.jdx.dev/environments/secrets/).
+
+mise-toml
+
+```
+[vars]
+test_mode = { default = "headless" }
+api_token = { required = "Set api_token in mise.local.toml" }
+secret_arg = { value = "--token=abc123", redact = true }
+_.file = ".env"
+```
+
+The `default` form uses a process environment variable with the same name when it is set and non-empty; values from `[env]` are not used for this lookup. A `required` var must be supplied by the process environment or a later config file. Values marked `redact = true` are hidden from task output.
+
+See the [`env._` directive reference](https://mise.jdx.dev/environments/#env-directives) for the available file, source, and plugin-provided directive forms. When used under `[vars]`, these directives populate `vars` instead of exporting the values as environment variables.
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/configuration/vars.md)
+
+Last updated:
+
+Pager
+
+[Previous pagemise.toml](https://mise.jdx.dev/configuration.html)
+
+[Next pageProject Diagnostics](https://mise.jdx.dev/configuration/project-diagnostics.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)

package/skills/working-with-mise/references/dev-tools/aliases-html.md

@@ -0,0 +1,97 @@
+Tool Aliases
+
+Tool Aliases [​](#tool-aliases)
+
+Use `[tool_alias]` to give a tool a different backend or name a version request. Put shared aliases in the project's `mise.toml`; use `~/.config/mise/config.toml` for personal defaults. Teammates need the alias definition as well as the tool declaration.
+
+Renamed configuration key
+
+`[alias]` was renamed to `[tool_alias]`. The old key still works but is deprecated. For command shortcuts such as `alias ll='ls -la'`, use [Shell Aliases](https://mise.jdx.dev/shell-aliases.html).
+
+## Aliased Backends [​](#aliased-backends)
+
+A backend alias changes where mise obtains a tool. For example, explicitly choose mise's built-in Node.js backend:
+
+mise.toml
+
+toml
+
+```
+[tool_alias]
+node = "core:node"
+
+[tools]
+node = "24"
+```
+
+Inspect the result with `mise tool node`, then run `mise install` to install the selected version. See [backend selection](https://mise.jdx.dev/dev-tools/backend_architecture.html#how-backend-selection-works) if an installed plugin or environment override selects a different source than expected.
+
+Aliases can also select separate release assets from the same GitHub repository:
+
+mise.toml
+
+toml
+
+```
+[tool_alias]
+dhall-json = "github:dhall-lang/dhall-haskell"
+dhall-lsp = "github:dhall-lang/dhall-haskell"
+
+[tools]
+dhall-json = { version = "v1.42.2", matching = "dhall-json" }
+dhall-lsp = { version = "latest", matching = "dhall-lsp-server" }
+```
+
+Each alias has its own version request and [GitHub asset filter](https://mise.jdx.dev/dev-tools/backends/github.html#matching). This matters for repositories that release several tools independently.
+
+## Aliased Versions [​](#aliased-versions)
+
+A version alias gives a stable name to a version request. Keep a team's Node.js release series in one place:
+
+mise.toml
+
+toml
+
+```
+[tool_alias.node.versions]
+project-lts = "24"
+
+[tools]
+node = "project-lts"
+```
+
+`project-lts` resolves as a request for Node.js 24. It is not an exact patch pin; use [mise.lock](https://mise.jdx.dev/dev-tools/mise-lock.html) to record the resolved version. Changing the alias changes the request for every declaration that uses it.
+
+The built-in Node.js backend already supplies aliases such as `lts` and named LTS releases. You don't need to redefine those. Legacy asdf plugin authors can provide their own aliases through `bin/list-aliases`, with one alias and version per line:
+
+bash
+
+```
+#!/usr/bin/env bash
+printf '%s\n' 'recommended 2.0' 'legacy 1.0'
+```
+
+## Templates [​](#templates)
+
+Alias values support [templates](https://mise.jdx.dev/templates.html). For example, allow an explicit environment override with a default release series:
+
+toml
+
+```
+[tool_alias.node.versions]
+project-lts = "{{ env.PROJECT_NODE_VERSION | default(value='24') }}"
+```
+
+Set `PROJECT_NODE_VERSION` before invoking mise. Avoid computing a tool's version by invoking that same tool from its alias template: version resolution may happen before the tool is available, or re-enter mise through a shim.
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/aliases.md)
+
+Last updated:
+
+Pager
+
+[Previous pageShims](https://mise.jdx.dev/dev-tools/shims.html)
+
+[Next pageTool Stubs](https://mise.jdx.dev/dev-tools/tool-stubs.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)

package/skills/working-with-mise/references/dev-tools/backend_architecture-html.md

@@ -0,0 +1,198 @@
+Backend Architecture
+
+Backend Architecture [​](#backend-architecture)
+
+A backend resolves a tool's versions, installs it, and supplies its executable paths and environment. The [registry](https://mise.jdx.dev/registry.html) maps short names such as `node` and `ripgrep` to backends. Start with those names; choose an explicit backend when you need a particular distribution or a tool outside the registry.
+
+## What are Backends? [​](#what-are-backends)
+
+In `github:BurntSushi/ripgrep`, `github` is the backend and `BurntSushi/ripgrep` identifies the upstream project. These are separate from the version request after `@`:
+
+sh
+
+```
+mise ls-remote github:BurntSushi/ripgrep
+mise use github:BurntSushi/ripgrep@latest
+mise exec -- rg --version
+```
+
+Installing a tool through a backend does not add a new entry to mise's registry. Explicit backend syntax works directly in your own configuration.
+
+## The Backend Trait System [​](#the-backend-trait-system)
+
+Built-in backends implement the Rust [`Backend` trait](https://github.com/jdx/mise/blob/main/src/backend/mod.rs). The installation flow uses that interface to:
+
+1. List versions or resolve a request such as a prefix or channel.
+2. Identify installation dependencies and tool options.
+3. Download or build the requested version and perform the verification supported by that distribution.
+4. Record the installation and expose executable paths and environment variables.
+
+Version strings are not necessarily semantic versions. Backends can support date releases, vendor prefixes, tags, and rolling channels; the backend determines what `latest` means. A lockfile records a concrete resolution. See [version ordering](https://mise.jdx.dev/dev-tools/#version-ordering) and [mise.lock](https://mise.jdx.dev/dev-tools/mise-lock.html).
+
+For extension APIs, see [tool plugins](https://mise.jdx.dev/tool-plugin-development.html) and [backend plugins](https://mise.jdx.dev/backend-plugin-development.html). Their hook interfaces are separate from the internal Rust trait.
+
+## Backend Types [​](#backend-types)
+
+| Distribution method | Examples | What to check |
+| --- | --- | --- |
+| Built-in language support | Node.js, Python, Java, Rust | Language-specific options, system libraries, and any build tools required |
+| Signed release manifests | `packslip:` | Published manifest, trusted signer, and supported platform |
+| Registry-described downloads | `aqua:` | Package entry and its per-version download/verification rules |
+| Forge releases | `github:`, `gitlab:`, `forgejo:` | Matching release assets for the target platform |
+| Direct artifacts | `http:`, `s3:` | Artifact location, authentication, platform mapping, and integrity information |
+| Language packages | `npm:`, `pipx:`, `cargo:`, `gem:`, `go:`, `dotnet:` | Required runtime or toolchain and package-manager behavior |
+| Other package sources | `conda:`, `pkgx:`, `spm:` | Backend-specific platform support and dependencies |
+| External plugins | asdf, vfox tool plugins, backend plugins | Plugin code, prerequisites, and supported platforms |
+
+The [backend reference](https://mise.jdx.dev/dev-tools/backends/) lists available backends and their options. Built-in language guides are under **Languages** in the sidebar.
+
+## How Backend Selection Works [​](#how-backend-selection-works)
+
+An explicit identifier such as `core:node` expresses a backend choice. A short name such as `node` also depends on configuration and local state:
+
+- `[tool_alias]` and `[plugins]` can select another source.
+- A matching lockfile entry can preserve the backend used for that resolution.
+- An installed external plugin can override a registry shorthand, including a built-in language tool. Disabled backends and existing installations also affect this choice.
+- Otherwise, the registry supplies the preferred available backend, which can depend on the requested version and platform.
+
+Use `mise tool <name>` to inspect the effective backend instead of inferring it from the tool's short name. The [resolution implementation](https://github.com/jdx/mise/blob/main/src/cli/args/backend_arg.rs) contains the detailed precedence rules.
+
+### Environment Variable Overrides [​](#environment-variable-overrides)
+
+`MISE_BACKENDS_<TOOL>` overrides the backend for that identifier. Convert the name to uppercase and replace hyphens with underscores. For example, in a POSIX shell:
+
+sh
+
+```
+MISE_BACKENDS_NODE=core:node mise tool node
+```
+
+An exported override affects subsequent commands and can override configuration choices. Check your environment when two machines resolve the same shorthand differently.
+
+### Registry System [​](#registry-system)
+
+Inspect a registry mapping with `mise registry node`. To commit a backend choice without changing the registry, use an [alias](https://mise.jdx.dev/dev-tools/aliases.html):
+
+mise.toml
+
+toml
+
+```
+[tool_alias]
+node = "core:node"
+
+[tools]
+node = "24"
+```
+
+## Backend Capabilities Comparison [​](#backend-capabilities-comparison)
+
+Verification and platform support depend on both the backend and the particular tool. A backend supporting Windows does not imply every package it installs has a Windows release. Likewise, downloading a checksum does not establish the publisher's identity unless that checksum is authenticated.
+
+Consult each backend's verification options and the [security guide](https://mise.jdx.dev/security.html). For example, packslip verifies signed manifests, and aqua can apply the verification methods declared by its registry entry. External plugin code runs locally and must be trusted along with the tool itself.
+
+## When to Use Each Backend [​](#when-to-use-each-backend)
+
+Start with a registry shorthand for supported tools. For another source:
+
+- Use `packslip:` when the publisher provides signed release manifests.
+- Use `aqua:` when its registry describes the required tool and releases.
+- Use a forge backend for release assets, or `http:` or `s3:` for artifacts you distribute directly.
+- Use a language package backend when you need that ecosystem's package and can supply its runtime or build dependencies.
+- Use a plugin when installation or environment setup needs custom logic.
+
+Deprecated backend
+
+`ubi:` is deprecated. Use the corresponding `github:` or `gitlab:` backend and review its options when migrating; see the [ubi migration guide](https://mise.jdx.dev/dev-tools/backends/ubi.html).
+
+## Backend Dependencies [​](#backend-dependencies)
+
+Backends may need another tool during installation. Declare the required tools alongside the package so mise can install them in order:
+
+mise.toml
+
+toml
+
+```
+[tools]
+node = "24"
+"npm:prettier" = "3"
+```
+
+A dependency relationship does not automatically add missing tools to your configuration. A matching configured tool is installed first; an unconfigured dependency may be satisfied by a suitable executable on the existing `PATH`. Otherwise installation fails. See [tool dependencies](https://mise.jdx.dev/dev-tools/#tool-dependencies) for explicit `depends` declarations.
+
+## Configuration and Overrides [​](#configuration-and-overrides)
+
+### Disable Backends [​](#disable-backends)
+
+Use the global settings file to prevent installation through selected backends:
+
+\~/.config/mise/config.toml
+
+toml
+
+```
+[settings]
+disable_backends = ["asdf", "vfox"]
+```
+
+Disabled backends are excluded from tool resolution and new installs. Existing installations are left on disk and become available again if the backend is re-enabled.
+
+### Force Backend for Tool [​](#force-backend-for-tool)
+
+An explicit identifier can be used directly as a tool key:
+
+mise.toml
+
+toml
+
+```
+[tools]
+"core:node" = "24"
+"aqua:BurntSushi/ripgrep" = "latest"
+```
+
+### Backend-Specific Settings [​](#backend-specific-settings)
+
+Read the selected backend's reference before adding options. For example, this selects an optional extra from a Python package:
+
+mise.toml
+
+toml
+
+```
+[tools]
+python = "3.14"
+uv = "latest"
+"pipx:black" = { version = "latest", extras = ["jupyter"] }
+```
+
+The [pipx backend](https://mise.jdx.dev/dev-tools/backends/pipx.html) can use uv or pipx. Backend options are not interchangeable with options for another distribution of the same tool.
+
+## Troubleshooting Backend Issues [​](#troubleshooting-backend-issues)
+
+### Debug Backend Selection [​](#debug-backend-selection)
+
+sh
+
+```
+mise tool node       # effective backend and tool information
+mise plugins ls      # external plugins that may override defaults
+mise config ls       # configuration files contributing to this directory
+mise ls --current    # selected versions and their sources
+mise doctor          # installation and activation diagnostics
+```
+
+If selection is correct but installation fails, check the backend's prerequisites, platform support, and authentication requirements. `MISE_DEBUG=1 mise install node` adds diagnostic output; review logs for credentials before sharing them.
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/backend_architecture.md)
+
+Last updated:
+
+Pager
+
+[Previous pageDeps](https://mise.jdx.dev/dev-tools/deps.html)
+
+[Next pageCore tools](https://mise.jdx.dev/core-tools.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)