Agent skill
managing-mise
Manage mise runtime: Node.js, pnpm, shims. Trigger: 'mise 설정', 'pnpm not found', '.nvmrc', 'mise shims', 'mise activate', '런타임 버전 불일치'.
Install this agent skill to your Project
npx add-skill https://github.com/greenheadHQ/nixos-config/tree/main/.claude/skills/managing-mise
SKILL.md
mise 런타임 버전 관리
mise를 사용한 Node.js, pnpm 등 런타임 버전 관리 가이드.
목적과 범위
런타임 버전 선택, shims 경로, SSH 비대화형 셸 이슈를 안정적으로 운영하는 절차를 다룬다.
macOS에서는 Homebrew로 mise를 설치하고, NixOS에서는 pkgs.mise를 사용한다.
빠른 참조
플랫폼별 설치 구조
| 항목 | macOS | NixOS |
|---|---|---|
| mise 설치 | Homebrew | libraries/packages.nix (nixosOnly) |
| 소스 빌드 | 기본값 사용 | MISE_ALL_COMPILE=0 환경변수로 비활성화 |
| Node 빌드 | 기본값 사용 | MISE_NODE_COMPILE=0 환경변수로 비활성화 |
| 환경변수 위치 | - | modules/shared/programs/shell/nixos.nix |
mise 설정 위치
| 파일 | 용도 |
|---|---|
~/.config/mise/config.toml |
전역 설정 |
mise.toml / .mise.toml |
프로젝트별 설정 |
mise.local.toml |
프로젝트 로컬 (gitignore됨) |
.nvmrc, .node-version |
Node.js 버전 (idiomatic files) |
주요 명령어
# 현재 버전 확인
mise current
# 전역 버전 설정
mise use -g node@lts
# 프로젝트 버전 설치
mise install node@20.18
# 프로젝트 설정 신뢰
mise trust
관련 설정 파일
| 파일 | 용도 |
|---|---|
modules/shared/programs/shell/default.nix |
zsh mise 활성화 (shims + activate) |
modules/shared/programs/shell/nixos.nix |
NixOS 환경변수 (MISE_ALL_COMPILE=0, MISE_NODE_COMPILE=0) |
libraries/packages.nix |
pkgs.mise 패키지 설치 (nixosOnly) |
셸 활성화 구조
mise는 두 계층으로 활성화된다:
| 계층 | 파일 | 명령어 | 용도 |
|---|---|---|---|
.zshenv |
shell/default.nix envExtra |
mise activate zsh --shims |
비대화형 SSH 세션 (PATH에 shim만 추가) |
.zshrc |
shell/default.nix initContent |
mise activate zsh |
대화형 셸 (cd 시 자동 버전 전환 등 전체 훅) |
MISE_SHELL 환경변수로 중복 활성화를 방지한다.
핵심 절차
mise current로 현재 선택된 런타임을 확인한다.- 전역 버전이 필요하면
mise use -g node@lts로 고정한다. - 프로젝트별 버전은
mise.toml또는.nvmrc기준으로mise install을 실행한다. .nvmrc인식이 필요하면mise settings add idiomatic_version_file_enable_tools node를 실행한다.- 비대화형 셸 문제는
~/.zshenv의 shims 경로와mise activate적용 여부를 점검한다.
자주 발생하는 문제
- SSH 비대화형 세션에서 pnpm not found:
.zshenv에 mise shims 누락 → 셸 활성화 구조 참조 - .nvmrc 인식 안 됨: mise 2025.10.0부터 기본 비활성화 →
idiomatic_version_file_enable_tools설정 필요 - NixOS에서 node 빌드 실패:
MISE_NODE_COMPILE=0필요 (현재nixos.nix에서 영구 설정됨) - mise.local.toml 미신뢰:
mise trust실행 필요 (최초 1회)
레퍼런스
- 트러블슈팅: references/troubleshooting.md
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
greenheadHQ/nixos-config
configuring-git
Configure Git via Home Manager: delta, lazygit, rerere. Trigger: 'git 설정 충돌', 'delta 설정', 'lazygit', 'rerere', 'git-cleanup', 'git 브랜치 정리'.
greenheadHQ/nixos-config
managing-tmux
Configure tmux: plugins (resurrect, thumbs, yank), Pane Notepad. Trigger: 'tmux 설정', 'tmux 플러그인', 'pane notepad', 'tmux-resurrect', 'tmux 단축키', 'tmux 세션 복원'. NOT for SSH (use managing-ssh). NOT for Atuin (use syncing-atuin).
greenheadHQ/nixos-config
configuring-neovim
Configure Neovim (LazyVim) via Nix: plugins, LSP, formatters, linters, themes, treesitter, im-select. Default editor skill — generic '에디터', '편집기', '코드 편집기' queries route here unless the request is explicitly about Zed or another editor-specific path. Trigger: 'neovim', 'LSP', 'lazy.nvim', 'treesitter', '한영 전환', 'im-select', '에디터', '코드 편집기', '편집기 설정', 'colorscheme', 'catppuccin', 'formatter', 'linter', 'extraPackages', '자동완성', 'syntax highlighting', 'language server', '코드 편집'. NOT for Zed/확장 (→ modules/darwin/programs/zed/). NOT for VSCode (제거됨, #329).
greenheadHQ/nixos-config
managing-secrets
Manage encrypted secrets with agenix: .age files, re-encryption, decryption failures. Trigger: '시크릿', '암호화', '복호화', 'agenix', 'secrets.nix', 'age key', '.age', '토큰 추가', 're-encrypt', '/run/agenix'. NOT for Vaultwarden 비밀번호 관리자 (use hosting-vaultwarden).
greenheadHQ/nixos-config
managing-ssh
Configure SSH, Tailscale VPN, mosh, sudo auth. Trigger: 'SSH 인증 실패', 'Tailscale', 'ssh-agent 문제', 'MagicDNS', 'mosh', 'authorized_keys 설정'. NOT for tmux (use managing-tmux). NOT for Atuin (use syncing-atuin).
greenheadHQ/nixos-config
managing-macos
Configure macOS/nix-darwin: Dock, Finder, Homebrew Cask, Folder Actions. Trigger: 'darwin-rebuild', 'shottr 설정', 'Folder Actions', 'compress-video', 'upload-immich'.
Didn't find tool you were looking for?