Ruby version manager detection, authoritative resource map, and test framework reference

version
0.6.0
GitHub stars
125

Install

/plugin install ruby-skills@ruby-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add st0012/ruby-skills.

Contents

Discovered from source

Skills 3

Ruby Knowledge

Authoritative resource map for Ruby development. Use these sources rather than searching broadly.

Never use these sources:

  • ruby-doc.org
  • apidock.com

Official Documentation

Primary source: https://docs.ruby-lang.org/en/

Other Useful Resources

Core & Standard Library

TermMeaning
Default gemShips with Ruby, cannot uninstall
Bundled gemShips with Ruby, can uninstall/replace
Standard libraryPart of Ruby itself, not a gem

To check which gem versions ship with each Ruby release: https://stdgems.org/

VersionDocumentationStandard Library
3.2https://docs.ruby-lang.org/en/3.2/https://docs.ruby-lang.org/en/3.2/standard_library_rdoc.html
3.3https://docs.ruby-lang.org/en/3.3/https://docs.ruby-lang.org/en/3.3/standard_library_rdoc.html
3.4https://docs.ruby-lang.org/en/3.4/https://docs.ruby-lang.org/en/3.4/standard_library_md.html
4.0https://docs.ruby-lang.org/en/4.0/https://docs.ruby-lang.org/en/4.0/standard_library_md.html
masterhttps://docs.ruby-lang.org/en/master/https://docs.ruby-lang.org/en/master/standard_library_md.html

Testing Frameworks

FrameworkGitHubDocumentation
minitesthttps://github.com/minitest/minitesthttps://docs.seattlerb.org/minitest/
test-unithttps://github.com/test-unit/test-unithttps://test-unit.github.io/

Typing Ecosystem

Two type definition formats exist in Ruby:

  • RBI - Sorbet's format. Uses Ruby DSL syntax (sig { ... }) in .rb and .rbi files.
  • RBS - Official Ruby format (Ruby 3.0+). Dedicated syntax in .rbs files or inline as comments.

Sorbet Ecosystem

Sorbet is a static and runtime type checker for Ruby, maintained by Stripe. Key companion tools:

  • Tapioca - Generates RBI files for gems and DSLs (Rails, ActiveRecord, etc.)
  • Spoom - Coverage analysis, strictness bumping, dead code detection, signature migration

RBS Ecosystem

  • rbs - Official CLI for working with RBS files (prototype, list, methods)
  • Steep - Type checker that uses RBS

RBS Inline Comments

Sorbet supports RBS-style inline type annotations using #: comment syntax. This eliminates the need for separate .rbi files or verbose sig blocks.

Docs: https://sorbet.org/docs/rbs-comments

Minitest vs Test-Unit Divergences

Only covers where minitest and test-unit diverge. If something isn't listed here, it works the same in both.

Assertion Naming Mismatches

Using the wrong name causes NoMethodError.

Conceptminitesttest-unit
Exceptionassert_raises (plural)assert_raise (singular)
Throwassert_throws (plural)assert_throw (singular)
Collection inclusionassert_includes (plural)assert_include (singular)
Path existsassert_path_exists (with s)assert_path_exist (no s)
Negation patternrefute_* (e.g. refute_nil)assert_not_* (e.g. assert_not_nil)

test-unit aliases minitest names (assert_raises, refute_*, etc.), so minitest syntax works in test-unit but not vice versa.

Assertions That Only Exist in One Framework

test-unit only

MethodPurpose
assert_nothing_raisedPasses if block doesn't raise (also added by Rails on top of minitest)
assert_true / assert_falseChecks for exactly true or false (not just truthy/falsy)
assert_booleanChecks value is true or false
assert_compareFor <, <=, >, >= comparisons
assert_raise_with_messageChecks both exception class and message
assert_raise_messageChecks exception message only (any class)
assert_raise_kind_ofChecks exception via kind_of? instead of exact class
assert_const_defined / assert_not_const_definedCheck constant existence
assert_alias_methodVerify method aliasing
assert_nothing_thrownPasses if block doesn't call throw
assert_blockPasses if block returns truthy

minitest only

MethodPurpose
assert_pattern / refute_patternRuby 3+ pattern matching (in expressions)
assert_silentPasses if block produces no stdout/stderr
assert_outputCheck stdout/stderr content
capture_io / capture_subprocess_ioCapture output for inspection
skip_until(y, m, d, msg)Skip until a date, then fail as reminder
fail_after(y, m, d, msg)Pass until a date, then fail as reminder

minitest 6 breaking change

assert_equal(nil, value) is a hard failure in minitest 6. Use assert_nil(value) instead. test-unit has no such restriction.

Test Selection (CLI Flags)

Operationminitesttest-unit
By name (exact)-n test_method_name--name test_method_name
By name (regex)-n /pattern/--name "/pattern/"
By name (rake)N=/pattern/ rake testN/A
By line numberm test/file.rb:42 or minitest test/file.rb:42 (v6)--location path.rb:LINE
By line (Rails)bin/rails test test/file.rb:42N/A
Exclude by name-e /pattern/--ignore-name /pattern/
Exclude by classN/A--ignore-testcase /pattern/
Filter by classN/A (use -n /ClassName#/)--testcase ClassName
Filter by attributeN/A--attribute "speed == :slow"
Seed-s SEED or --seed SEEDN/A (use --order random)
Stop on failureN/A--stop-on-failure
Execution orderRandom by default--order alphabetic / random / defined
Color-p (pride)--color-scheme SCHEME

minitest 6 renamed -n to -i (--include). -n still works as an alias but is planned for removal.

Rails-specific flags (minitest underneath)

bin/rails test adds: -b (full backtrace), -f (fail-fast), -d (defer output), --profile [N] (slowest tests).

Lifecycle Differences

minitest

before_setup    (for frameworks like Rails)
  setup         (for test authors)
    after_setup
      [TEST]
    before_teardown
  teardown
after_teardown

No class-level hooks. No cleanup. For before(:all) / after(:all), use the minitest-hooks gem.

test-unit

startup           (class method, once before all tests)
  setup           (instance, before each test)
    [TEST]
  cleanup         (instance, only if test didn't raise)
  teardown        (instance, always runs, even if cleanup raised)
shutdown          (class method, once after all tests)

startup/shutdown have no minitest equivalent. cleanup runs after a passing test but before it's marked as passed — use it for verification like mock expectations. teardown always runs regardless of outcome — use it for resource release.

test-unit also supports registering multiple setup/teardown methods by symbol:

setup :prepare_database, :prepare_cache

Skip / Pending / Omit

Conceptminitesttest-unit
Skip a testskip("reason")omit("reason") or pend("reason")
Conditional skipskip("reason") if conditionomit("reason") if condition or omit_if(condition, "reason") / omit_unless(condition, "reason")
Output characterSO (omit) or P (pend)

Critical difference: test-unit's pend with a block fails if the block passes. This catches code that was fixed but still marked pending. minitest's skip is always unconditional.

# test-unit: this FAILS if the bug gets fixed
pend("Bug #123") do
  assert_equal(42, buggy_method)  # if this passes, test fails
end

# minitest: no equivalent behavior
skip("Bug #123")  # always skips, no block form

Output Format

Aspectminitesttest-unit
Progress.FES.FEOPN (adds Omit, Pending, Notification)
SummaryN runs, N assertions, N failures, N errors, N skipsN tests, N assertions, N failures, N errors, N pendings, N omissions, N notifications
Throughputruns/s, assertions/stests/s, assertions/s

test-unit Exclusive Features

These have no minitest equivalent:

  • Data-driven tests: data("label", value) method generates parameterized test runs
  • Priority system: priority :must / :important / :high / :normal / :low / :never with probabilistic execution
  • Attributes: Generic metadata on test methods, filterable via --attribute
  • sub_test_case: Named nested test groups (minitest uses describe blocks in Spec mode)
  • notify: Non-fatal informational messages shown as N in output
  • Test runners: Console, Emacs, XML (minitest only has console with plugin system)
  • Config file: ~/.test-unit.yml for persistent settings

Rails Context

Rails uses minitest, not test-unit. But Rails adds aliases and methods that blur the line:

Aliases Rails defines on top of minitest:

Rails aliasDelegates toEffect
assert_not_* (12 methods)refute_*assert_not_nil, assert_not_equal, etc. all work in Rails
assert_notrefuteBase negation
assert_raise (singular)assert_raisesBoth singular and plural work in Rails
assert_no_matchrefute_match

Methods Rails adds (not in either framework):

MethodPurpose
assert_nothing_raisedPasses if block doesn't raise
assert_difference / assert_no_differenceCheck numeric change after block
assert_changes / assert_no_changesCheck value change after block

This means in Rails: assert_not_nil, assert_raise, and assert_nothing_raised all work — but they will not work if you move the test to plain minitest outside Rails.

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

VariableDescription
VERSION_MANAGERDetected: shadowenv, chruby, rbenv, rvm, asdf, rv, mise, or none
VERSION_MANAGER_PATHInstallation path
PROJECT_RUBY_VERSIONVersion required by project
PROJECT_VERSION_SOURCESource file (.ruby-version, .tool-versions, .mise.toml, Gemfile)
RUBY_ENGINEImplementation (ruby, truffleruby, jruby)
INSTALLED_RUBIESComma-separated available versions
VERSION_AVAILABLEtrue/false - whether requested version is installed
ACTIVATION_COMMANDShell command to activate the manager
SYSTEM_RUBY_VERSIONSystem Ruby (when VERSION_MANAGER=none)
WARNINGEnvironment warnings
NEEDS_USER_CHOICEtrue when multiple managers detected without preference
AVAILABLE_MANAGERSList of detected managers (when NEEDS_USER_CHOICE=true)
NEEDS_VERSION_CONFIRMtrue when no version specifier found
SUGGESTED_VERSIONLatest installed Ruby (when NEEDS_VERSION_CONFIRM=true)

Activation Commands by Manager

ManagerActivation CommandNotes
rbenveval "$(rbenv init -)"Or use rbenv exec ruby ...
chrubysource .../chruby.sh && chruby <version>detect.sh provides full command
rvmsource "$HOME/.rvm/scripts/rvm"Or use ~/.rvm/bin/rvm-auto-ruby
asdf (v0.16+)Noneasdf exec ruby ...
asdf (<v0.16)source "$HOME/.asdf/asdf.sh"Then asdf exec ruby ...
miseNonemise x -- ruby ...
rvNonerv ruby run -- ...
shadowenvNoneshadowenv exec -- ruby ...
noneNoneruby ... (uses PATH)

Commands Requiring Activation

CategoryCommands
Coreruby, irb, gem, bundle, bundler
Build/Taskrake, rails, thor
Testingrspec, minitest, cucumber
Lintingrubocop, standardrb, reek
LSP/IDEruby-lsp, solargraph, steep
Debugpry, byebug, debug
Gem binariesAny 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

Sponsors

Details

Marketplace
st0012/ruby-skills
Source
plugins/ruby-skills
Category
Community