/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`