steveclarke/rails-upgrade-assistant
ai/skills/rails-upgrade-assistant/SKILL.md
Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 7.0 through 8.1.1. Use when upgrading Rails applications, planning multi-hop upgrades, or querying version-specific changes.
$ install --global
skillsauthnpx skillsauth add steveclarke/dotfiles rails-upgrade-assistantInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 13, 2026, 6:37 PM28.7s28 files scanned
SKILL.md
- name:
- rails-upgrade-assistant
- description:
- Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 7.0 through 8.1.1. Use when upgrading Rails applications, planning multi-hop upgrades, or querying version-specific changes.
Rails Upgrade Assistant Skill v1.0
How It Works
Three-step process:
- Detection Script — Generate a bash script that scans the codebase for breaking changes with file:line references
- User Runs Script — User executes it, gets
rails_{version}_upgrade_findings.txt - Reports — Generate upgrade report and app:update preview based on actual findings (not hypothetical)
Sequential Upgrade Strategy
⚠️ Version Skipping is NOT Allowed
Rails upgrades MUST follow this exact sequence:
7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x
You CANNOT skip versions. Examples:
- ❌ 7.0 → 7.2 (skips 7.1)
- ❌ 7.0 → 8.0 (skips 7.1 and 7.2)
- ✅ 7.0 → 7.1 (correct)
- ✅ 7.1 → 7.2 (correct)
If user requests a multi-hop upgrade (e.g., 7.0 → 8.1):
- Explain the sequential requirement
- Break it into individual hops
- Generate separate reports for each hop
- Recommend completing each hop fully before moving to next
Available Resources
Core Documentation
docs/README.md- Human-readable overviewdocs/QUICK-REFERENCE.md- Command cheat sheetdocs/USAGE-GUIDE.md- Comprehensive how-to
Version-Specific Guides (Load as needed)
version-guides/upgrade-7.0-to-7.1.md- Rails 7.0 → 7.1version-guides/upgrade-7.1-to-7.2.md- Rails 7.1 → 7.2version-guides/upgrade-7.2-to-8.0.md- Rails 7.2 → 8.0version-guides/upgrade-8.0-to-8.1.md- Rails 8.0 → 8.1
Workflow Guides (Load when generating deliverables)
workflows/upgrade-report-workflow.md- How to generate upgrade reportsworkflows/detection-script-workflow.md- How to generate detection scriptsworkflows/app-update-preview-workflow.md- How to generate app:update previews
Examples (Load when user needs clarification)
examples/simple-upgrade.md- Single-hop upgrade exampleexamples/multi-hop-upgrade.md- Multi-hop upgrade exampleexamples/detection-script-only.md- Detection script only requestexamples/preview-only.md- Preview only request
Reference Materials
reference/breaking-changes-by-version.md- Quick lookupreference/multi-hop-strategy.md- Multi-version planningreference/deprecations-timeline.md- Deprecation trackingreference/testing-checklist.md- Comprehensive testingreference/pattern-file-guide.md- How to use pattern filesreference/quality-checklist.md- Pre-delivery verificationreference/troubleshooting.md- Common issues and solutions
Detection Script Resources
detection-scripts/patterns/rails-72-patterns.yml- Rails 7.2 patternsdetection-scripts/patterns/rails-80-patterns.yml- Rails 8.0 patternsdetection-scripts/patterns/rails-81-patterns.yml- Rails 8.1 patternsdetection-scripts/templates/detection-script-template.sh- Bash template
Report Templates
templates/upgrade-report-template.md- Main upgrade report structuretemplates/app-update-preview-template.md- Configuration preview
Workflow
Phase 1: Generate Detection Script
- Detect current Rails version from
Gemfile.lock - Read
detection-scripts/patterns/rails-{VERSION}-patterns.yml - Read
detection-scripts/templates/detection-script-template.sh - Read
workflows/detection-script-workflow.md - Generate version-specific bash script and deliver to user
Phase 2: User Runs Script
User runs the script, gets findings. Wait for them to share rails_{version}_upgrade_findings.txt.
Phase 3: Generate Reports
- Parse findings.txt — extract breaking changes and affected files
- Read
version-guides/upgrade-{FROM}-to-{TO}.md - Read
workflows/upgrade-report-workflow.mdandworkflows/app-update-preview-workflow.md - Generate Comprehensive Upgrade Report with real code from the user's project
- Generate app:update Preview with actual config file diffs
Quality
Before delivering any output, verify against reference/quality-checklist.md. Key rules:
- Replace all {PLACEHOLDERS} with actual values
- Use ACTUAL findings from the script, not generic examples
- Include real file:line references and real code from the user's project
- Flag custom code with warnings
Bundled Resources
Load these as needed — don't read everything upfront:
| Directory | When to load |
|-----------|-------------|
| workflows/ | Before generating detection scripts or reports |
| version-guides/ | When you need version-specific breaking changes |
| templates/ | When generating report output |
| detection-scripts/patterns/ | When building the detection script |
| examples/ | When user needs clarification on the process |
| reference/ | For quality checks, troubleshooting, pattern file format |
Related Skills
steveclarke/youtube
content-media
VerifiedTrustedCommunity
Download content from YouTube including transcripts, captions, subtitles, music, MP3s, and playlists. Use when the user provides a YouTube URL or asks to download, transcribe, or get content from YouTube videos or playlists.
32SKILL.mdUpdated Apr 13, 2026
steveclarke/vueuse-functions
development
VerifiedTrustedCommunity
Apply VueUse composables where appropriate to build concise, maintainable Vue.js / Nuxt features.
32SKILL.mdUpdated Apr 13, 2026
steveclarke/ui-review
development
VerifiedTrustedCommunity
Review UI for visual consistency, layout structure, and design system compliance. Two modes — code review (check view files against patterns) and visual audit (screenshot all routes and analyze). Use when reviewing UI code, checking consistency, auditing views, or when user says "review the UI", "check consistency", "UI audit", "design review".
32SKILL.mdUpdated Apr 13, 2026
steveclarke/typeset
tools
VerifiedTrustedCommunity
Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography.
32SKILL.mdUpdated Apr 13, 2026