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 rspecRun 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.jsonDetection 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
~/.rubiesor/opt/rubiesfor installations - rvm: Check both
~/.rvmand/usr/local/rvm