ruby-version-manager

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  # Saves to ~/.config/ruby-skills/preference.json

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:

1. Re-run detect.sh to verify environment
2. Check VERSION_AVAILABLE - install if false
3. Verify manager installation at VERSION_MANAGER_PATH
4. chruby: Check ~/.rubies or /opt/rubies for installations
5. rvm: Check both ~/.rvm and /usr/local/rvm