madbomber/ruby-version-manager

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