mise-fy

Files (21)

• README.md
• SKILL.md
• hk.pkl · assets/.config/
• .gitignore · assets/.config/mise/
• check.autofix.yml · assets/.github/workflows/
• check.yml · assets/.github/workflows/
• AGENTS.md · assets/
• README.md · assets/
• mise.toml · assets/
• ci.md · references/
• github.md · references/ci/
• docs.md · references/
• env.md · references/
• hk.md · references/
• hooks.md · references/
• install.md · references/
• mise-fy.md · references/
• reference-setup-and-patterns.md · references/
• node.md · references/runtimes/
• tasks.md · references/
• tools.md · references/

SKILL.md (first lines)

# 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!

## 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, 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 Actions -> [`ci/github.md`](references/ci/github.md)

**mise-fy an existing project** (migrate + audit) -> [`references/mise-fy.md`](references/mise-fy.md)
Step-by-step conversion from custom/asdf/Makefile, plus a full audit checklist. References every other doc.

**Project docs** (README + AGENTS.md onboarding) -> [`references/docs.md`](references/docs.md)
What to put in README.md and AGENTS.md/CLAUDE.md so a human and an agent can install mise, set up, run tasks, and extend the setup. Part of every mise-fy/audit.

**Reference setup** (canonical example layout) -> [`references/reference-setup-and-patterns.md`](references/reference-setup-and-patterns.md)
Annotated example file tree + `mise.toml` to copy from.

### Complementary Skills

**CI/CD** (checks/release/publish workflows, gating, signing, and community hygiene) -> load **cicd-fy** skill, if installed (from same author).
This skill covers running mise *in* CI; the pipeline's shape is cicd-fy's domain.


## Always applies (regardless of task)

These hold no matter which reference you loaded; check them even when fixated on one task.
Unlike the opinionated best practices (scope those to your goal), these are the
safety/correctness floor: apply them even on a one-tool change, not polish you'd defer.

1. **Untrusted config errors out.** A `mise.toml` containing `[env]`, hooks, templates, or
   task logic hard-errors as a *whole file* until `mise trust` (interactive shells prompt to
   trust; non-interactive ones error). Only a bare `min_version` + plain-string
   `[tools]`/`[tasks]` file loads untrusted (since 2026.6.6). `mise run`/`install`/`exec` trust the
   active config on their own (since 2026.8.9); `mise env` and older clients still error, and the
   shell hook skips the file with a warning, so docs keep an explicit `mise trust` (or a `trusted_config_paths` entry).
   An untrusted file's `[settings]` are silently ignored, so security settings such as
   `disable_backends` and `minimum_release_age` stay off until trust.
2. **Some features need `experimental = true`** and may change between releases. If a documented flag errors, check whether it's gated.
3. **Set `min_version`** (root level, not under `[settings]`): the oldest release that supports every feature the config uses, never below the known-vulnerable floor (`2026.10.13`), and never
   above what the author has installed. An old client is then told to update instead of failing on a feature it lacks.
4. **Avoid GitHub rate limits** on tool installs (local *and* CI): set

From sherifabdlnaby/skills, MIT.

More from sherifabdlnaby/skills