SKILL.md
Ruby Best Practices
Core Ruby language guide organized as modular rules, independent of any web framework. Covers syntax and types, collections, blocks/procs/lambdas, OOP/modules, metaprogramming, dependency management, testing, style/typing tooling, and performance/debugging.
For Rails-specific concerns (Active Record, controllers, views, jobs, Kamal deployment, etc.), load the sibling ruby-on-rails skill instead.
ROUTING: Which rule file to load
IF working with variables, strings/symbols, numerics, control flow, or pattern matching (case/in): → Read rules/core-syntax-and-types.md
IF working with Array, Hash, Struct, Enumerable, or lazy enumerators: → Read rules/core-collections-enumerable.md
IF working with blocks, yield, Proc, or lambda: → Read rules/core-blocks-procs-lambdas.md
IF working with classes, modules, mixins, or inheritance: → Read rules/core-oop-modules.md
IF writing metaprogramming, DSLs, or dynamic method definitions: → Read rules/metaprogramming.md
IF managing dependencies, a Gemfile, or building/publishing a gem: → Read rules/gems-and-bundler.md
IF writing or fixing tests: → Read rules/testing-rspec-minitest.md
IF configuring linting, formatting, or type-checking tooling: → Read rules/style-and-typing.md
IF profiling, debugging, or tuning Ruby performance: → Read rules/performance-and-debugging.md
Rule index
| Topic | Description | File |
|---|---|---|
| Sections overview | Categories and reading order | [rules/sections.md](rules/sections.md) |
| Syntax & Types | Variables, symbols, strings, numerics, control flow, pattern matching | [rules/core-syntax-and-types.md](rules/core-syntax-and-types.md) |
| Collections & Enumerable | Array, Hash, Struct, Enumerable, lazy enumerators | [rules/core-collections-enumerable.md](rules/core-collections-enumerable.md) |
| Blocks, Procs, Lambdas | Blocks, yield, closures, Proc vs lambda |
[rules/core-blocks-procs-lambdas.md](rules/core-blocks-procs-lambdas.md) |
| OOP & Modules | Classes, modules, mixins, inheritance, method_missing |
[rules/core-oop-modules.md](rules/core-oop-modules.md) |
| Metaprogramming | definemethod, instanceeval/class_eval, DSLs, refinements |
[rules/metaprogramming.md](rules/metaprogramming.md) |
| Gems & Bundler | Dependency management, building/publishing gems | [rules/gems-and-bundler.md](rules/gems-and-bundler.md) |
| Testing | Minitest vs RSpec, doubles, fixtures | [rules/testing-rspec-minitest.md](rules/testing-rspec-minitest.md) |
| Style & Typing | RuboCop, style guides, RBS/Steep/Sorbet, ruby-lsp | [rules/style-and-typing.md](rules/style-and-typing.md) |
| Performance & Debugging | irb/pry, GC tuning, YJIT, profiling | [rules/performance-and-debugging.md](rules/performance-and-debugging.md) |
Rule categories by priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Core language | CRITICAL | core- |
| 2 | Metaprogramming | MEDIUM (advanced/DSL work) | (none) |
| 3 | Dependency management | HIGH | (none) |
| 4 | Testing | HIGH | testing- |
| 5 | Style & Typing | MEDIUM | (none) |
| 6 | Performance & Debugging | MEDIUM | (none) |
Coverage and maintenance
- Coverage map:
rules/_coverage-map.md - Sources: https://www.ruby-lang.org/en/documentation/ (Ruby 4.0, with 3.3/master references) and https://rubystyle.guide/
- Update this skill when a new Ruby major/minor ships or when ruby-lang.org restructures its documentation page.
Ruby CLI quick reference
ruby -v # print Ruby version
ruby -c file.rb # syntax check only
ruby -w file.rb # run with verbose warnings
irb # interactive REPL
gem install pry && pry # richer REPL (better introspection, editing)
bundle init # create a Gemfile
bundle install # install gems from Gemfile.lock
bundle exec rspec # run RSpec inside the bundle's gem set
bundle exec rake test # run Minitest via Rake
rubocop # lint/format check
rubocop -A # auto-correct safe + unsafe offenses
ri Array#each # look up stdlib docs from the CLI