# Ruby Version Manager

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-st0012-ruby-skills-ruby-version-manager`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [st0012](https://agentstack.voostack.com/s/st0012)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [st0012](https://github.com/st0012)
- **Source:** https://github.com/st0012/ruby-skills/tree/master/plugins/ruby-skills/skills/ruby-version-manager

## Install

```sh
agentstack add skill-st0012-ruby-skills-ruby-version-manager
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```text
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:

```bash
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 ` | 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 (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`

## Source & license

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

- **Author:** [st0012](https://github.com/st0012)
- **Source:** [st0012/ruby-skills](https://github.com/st0012/ruby-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-st0012-ruby-skills-ruby-version-manager
- Seller: https://agentstack.voostack.com/s/st0012
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.