| name | ruby-version-manager |
| description | Use at session start for Ruby projects (Gemfile, .ruby-version, or .tool-versions present). Detect version manager BEFORE running ruby, bundle, gem, rake, rails, rspec, or any Ruby command. |
Ruby Version Manager Skill
Detects and configures Ruby version managers for proper environment setup.
When to Use
Run detect.sh IMMEDIATELY when:
- Starting work in a directory with
Gemfile, .ruby-version, or .tool-versions
- Before your first Ruby command (
ruby, bundle, gem, rake, rails, rspec, etc.)
- When switching between Ruby projects
Do NOT wait for commands to fail or user requests. Proactive detection prevents version mismatch errors.
Always chain activation with commands: ACTIVATION_COMMAND && ruby_command
Usage
Step 1: Run detect.sh
Run detect.sh from this skill's directory (path provided by session-start hook).
Step 2: Parse Output
The script outputs key=value pairs:
VERSION_MANAGER=rbenv
PROJECT_RUBY_VERSION=3.2.0
VERSION_AVAILABLE=true
ACTIVATION_COMMAND=eval "$(rbenv init -)"
Step 3: Execute Ruby Commands
Chain ACTIVATION_COMMAND with your Ruby command:
eval "$(rbenv init -)" && bundle install
eval "$(rbenv init -)" && bundle exec rspec
Run detect.sh once per project session; reuse ACTIVATION_COMMAND for subsequent commands.
Output Variables
| Variable | Description |
|---|
VERSION_MANAGER | Detected: shadowenv, chruby, rbenv, rvm, asdf, rv, mise, or none |
VERSION_MANAGER_PATH | Installation path |
PROJECT_RUBY_VERSION | Version required by project |
PROJECT_VERSION_SOURCE | Source file (.ruby-version, .tool-versions, .mise.toml, Gemfile) |
RUBY_ENGINE | Implementation (ruby, truffleruby, jruby) |
INSTALLED_RUBIES | Comma-separated available versions |
VERSION_AVAILABLE | true/false - whether requested version is installed |
ACTIVATION_COMMAND | Shell command to activate the manager |
SYSTEM_RUBY_VERSION | System Ruby (when VERSION_MANAGER=none) |
WARNING | Environment warnings |
NEEDS_USER_CHOICE | true when multiple managers detected without preference |
AVAILABLE_MANAGERS | List of detected managers (when NEEDS_USER_CHOICE=true) |
NEEDS_VERSION_CONFIRM | true when no version specifier found |
SUGGESTED_VERSION | Latest installed Ruby (when NEEDS_VERSION_CONFIRM=true) |
Activation Commands by Manager
| Manager | Activation Command | Notes |
|---|
| rbenv | eval "$(rbenv init -)" | Or use rbenv exec ruby ... |
| chruby | source .../chruby.sh && chruby <version> | detect.sh provides full command |
| rvm | source "$HOME/.rvm/scripts/rvm" | Or use ~/.rvm/bin/rvm-auto-ruby |
| asdf (v0.16+) | None | asdf exec ruby ... |
| asdf (<v0.16) | source "$HOME/.asdf/asdf.sh" | Then asdf exec ruby ... |
| mise | None | mise x -- ruby ... |
| rv | None | rv ruby run -- ... |
| shadowenv | None | shadowenv exec -- ruby ... |
| none | None | ruby ... (uses PATH) |
Commands Requiring Activation
| Category | Commands |
|---|
| Core | ruby, irb, gem, bundle, bundler |
| Build/Task | rake, rails, thor |
| Testing | rspec, minitest, cucumber |
| Linting | rubocop, standardrb, reek |
| LSP/IDE | ruby-lsp, solargraph, steep |
| Debug | pry, byebug, debug |
| Gem binaries | Any executable from gem install or Gemfile |
Handling Special Cases
Multiple Version Managers (NEEDS_USER_CHOICE=true)
Ask the user which manager to use, then store preference:
/path/to/set-preference.sh chruby
Detection priority: shadowenv > chruby > rbenv > rvm > asdf > rv > mise > none
No Version Specifier (NEEDS_VERSION_CONFIRM=true)
Ask: "No .ruby-version found. Use Ruby [SUGGESTED_VERSION] for this session?"
If declined, show options from INSTALLED_RUBIES.
Version Not Installed (VERSION_AVAILABLE=false)
Inform user and offer installation:
Ruby {PROJECT_RUBY_VERSION} is not installed. Install with:
- rbenv:
rbenv install {VERSION}
- rvm:
rvm install {VERSION}
- asdf:
asdf install ruby {VERSION}
- mise:
mise install ruby@{VERSION}
- chruby:
ruby-install ruby {VERSION}
Always ask before installing. For chruby, check INSTALLED_RUBIES for compatible versions (same major.minor).
Shadowenv Trust Issues
If "untrusted shadowenv program" error appears, user must run shadowenv trust in the project directory.
Version Format Variations
Supported formats: 3.3.0, ruby-3.3.0, truffleruby-21.3.0, 3.3.0-rc1, 3.3 (matches any patch)
CI/Docker Environments
When VERSION_MANAGER=none, use system Ruby directly.
Troubleshooting
If Ruby commands fail after activation:
- Re-run detect.sh to verify environment
- Check
VERSION_AVAILABLE - install if false
- Verify manager installation at
VERSION_MANAGER_PATH
- chruby: Check
~/.rubies or /opt/rubies for installations
- rvm: Check both
~/.rvm and /usr/local/rvm
