/mise-fy

name: mise-fy
description: >
  Use when working with mise (mise-en-place) or planning to update mise.toml.
  If the project uses mise, consult it even for one-line edits to mise.toml/hk.pkl, hooks, or CI tool setup, as it has the practices and security defaults you'd otherwise skip.
  Trigger on the intent even when the user never says "mise" (e.g. "update/pin the node version", "set up pre-commit") as long as the project already uses mise.
  Don't load for routine mise *use* (run/install/trust) that isn't changing config. Optionally use the skill to transform local development into using mise, aka (mise-fy).
license: MIT
argument-hint: "Mise-fy this project | Audit this project | Add x tool via Mise"
metadata:
  author: sherifabdlnaby
  version: "0.9.1"

mise-fy

[//]: # (If you're an agent, focus on # How to use the SKill, and the progressive disclosure rules!)

Introduction to Humans

Best-practices, tips, and gotchas to maximize the use of [mise](https://mise.jdx.dev) (along-side [hk](http://hk.jdx.dev/)) distilled from experience building dev (& CI) setups that ✨just works ✨ for diverse teams at different levels that you and your agents would love to use!

**The skill has two modes to trigger for:** 1. Provide tips & gotchas to agents when working with Mise. (duhh!) 2. **_Mise-fy_** 🪄 an existing project and transform it to a recommended structure.

Read each topic's reference in [./references](references) to learn more about what the skill encodes.

> [!TIP] > The skill is written and optimized to be used by models with coherence level similar to `Opus 4.8` or `GPT 5.5`, especially when mise-fying.

The skill **does not enumerate** all of Mise's features. It relies on Agents world knowledge, and ability to read docs (and it ask agents to!) but **guide the agent to best practices**. I may cover more use-cases later!

Is this a `Mise` skill ? or a good local dev setup skill ?

Kinda both; `Mise` is THE tool to use to have a great UX in your dev setups, so there is a lot of overlap. However, the skill is primarily focused on Mise itself, and only encode tips/gotchas **when Mise is involved.** It'll be a good skill to pair with "local-setup" Skill that is runtime specific (maybe soon!).

So What does the skill encode exactly ?

The skill encodes what needs for dev setup to just work, stay discoverable, and guide you to be set up correctly.

**It just works.** Clone the repo, run `mise trust && mise run setup`, and you're done. Tools install pinned and locked, so your versions match everyone else's and CI's. Setup is idempotent and cached, so re-running it is cheap (and for worktrees too!), and the git hooks install themselves on `mise install`, and will nag you if you didn't (so u trust every one and their agent get all local linters/tests/validations)!

**It's discoverable.** Tasks follow the same names in every repo

---

How to use the Skill

The skill uses progressive disclosure: each area routes to a `references/` file holding the actual rules and best practices. Read the matching one **before** planning or acting, not after. SKILL.md alone is not enough. Plan ahead, and read all references you'll need!

**Versions.** Checked against mise 2026.11.3, hk 2.11.1 and pitchfork 2.33.1 on 2026-11-07.

When to read references

Always read at-least 1 reference from the router below. Depending on your goal you might want to read more than 1 reference. Be eager to load local .md references. Do not load online links/references unless you really need to, default to trust your knowledge. Only load online reference when you need to learn more. Commands and keys in the references are the usual call, not the full surface: `--help` and the current docs win. Experimental features (e.g. `[daemons]`) are thin in your training, so read their linked docs before you use anything a page doesn't show.

Router

**Install mise** (machine setup, not project setup) -> [`references/install.md`](references/install.md) Install via package manager, activate the shell, shims for non-interactive shells, completions.

**Dev tools / runtimes** (install, pin, update, backends, lockfile, lazy/uncommon tools) -> [`references/tools.md`](references/tools.md) Installing a tool or a runtime.

**Runtime integration** (per-runtime: package managers, dep install) -> [`references/runtimes/`](references/runtimes/).

• Node -> [`runtimes/node.md`](references/runtimes/node.md)

**Env & vars** (project env, dotenv, secrets) -> [`references/env.md`](references/env.md) `[env]`, `_.file`/`_.path`/`_.source`, templating, required vars, default fallbacks, redaction, updating PATH, loading .env files, config environments (`MISE_ENV`), shell aliases.

**Tasks** (run scripts, build pipelines, watch) -> [`references/tasks.md`](references/tasks.md) TOML vs file tasks, `depends`/`wait_for`, `sources`/`outputs` caching, running and parallelism, `mise watch` (re-run on change).

**Local dev stack** (databases, caches, app servers and workers in the background; a stack per worktree) -> [`references/dev.md`](references/dev.md) `[daemons]` presets and custom daemons, the port block, ready/health/retry, migrations, the `dev:*` tasks, container images, compose as the exception.

**Hooks** (directory & lifecycle: `enter`/`cd`, `watch_files`, `postinstall`) -> [`references/hooks.md`](references/hooks.md) Keeping `enter`/`cd` hooks offline-safe (plain shell, not `mise run`), trust impact, the shim caveat. For git/pre-commit hooks specifically, see hk below.

**hk Hooks** (pre-commit / git hooks) -> [`references/hk.md`](references/hk.md) `hk.pkl` (Pkl, lives at `.config/hk.pkl`), `check` vs `fix`, builtins, mise integration, install, extending with custom steps, the `.config/` home for linter configs.

**CI** (running mise tasks/tools in CI: shims, caching, pinning, tokens) -> [`references/ci.md`](references/ci.md) General platform-agnostic CI rules; platform specifics under [`references/ci/`](references/ci/):

• GitHub Action