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 VERSIONMANAGER=none) | | WARNING | Environment warnings | | NEEDS_USER_CHOICE | true when multiple managers detected without preference | | AVAILABLE_MANAGERS | List of detected managers (when NEEDSUSERCHOICE=true) | | NEEDS_VERSION_CONFIRM | true when no version specifier found | | SUGGESTED_VERSION | Latest installed Ruby (when NEEDSVERSION_CONFIRM=true) |

Activation Commands by Manager

| Manager | Activation Command | Notes | |---------|-------------------|-------| | rbenv | eval "$(rbenv init -)" | Or use rbenv exec ruby ... | | chruby | source .../chruby.sh && chruby | 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 ( chruby > rbenv > rvm > asdf > rv > mise > none

No Version Specifier (NEEDSVERSIONCONFIRM=true)

Ask: "No .ruby-version found. Use Ruby [SUGGESTEDVERSION] for this session?" If declined, show options from INSTALLEDRUBIES.

Version Not Installed (VERSION_AVAILABLE=false)

Inform user and offer installation:

> Ruby {PROJECTRUBYVERSION} 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: st0012
• Source: st0012/ruby-skills
• License: MIT

Install and usage instructions live in the source repository linked above.