| name | mise-expert |
| description | Manage tool versions (node, python, go), create task runners, and setup development environments using mise. Use when user requests "install node", "setup mise", "create task", or mentions mise.toml, version manager, tool management, task runner. |
Mise Expert Skill
Purpose
Specialized skill for mise - a unified development environment manager combining tool version management (asdf replacement), environment variable management (direnv replacement), and task running (make/npm scripts replacement).
When to Use This Skill
Tool & Runtime Management
- Installing and managing runtime versions (node, python, go, ruby, rust, etc.)
- Setting up project-specific tool versions for reproducibility
- Switching between multiple language versions in polyglot projects
- Managing global vs project-local tool installations
- Migrating from asdf, nvm, pyenv, rbenv, or similar version managers
- Troubleshooting tool version conflicts
Project Setup & Onboarding
- Bootstrapping new project development environments
- Creating mise.toml for team consistency
- Setting up monorepo tool configurations
- Configuring per-directory environment switching
- Establishing project development standards
- Simplifying onboarding for new team members
Task Runner & Build Systems
- Creating or optimizing mise.toml task configurations
- Designing task workflows with dependency chains
- Implementing parallel task execution strategies
- Adding intelligent caching with sources/outputs
- Converting from make, npm scripts, just, or other task runners
- Building cross-platform compatible task systems
- Optimizing build performance with incremental builds
Environment Management
- Configuring per-directory environment variables
- Managing secrets and configuration across environments
- Setting up development/staging/production environment switching
- Replacing direnv with mise
- Loading environment from .env files
- Creating environment-specific task behaviors
CI/CD Integration
- Setting up mise in GitHub Actions, GitLab CI, CircleCI
- Ensuring consistent environments between local and CI
- Optimizing CI builds with mise caching
- Managing tool versions in containerized environments
Troubleshooting & Optimization
- Debugging mise task execution issues
- Diagnosing tool version problems
- Resolving environment variable loading issues
- Optimizing task caching and performance
- Fixing cross-platform compatibility issues
Core Capabilities
Operational Guidelines
Task Configuration Principles
Decision Framework
Skip mise for:
- Single-language projects with simple build steps
- Projects where npm scripts are sufficient
- Teams unfamiliar with TOML and no bandwidth for learning
- Projects with existing, working task systems and no pain points
- Embedded systems or constrained environments
Tool Version Management Patterns
Read from version file
ruby = { file = ".ruby-version" } java = { file = ".java-version" }
Latest patch version
postgres = "16" redis = "7"
Multiple versions (switch with mise use)
mise use node@18 (temporarily override)
**Global Development Tools**
```bash
# Install globally useful CLI tools
mise use -g ripgrep@latest # Better grep
mise use -g bat@latest # Better cat
Version File Migration
# Migrate from existing version files
echo "20.10.0" > .node-version
echo "3.11.6" > .python-version
# mise.toml
[tools]
node = { file = ".node-version" }
python = { file = ".python-version" }
Project Setup Workflows
[env] PROJECT_ROOT = "{{cwd}}" LOG_LEVEL = "debug"
[vars] project_name = "my-app"
[tasks.setup] description = "Setup development environment" run = [ "mise install", "npm install", "pip install -r requirements.txt", "cp .env.example .env" ]
[tasks.dev] alias = "d" description = "Start development server" depends = ["setup"] env = { NODE_ENV = "development" } run = "npm run dev"
**Monorepo Configuration**
```toml
# Root mise.toml
[tools]
node = "20"
go = "1.21"
[tasks.install]
description = "Install all dependencies"
run = [
"cd frontend && npm install",
"cd backend && go mod download"
]
# frontend/mise.toml
[tasks.dev]
dir = "{{cwd}}/frontend"
run = "npm run dev"
# backend/mise.toml
[tools]
go = "1.21"
[tasks.dev]
dir = "{{cwd}}/backend"
run = "go run main.go"
Configuration Patterns
[tasks.dev-watch] description = "Watch and rebuild on changes" run = "mise watch build"
**Build Pipeline with Caching**
```toml
[tasks.clean]
description = "Remove build artifacts"
run = "rm -rf dist"
[tasks.build]
alias = "b"
description = "Build production bundle"
depends = ["clean"]
sources = ["src/**/*", "package.json", "tsconfig.json"]
outputs = ["dist/**/*"]
env = { NODE_ENV = "production" }
run = "npm run build"
[tasks.build-watch]
description = "Rebuild on source changes"
run = "mise watch build"
Testing Suite
[tasks.test]
alias = "t"
description = "Run all tests"
depends = ["test:unit", "test:integration"] # Runs in parallel
[tasks."test:unit"]
description = "Run unit tests"
sources = ["src/**/*.ts", "tests/unit/**/*.ts"]
run = "npm test -- --testPathPattern=unit"
[tasks."test:integration"]
description = "Run integration tests"
sources = ["src/**/*.ts", "tests/integration/**/*.ts"]
run = "npm test -- --testPathPattern=integration"
[tasks."test:watch"]
description = "Run tests in watch mode"
run = "npm test -- --watch"
[tasks."test:coverage"]
description = "Generate coverage report"
run = "npm test -- --coverage"
[tasks."test:e2e"]
description = "Run end-to-end tests"
depends = ["build"]
run = "playwright test"
Database Workflow
[tasks."db:migrate"]
description = "Run database migrations"
run = "npx prisma migrate deploy"
[tasks."db:seed"]
description = "Seed database with test data"
depends = ["db:migrate"]
run = "npx prisma db seed"
[tasks."db:reset"]
description = "Reset database to clean state"
run = ["npx prisma migrate reset --force", "mise run db:seed"]
[tasks."db:studio"]
description = "Open Prisma Studio"
run = "npx prisma studio"
Linting & Formatting
[tasks.lint]
description = "Lint code"
sources = ["src/**/*.ts"]
run = "eslint src"
[tasks.format]
description = "Format code"
sources = ["src/**/*.ts"]
run = "prettier --write src"
[tasks."lint:fix"]
description = "Lint and auto-fix issues"
run = "eslint src --fix"
[tasks.check]
description = "Run all checks"
depends = ["lint", "format", "test"] # Runs in parallel
Deployment Pipeline
[tasks.deploy]
description = "Deploy to production"
usage = '''
arg "environment" description="Target environment" default="staging"
flag "-f --force" description="Skip confirmation"
'''
depends = ["build", "test"]
depends_post = ["notify:slack"]
run = './scripts/deploy.sh {{arg(name="environment")}} {{flag(name="force")}}'
[tasks."deploy:staging"]
description = "Deploy to staging"
depends = ["build", "test"]
run = "./scripts/deploy.sh staging"
[tasks."deploy:production"]
description = "Deploy to production"
depends = ["build", "test"]
run = "./scripts/deploy.sh production"
[tasks."notify:slack"]
hide = true
run = 'curl -X POST $SLACK_WEBHOOK -d "Deployment complete"'
Docker Integration
[tasks."docker:build"]
description = "Build Docker image"
sources = ["Dockerfile", "src/**/*"]
run = "docker build -t myapp:latest ."
[tasks."docker:run"]
description = "Run Docker container"
depends = ["docker:build"]
run = "docker run -p 3000:3000 myapp:latest"
[tasks."docker:compose"]
description = "Start services with docker-compose"
run = "docker-compose up -d"
Go Plugin Build System
[tasks."build:plugins"]
description = "Build all Go plugins in parallel"
sources = ["plugins/**/*.go"]
outputs = ["plugins/**/main.so"]
run = '''
for plugin in plugins/*/; do
(cd "$plugin" && go build -buildmode=plugin -o main.so main.go) &
done
wait
'''
[tasks."rebuild:plugins"]
description = "Rebuild plugins when engine changes"
sources = ["engine/**/*.go"]
depends = ["build:engine"]
run = "mise run build:plugins"
Variables and Environment Management
Load additional vars from .env
_.file = ".env"
[env]
Static environment variables
NODE_ENV = "development" LOG_LEVEL = "debug"
Reference variables
API_URL = "{{vars.api_url}}" DATABASE_URL = "postgres://{{vars.db_host}}:{{vars.db_port}}/myapp" DEBUG = "{{vars.debug_mode}}"
[tasks.dev] env = { NODE_ENV = "development", API_URL = "{{vars.api_url}}" } run = "npm run dev"
**Multi-Environment Setup**
```toml
# mise.toml (base development config)
[vars]
environment = "development"
api_url = "http://localhost:3000"
[env]
NODE_ENV = "development"
# mise.staging.toml
[vars]
environment = "staging"
api_url = "https://api.staging.example.com"
[env]
NODE_ENV = "staging"
# mise.production.toml
[vars]
environment = "production"
api_url = "https://api.example.com"
debug_mode = "false"
[env]
NODE_ENV = "production"
Secret Management
# mise.toml (checked into git)
[vars]
# Non-sensitive defaults
api_url = "http://localhost:3000"
# Load secrets from .env (gitignored)
_.file = ".env"
[env]
# Reference secrets loaded from .env
API_KEY = "{{vars.api_key}}"
DATABASE_PASSWORD = "{{vars.db_password}}"
# .env (NOT in git)
api_key=secret-key-here
db_password=secret-password
Workflow Process
Assess Current State
- Read existing mise.toml if present
- Identify current task runner (make, npm, etc.)
- Check for version managers (asdf, nvm, pyenv)
- Understand project structure and requirements
Design Architecture
- Determine tool version requirements
- Map out task dependencies and relationships
- Identify parallel execution opportunities
- Plan caching strategy with sources/outputs
- Consider cross-platform needs
Implement Configuration
- Start with tool versions and environment setup
- Create simple tasks, add complexity incrementally
- Use namespacing for related tasks
- Add aliases for frequently used tasks
- Document complex tasks with descriptions
Optimize Performance
- Add sources/outputs for caching
- Leverage parallel execution via depends
- Set appropriate
jobslimit - Use watch mode for development workflows
Validate and Test
- Run
mise installto verify tool installation - Run
mise tasks lsto verify task registration - Test task execution:
mise run <task> - Verify caching behavior
- Test cross-platform if applicable
- Run
mise doctorfor diagnostics
- Run
Migration Strategies
.tool-versions:
nodejs 20.10.0
python 3.11.6
golang 1.21.5
terraform 1.6.6
mise.toml:
[tools]
node = "20.10.0"
python = "3.11.6"
go = "1.21.5"
terraform = "1.6.6"
Migration command:
# Mise can read .tool-versions directly
mise install
# Or convert to mise.toml
mise use node@20.10.0 python@3.11.6 go@1.21.5 terraform@1.6.6
Makefile:
.PHONY: build test clean deploy
clean:
rm -rf dist
build: clean
npm run build
test: build
npm test
deploy: build test
./deploy.sh
mise.toml:
[tasks.clean]
description = "Remove build artifacts"
run = "rm -rf dist"
[tasks.build]
alias = "b"
description = "Build production bundle"
depends = ["clean"]
sources = ["src/**/*", "package.json"]
outputs = ["dist/**/*"]
run = "npm run build"
[tasks.test]
alias = "t"
description = "Run tests"
depends = ["build"]
run = "npm test"
[tasks.deploy]
description = "Deploy to production"
depends = ["build", "test"] # build and test run in parallel
run = "./deploy.sh"
Advantages:
- Automatic caching via sources/outputs
- Parallel execution of independent tasks
- Cross-platform compatibility
- Environment variable management
- Tool version management integrated
package.json:
{
"scripts": {
"dev": "NODE_ENV=development npm start",
"build": "webpack --mode production",
"test": "jest",
"lint": "eslint src",
"deploy": "npm run build && npm run test && ./deploy.sh"
}
}
mise.toml:
[tasks.dev]
alias = "d"
description = "Start development server"
env = { NODE_ENV = "development" }
run = "npm start"
[tasks.build]
alias = "b"
description = "Build production bundle"
sources = ["src/**/*", "webpack.config.js"]
outputs = ["dist/**/*"]
run = "webpack --mode production"
[tasks.test]
alias = "t"
description = "Run tests"
run = "jest"
[tasks.lint]
description = "Lint code"
sources = ["src/**/*.js"]
run = "eslint src"
[tasks.deploy]
description = "Deploy to production"
depends = ["build", "test"] # Runs in parallel
run = "./deploy.sh"
Advantages:
- Better dependency management (build + test run in parallel)
- Caching prevents unnecessary rebuilds
- Environment variables in configuration
- Consistent interface across different project types
- Works with any language, not just Node.js
.envrc:
export NODE_ENV=development
export API_URL=http://localhost:3000
export DATABASE_URL=postgres://localhost/myapp
mise.toml:
[env]
NODE_ENV = "development"
API_URL = "http://localhost:3000"
DATABASE_URL = "postgres://localhost/myapp"
# Or use variables for DRY
[vars]
api_host = "localhost"
api_port = "3000"
[env]
API_URL = "http://{{vars.api_host}}:{{vars.api_port}}"
Advantages:
- TOML format easier to read/edit than bash
- Variables for DRY configuration
- Integrates with task runner and tool versions
- No shell-specific syntax
CI/CD Integration
jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
- name: Setup mise
uses: jdx/mise-action@v2
with:
version: latest # or specific version
- name: Install tools and dependencies
run: mise install
- name: Run tests
run: mise run test
- name: Build
run: mise run build
**GitLab CI**
```yaml
image: ubuntu:latest
before_script:
- curl https://mise.run | sh
- export PATH="$HOME/.local/bin:$PATH"
- mise install
test:
script:
- mise run test
build:
script:
- mise run build
Docker
FROM ubuntu:latest
# Install mise
RUN curl https://mise.run | sh
ENV PATH="/root/.local/bin:$PATH"
# Copy project files
COPY . /app
WORKDIR /app
# Install tools and dependencies
RUN mise install
# Run build
RUN mise run build
CMD ["mise", "run", "start"]
Troubleshooting Guide
Task Not Found
# Symptom: "Task 'xyz' not found"
mise tasks ls # List all tasks
mise config # Show active config files
cat mise.toml # Verify task definition
mise tasks info <task> # Get task details
Task Caching Issues
# Symptom: Task not re-running when files change
[tasks.build]
sources = ["src/**/*"] # Check glob patterns are correct
outputs = ["dist/**/*"] # Verify output paths match actual outputs
run = "npm run build"
# Debug: Remove outputs and re-run
# rm -rf dist && mise run build
Environment Variables Not Loading
# Symptom: Environment variables not set in tasks
mise config # Verify mise.toml location (project root)
mise run --verbose <task> # Check env loading with verbose output
mise doctor # Diagnostic check
env | grep VAR_NAME # Check if var is actually set
Cross-Platform Issues
# Symptom: Task fails on Windows
[tasks.build]
run = "npm run build" # Use cross-platform commands
run_windows = "npm.cmd run build" # Windows-specific override
# Or use mise variables for paths
run = "{{cwd}}/scripts/build.sh"
Parallel Execution Not Working
# Symptom: Tasks running sequentially instead of parallel
[tasks.ci]
depends = ["lint", "test", "build"] # Runs in parallel by default
# For sequential execution, use run array
[tasks.sequential]
run = [
"mise run step1",
"mise run step2",
"mise run step3"
]
Tool Installation Fails
# Symptom: mise install fails for a tool
mise doctor # Check for system dependencies
mise ls-remote node # List available versions
mise install node@20 --verbose # Verbose installation
mise cache clear # Clear cache and retry
Best Practices Checklist
Task Configuration:
- All frequently used tasks have short aliases
- Build tasks define sources and outputs for caching
- Related tasks use namespace prefixes (db:, test:, docker:)
- Complex tasks have clear descriptions
- Tasks with arguments use usage spec for documentation
- Hidden internal tasks marked with hide = true
Environment Management:
- Environment variables use mise variables for DRY
- Secrets loaded from .env (gitignored)
- Development defaults in mise.toml (version controlled)
- Production overrides in separate config files
Performance:
- Parallel execution leveraged via depends arrays
- Caching configured with sources/outputs
- Watch mode available for iterative development
- jobs setting optimized for system resources
Cross-Platform:
- Platform-specific commands use run_windows
- Paths use {{cwd}} instead of hardcoded values
- Tested on target platforms (Linux/Mac/Windows)
Team & CI:
- mise.toml version controlled
- README documents mise installation and usage
- CI/CD uses mise for consistent environments
- Validated with
mise doctor
Output Standards
When creating mise configurations:
- Always provide complete mise.toml sections, not fragments
- Include comments explaining non-obvious configurations
- Add descriptions to all user-facing tasks
- Show usage examples with
mise runcommands - Explain caching strategy when using sources/outputs
- Document environment variables and their purposes
- Provide migration path if converting from other systems
- Include validation steps to verify configuration works
- Show tool installation with
mise installwhen setting up tools - Demonstrate testing with actual command examples
Example Interactions
Response:
# mise.toml
[tools]
node = "20.10.0"
[env]
NODE_ENV = "development"
[tasks.install]
description = "Install dependencies"
run = "npm install"
[tasks.dev]
alias = "d"
description = "Start development server"
env = { NODE_ENV = "development" }
run = "npm run dev"
[tasks.build]
alias = "b"
description = "Build for production"
sources = ["src/**/*", "package.json"]
outputs = ["dist/**/*"]
env = { NODE_ENV = "production" }
run = "npm run build"
[tasks.test]
alias = "t"
description = "Run tests"
run = "npm test"
Setup:
mise install # Install Node.js 20.10.0
mise run install # Install npm dependencies
mise dev # Start development server
Response:
# mise.toml
[tools]
node = "20.10.0"
python = "3.11.6"
[env]
PROJECT_ROOT = "{{cwd}}"
[tasks."backend:install"]
description = "Install Python dependencies"
dir = "{{cwd}}/backend"
run = "pip install -r requirements.txt"
[tasks."frontend:install"]
description = "Install Node dependencies"
dir = "{{cwd}}/frontend"
run = "npm install"
[tasks.install]
description = "Install all dependencies"
depends = ["backend:install", "frontend:install"]
[tasks."backend:dev"]
description = "Start Python backend"
dir = "{{cwd}}/backend"
env = { FLASK_ENV = "development" }
run = "python app.py"
[tasks."frontend:dev"]
description = "Start Node frontend"
dir = "{{cwd}}/frontend"
env = { NODE_ENV = "development" }
run = "npm run dev"
[tasks.dev]
description = "Start both frontend and backend"
depends = ["backend:dev", "frontend:dev"]
Usage:
mise install # Install both Node and Python
mise run install # Install all dependencies
mise dev # Start both services in parallel
Anti-Patterns to Avoid
Do:
- ✅ Pin exact tool versions for reproducibility
- ✅ Use namespacing for related tasks
- ✅ Add aliases for frequently used tasks
- ✅ Define sources/outputs for cacheable tasks
- ✅ Leverage parallel execution with depends
- ✅ Use variables for DRY configuration
- ✅ Document complex task arguments with usage spec
- ✅ Test with
mise doctorbefore committing - ✅ Provide clear descriptions for team members
- ✅ Load secrets from gitignored .env files