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:

• 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