
ruby-skills
Ruby version manager detection, authoritative resource map, and test framework reference
- version
- 0.6.0
- GitHub stars
- 125
Install
/plugin install ruby-skills@ruby-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add st0012/ruby-skills.
Contents
Discovered from sourceSkills 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
- https://rubyreferences.github.io/rubychanges/ - Version-by-version changelog with examples
- https://railsatscale.com/ - Shopify engineering blog (Latest updates on Ruby and its toolings)
Core & Standard Library
| Term | Meaning |
|---|---|
| Default gem | Ships with Ruby, cannot uninstall |
| Bundled gem | Ships with Ruby, can uninstall/replace |
| Standard library | Part of Ruby itself, not a gem |
To check which gem versions ship with each Ruby release: https://stdgems.org/
Testing Frameworks
| Framework | GitHub | Documentation |
|---|---|---|
| minitest | https://github.com/minitest/minitest | https://docs.seattlerb.org/minitest/ |
| test-unit | https://github.com/test-unit/test-unit | https://test-unit.github.io/ |
Typing Ecosystem
Two type definition formats exist in Ruby:
- RBI - Sorbet's format. Uses Ruby DSL syntax (
sig { ... }) in.rband.rbifiles. - RBS - Official Ruby format (Ruby 3.0+). Dedicated syntax in
.rbsfiles 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.
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.
| Concept | minitest | test-unit |
|---|---|---|
| Exception | assert_raises (plural) | assert_raise (singular) |
| Throw | assert_throws (plural) | assert_throw (singular) |
| Collection inclusion | assert_includes (plural) | assert_include (singular) |
| Path exists | assert_path_exists (with s) | assert_path_exist (no s) |
| Negation pattern | refute_* (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
| Method | Purpose |
|---|---|
assert_nothing_raised | Passes if block doesn't raise (also added by Rails on top of minitest) |
assert_true / assert_false | Checks for exactly true or false (not just truthy/falsy) |
assert_boolean | Checks value is true or false |
assert_compare | For <, <=, >, >= comparisons |
assert_raise_with_message | Checks both exception class and message |
assert_raise_message | Checks exception message only (any class) |
assert_raise_kind_of | Checks exception via kind_of? instead of exact class |
assert_const_defined / assert_not_const_defined | Check constant existence |
assert_alias_method | Verify method aliasing |
assert_nothing_thrown | Passes if block doesn't call throw |
assert_block | Passes if block returns truthy |
minitest only
| Method | Purpose |
|---|---|
assert_pattern / refute_pattern | Ruby 3+ pattern matching (in expressions) |
assert_silent | Passes if block produces no stdout/stderr |
assert_output | Check stdout/stderr content |
capture_io / capture_subprocess_io | Capture 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)
| Operation | minitest | test-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 test | N/A |
| By line number | m test/file.rb:42 or minitest test/file.rb:42 (v6) | --location path.rb:LINE |
| By line (Rails) | bin/rails test test/file.rb:42 | N/A |
| Exclude by name | -e /pattern/ | --ignore-name /pattern/ |
| Exclude by class | N/A | --ignore-testcase /pattern/ |
| Filter by class | N/A (use -n /ClassName#/) | --testcase ClassName |
| Filter by attribute | N/A | --attribute "speed == :slow" |
| Seed | -s SEED or --seed SEED | N/A (use --order random) |
| Stop on failure | N/A | --stop-on-failure |
| Execution order | Random 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
| Concept | minitest | test-unit |
|---|---|---|
| Skip a test | skip("reason") | omit("reason") or pend("reason") |
| Conditional skip | skip("reason") if condition | omit("reason") if condition or omit_if(condition, "reason") / omit_unless(condition, "reason") |
| Output character | S | O (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
| Aspect | minitest | test-unit |
|---|---|---|
| Progress | .FES | .FEOPN (adds Omit, Pending, Notification) |
| Summary | N runs, N assertions, N failures, N errors, N skips | N tests, N assertions, N failures, N errors, N pendings, N omissions, N notifications |
| Throughput | runs/s, assertions/s | tests/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/:neverwith probabilistic execution - Attributes: Generic metadata on test methods, filterable via
--attribute sub_test_case: Named nested test groups (minitest usesdescribeblocks in Spec mode)notify: Non-fatal informational messages shown asNin output- Test runners: Console, Emacs, XML (minitest only has console with plugin system)
- Config file:
~/.test-unit.ymlfor 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 alias | Delegates to | Effect |
|---|---|---|
assert_not_* (12 methods) | refute_* | assert_not_nil, assert_not_equal, etc. all work in Rails |
assert_not | refute | Base negation |
assert_raise (singular) | assert_raises | Both singular and plural work in Rails |
assert_no_match | refute_match |
Methods Rails adds (not in either framework):
| Method | Purpose |
|---|---|
assert_nothing_raised | Passes if block doesn't raise |
assert_difference / assert_no_difference | Check numeric change after block |
assert_changes / assert_no_changes | Check 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
| 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:
- 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
Hooks 1
Sponsors
Details
- Marketplace
- st0012/ruby-skills
- Source
- plugins/ruby-skills
- Category
- Community