Skip to content

ombulabs/claude-code_rails-upgrade-skill / rails-upgrade

rails-upgrade

Verified

Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.

FileKindSize
SKILL.mdskill md11.0 KB
detection-scripts/gem_limits.rbscript6.0 KB
detection-scripts/hop.rbscript2.2 KB
detection-scripts/patterns/rails-40-patterns.expectations.ymlconfig43.8 KB
detection-scripts/patterns/rails-40-patterns.ymlconfig96.5 KB
detection-scripts/patterns/rails-41-patterns.expectations.ymlconfig25.6 KB
detection-scripts/patterns/rails-41-patterns.ymlconfig59.8 KB
detection-scripts/patterns/rails-42-patterns.expectations.ymlconfig27.5 KB
detection-scripts/patterns/rails-42-patterns.ymlconfig48.7 KB
detection-scripts/patterns/rails-50-patterns.expectations.ymlconfig1.9 KB
detection-scripts/patterns/rails-50-patterns.ymlconfig8.1 KB
detection-scripts/patterns/rails-51-patterns.expectations.ymlconfig4.2 KB
detection-scripts/patterns/rails-51-patterns.ymlconfig15.0 KB
detection-scripts/patterns/rails-52-patterns.expectations.ymlconfig5.0 KB
detection-scripts/patterns/rails-52-patterns.ymlconfig14.7 KB
detection-scripts/patterns/rails-60-patterns.expectations.ymlconfig1007 B
detection-scripts/patterns/rails-60-patterns.ymlconfig14.2 KB
detection-scripts/patterns/rails-70-patterns.expectations.ymlconfig4.0 KB
detection-scripts/patterns/rails-70-patterns.ymlconfig11.2 KB
detection-scripts/patterns/rails-71-patterns.expectations.ymlconfig3.1 KB
detection-scripts/patterns/rails-71-patterns.ymlconfig9.5 KB
detection-scripts/patterns/rails-72-patterns.expectations.ymlconfig1.2 KB
detection-scripts/patterns/rails-72-patterns.ymlconfig6.1 KB
detection-scripts/patterns/rails-80-patterns.expectations.ymlconfig6.6 KB
detection-scripts/patterns/rails-80-patterns.ymlconfig21.2 KB
detection-scripts/patterns/rails-81-patterns.expectations.ymlconfig4.3 KB
detection-scripts/patterns/rails-81-patterns.ymlconfig13.2 KB
detection-scripts/scan_patterns.rbscript42.8 KB
examples/multi-hop-upgrade.mdmarkdown18.9 KB
examples/simple-upgrade.mdmarkdown4.0 KB
references/breaking-changes-by-version-reference.mdmarkdown3.9 KB
references/deprecation-warnings-reference.mdmarkdown10.7 KB
references/gem-compatibility-reference.mdmarkdown8.2 KB
references/js-compressor-sprockets-mismatch-reference.mdmarkdown4.7 KB
references/multi-hop-strategy-reference.mdmarkdown8.8 KB
references/next-hop-readiness-reference.mdmarkdown2.1 KB
references/no-test-suite-smoke-reference.mdmarkdown4.7 KB
references/request-patterns-reference.mdmarkdown3.7 KB
references/sequential-strategy-reference.mdmarkdown2.1 KB
references/staying-current-reference.mdmarkdown7.8 KB
references/testing-checklist-reference.mdmarkdown6.3 KB
templates/app-update-preview-template.mdmarkdown4.3 KB
templates/upgrade-report-template.mdmarkdown10.2 KB
version-guides/upgrade-3.2-to-4.0.mdmarkdown68.0 KB
version-guides/upgrade-4.0-to-4.1.mdmarkdown66.7 KB
version-guides/upgrade-4.1-to-4.2.mdmarkdown60.7 KB
version-guides/upgrade-4.2-to-5.0.mdmarkdown9.7 KB
version-guides/upgrade-5.0-to-5.1.mdmarkdown19.1 KB
version-guides/upgrade-5.1-to-5.2.mdmarkdown17.7 KB
version-guides/upgrade-5.2-to-6.0.mdmarkdown6.4 KB
version-guides/upgrade-6.0-to-6.1.mdmarkdown6.8 KB
version-guides/upgrade-6.1-to-7.0.mdmarkdown14.7 KB
version-guides/upgrade-7.0-to-7.1.mdmarkdown13.2 KB
version-guides/upgrade-7.1-to-7.2.mdmarkdown11.2 KB
version-guides/upgrade-7.2-to-8.0.mdmarkdown23.1 KB
version-guides/upgrade-8.0-to-8.1.mdmarkdown14.0 KB
workflows/00-verify-latest-patch-workflow.mdmarkdown1.7 KB
workflows/01-run-test-suite-workflow.mdmarkdown12.7 KB
workflows/02-resolve-deprecation-warnings-workflow.mdmarkdown6.3 KB
workflows/03-validate-upgrade-path-workflow.mdmarkdown1.8 KB
workflows/04-setup-next-rails-workflow.mdmarkdown1.5 KB
workflows/05-detect-breaking-changes-workflow.mdmarkdown20.0 KB
workflows/06-check-gem-compatibility-workflow.mdmarkdown11.1 KB
workflows/07-boot-smoke-test-workflow.mdmarkdown7.3 KB
workflows/08-generate-upgrade-report-workflow.mdmarkdown12.7 KB
workflows/09-generate-app-update-preview-workflow.mdmarkdown7.3 KB
workflows/10-implement-and-upgrade-workflow.mdmarkdown2.5 KB
workflows/11-sync-ci-workflow.mdmarkdown8.6 KB
workflows/12-align-load-defaults-workflow.mdmarkdown952 B
workflows/13-mention-cleanup-workflow.mdmarkdown1.3 KB

detection-scripts/patterns/rails-70-patterns.yml

View on GitHub
version: "7.0"
description: "Breaking change patterns for Rails 6.1 → 7.0 upgrade"

upgrade_findings:
  high_priority:
    - name: "Ruby version requirement"
      kind: "breaking"
      pattern: "^\\s*(?:ruby\\s*\\(?\\s*[\"'](?:=\\s*|~>\\s*(?=\\d+\\.\\d+\\.\\d))?|ruby-|ruby\\s+)?(?:1\\.\\d+|2\\.[0-6])(?:\\.\\d+)*(?![\\d.])|^\\s*ruby\\s*\\(?\\s*[\"']~>\\s*1\\.\\d+(?![\\d.])"
      exclude: ""
      search_paths:
        - "Gemfile"
        - ".ruby-version"
        - ".tool-versions"
      explanation: "Rails 7.0 requires Ruby 2.7.0 or newer. Flags a Ruby below 2.7.0 in .ruby-version or .tool-versions, and a Gemfile `ruby` line that rules it out (an exact version, or a `~>` whose upper bound is below 2.7.0); a requirement that still allows 2.7.0, such as `>=`, is not flagged"
      fix: "Upgrade Ruby to 2.7.0+ (3.0+ recommended)"
      variable_name: "RUBY_VERSION"

    - name: "Explicit format/handler extension in template: or layout:"
      kind: "breaking"
      pattern: "(template|layout):\\s*[\"'][^\"']*\\.(html|erb)\\b"
      exclude: ""
      search_paths:
        - "app/controllers/"
        - "app/mailers/"
        - "app/views/"
        - "app/helpers/"
      explanation: "A call like `render template: \"posts/show.html.erb\"` or `layout: \"pdf.html\"` worked on 6.1 and raises ActionView::MissingTemplate on 7.0. 6.1 tolerated it and warned: action_view/template/resolver.rb#find_template_paths_from_details emitted \"Rendering actions with '.' in the name is deprecated\" whenever the name contained a dot. That code path is gone in 7.0, so the dotted name is taken literally and matches no template. Most commonly hit via wicked_pdf's `render pdf:` helper, which forwards :template/:layout straight through. A related, non-regex-detectable failure mode: if the render call runs inside a non-html respond_to format block (e.g. `format.pdf do render pdf: ... end`) and does not pass an explicit `formats:` option, Rails resolves the template using the block's format (:pdf) instead of :html, and raises MissingTemplate even with a bare template name -- 6.1 fell back to :html here, 7.0 does not. See workflows/07-boot-smoke-test-workflow.md notes: neither this pattern nor the boot smoke test catches the formats: variant because it only manifests when the specific action+format combination is actually invoked, not at boot."
      fix: "Drop the format/handler extension from the string: template: \"posts/show.html.erb\" -> template: \"posts/show\"; layout: \"pdf.html\" -> layout: \"pdf\". If the render happens inside a non-html format.<x> block, also add formats: [:html] explicitly so template resolution doesn't use the block's format."
      variable_name: "EXPLICIT_TEMPLATE_EXTENSION"

    - name: "Webpacker usage"
      kind: "migration"
      pattern: "webpacker|javascript_pack_tag"
      exclude: "importmap"
      search_paths:
        - "Gemfile"
        - "config/"
        - "app/views/"
      explanation: "Rails 7.0 replaces Webpacker with Import Maps or jsbundling-rails"
      fix: "Migrate to Import Maps, esbuild, or rollup. Remove Webpacker."
      variable_name: "WEBPACKER"

    - name: "form_with local option"
      kind: "migration"
      pattern: "form_with.*local:\\s*(true|false)"
      exclude: ""
      search_paths:
        - "app/views/"
      explanation: "Rails 7.0 changes form_with to submit remotely by default with Turbo"
      fix: "Remove local: true (now default is remote with Turbo). Add data: { turbo: false } if needed."
      variable_name: "FORM_WITH_LOCAL"

  medium_priority:
    - name: "secrets.yml usage"
      kind: "migration"
      pattern: "Rails\\.application\\.secrets"
      exclude: "credentials"
      search_paths:
        - "app/"
        - "lib/"
        - "config/"
      explanation: "Rails.application.secrets still works at 7.0 with no deprecation warning; def secrets in railties/lib/rails/application.rb is byte-for-byte identical to 6.1. The runtime API is officially deprecated in 7.1, so migrating to Rails.application.credentials at this hop avoids rework on the next one"
      fix: "Move values from config/secrets.yml into config/credentials.yml.enc (`rails credentials:edit`), then update readers: Rails.application.secrets.api_key → Rails.application.credentials.api_key. config/master.key must NOT be committed"
      variable_name: "SECRETS_YML"

    - name: "ActiveRecord enum prefix/suffix"
      kind: "migration"
      pattern: "enum.*:.*\\{"
      exclude: ""
      search_paths:
        - "app/models/"
      explanation: "Rails 7.0 changes enum syntax - hash syntax preferred"
      fix: "Review enums. New syntax: enum status: { draft: 0, published: 1 }"
      variable_name: "ENUM_SYNTAX"

    - name: "image_tag skip_pipeline"
      kind: "optional"
      pattern: "image_tag.*skip_pipeline"
      exclude: ""
      search_paths:
        - "app/views/"
        - "app/helpers/"
      explanation: "skip_pipeline is fully supported at Rails 7.0; image_tag's implementation is byte-for-byte identical to 6.1. The option was actually expanded at 7.0 to also work on stylesheet_link_tag. This entry flags call sites for review when migrating away from Sprockets to Propshaft / Importmap, but the option itself does not change at this hop and existing calls continue to work"
      fix: "No change required at the 7.0 hop. If you are also migrating off the Sprockets asset pipeline, audit each skip_pipeline call to confirm it is still doing what you intend under the new pipeline; otherwise leave as-is"
      variable_name: "IMAGE_TAG_PIPELINE"

    - name: "ActiveStorage variant syntax"
      kind: "migration"
      pattern: "\\.variant\\(.*resize:"
      exclude: ""
      search_paths:
        - "app/"
      explanation: "load_defaults 7.0 sets config.active_storage.variant_processor = :vips (railties configuration.rb); below that the processor stays :mini_magick and resize: keeps working with no warning. Under vips, resize: is not an image_processing macro, so it is forwarded to libvips, which does not take an ImageMagick geometry string like \"100x100>\". A named variant declared without parentheses (a.variant :thumb, resize: ...) is missed"
      fix: "Rewrite with the image_processing macros, which work on both processors and both Rails versions: variant(resize_to_limit: [100, 100]), variant(resize_to_fill: [100, 100]). Or keep ImageMagick after load_defaults 7.0 with config.active_storage.variant_processor = :mini_magick"
      variable_name: "ACTIVE_STORAGE_VARIANT"

    - name: "Turbolinks"
      kind: "migration"
      pattern: "turbolinks|Turbolinks"
      exclude: ""
      search_paths:
        - "Gemfile"
        - "app/javascript/"
        - "app/assets/"
      explanation: "Turbolinks replaced by Turbo in Rails 7.0"
      fix: "Replace turbolinks with @hotwired/turbo. Update event listeners."
      variable_name: "TURBOLINKS"

    - name: "UJS (rails-ujs)"
      kind: "migration"
      pattern: "rails-ujs|@rails/ujs"
      exclude: ""
      search_paths:
        - "Gemfile"
        - "app/javascript/"
        - "package.json"
      explanation: "Rails UJS is replaced by Turbo and Stimulus in Rails 7.0"
      fix: "Remove rails-ujs. Use Turbo for remote forms and Stimulus for JavaScript."
      variable_name: "RAILS_UJS"

    - name: "redirect_to open redirect protection"
      kind: "breaking"
      pattern: "redirect_(to|back_or_to)\\s+(params\\[|session\\[|request\\.refer|[\"'][^\"']*(https?://|#\\{))"
      exclude: "allow_other_host"
      search_paths:
        - "app/controllers/"
        - "app/"
        - "lib/"
      explanation: "load_defaults 7.0 sets config.action_controller.raise_on_open_redirects = true. With it on, redirect_to and redirect_back_or_to to a host different from the current one raise ActionController::Redirecting::UnsafeRedirectError instead of redirecting. This is not a deprecation and there is no warning phase; it is gated by load_defaults 7.0, so apps only see it once they bump load_defaults to 7.0 (which is why it often surfaces during a later hop). Redirects to dynamic or external destinations (params, session, request.referer, or a literal/interpolated URL) are the ones that break; redirects to path helpers and model records are unaffected"
      fix: "For each intentional external redirect, pass allow_other_host: true, e.g. redirect_to \"https://example.com\", allow_other_host: true. Never pass allow_other_host: true on a destination built from untrusted input (params, session, request.referer) without validating it against an allowlist first, or the open-redirect protection is defeated. If a redirect target is internal, rewrite it as a path/url helper so it passes without the flag"
      variable_name: "OPEN_REDIRECT_PROTECTION"

    - name: "to_s(:format) deprecation"
      kind: "deprecation"
      pattern: "\\.to_s\\(:"
      exclude: ""
      search_paths:
        - "app/"
        - "lib/"
      explanation: "to_s(:format) is deprecated in favor of to_fs(:format)"
      fix: "Replace to_s(:format) with to_fs(:format)"
      variable_name: "TO_S_FORMAT"

  low_priority:
    - name: "Spring usage"
      kind: "optional"
      pattern: "gem ['\"]spring['\"]"
      exclude: "\\A\\s*#"
      search_paths:
        - "Gemfile"
      explanation: "Rails 7.0 no longer adds spring to new apps (the Gemfile template only has it commented out). An app that keeps it needs spring 4.0 or later: 4.0.0 is the first release whose README lists Rails 7.0, and spring 3.x README stops at 6.0"
      fix: "Remove spring and bin/spring if the team does not rely on it, or bump to gem \"spring\", \">= 4.0\" (needs Rails 6.0 or later, so it runs on both sides of the dual boot)"
      variable_name: "SPRING"

    - name: "config.action_controller.urlsafe_csrf_tokens set explicitly"
      kind: "deprecation"
      pattern: "\\burlsafe_csrf_tokens\\s*="
      exclude: "\\A\\s*#"
      search_paths:
        - "config/"
      explanation: "Rails 7.0 makes URL-safe CSRF tokens the only default (actionpack 7.0 sets urlsafe_csrf_tokens = true) and deprecates the setting: assigning it warns \"URL-safe CSRF tokens are now the default. Use 6.1 defaults or above.\" for true and \"Non-URL-safe CSRF tokens are deprecated. Use 6.1 defaults or above.\" for false. Rails 7.1 removes the setting. An app on load_defaults below 6.1 gets the second warning with no line of its own, because load_defaults 5.0 sets it to false; this pattern only finds an explicit assignment. Tokens keep working across a rolling deploy: 7.0 still decodes the standard base64 tokens 6.1 issued"
      fix: "Delete the line on the Rails 7.0 side: `config.action_controller.urlsafe_csrf_tokens = true unless NextRails.next?` keeps it for the 6.1 side only. If the app is on load_defaults below 6.1, move to 6.1 defaults or above, which stops setting it to false"
      variable_name: "URLSAFE_CSRF_TOKENS"

dependencies:
  importmap:
    check: true
    gem_name: "importmap-rails"
    message: "Rails 7.0 uses Import Maps by default for JavaScript"
    url: "https://github.com/rails/importmap-rails"

  turbo:
    check: true
    gem_name: "turbo-rails"
    message: "Rails 7.0 uses Turbo (Hotwire) for SPA-like navigation"
    url: "https://github.com/hotwired/turbo-rails"

  stimulus:
    check: true
    gem_name: "stimulus-rails"
    message: "Rails 7.0 uses Stimulus for JavaScript behaviors"
    url: "https://github.com/hotwired/stimulus-rails"
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall