Skip to content
Back to search

rails-upgrade-skill

SkillGitHubIncomplete

Claude Skill to upgrade a Rails application

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maquina-app--rails-upgrade-skill/badge.svg)](/listings/maquina-app--rails-upgrade-skill)

HTML

<a href="/listings/maquina-app--rails-upgrade-skill"><img src="/api/listings/maquina-app--rails-upgrade-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 418 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: rails-upgrade-assistant
  3. 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.
  4. ---
  5. # Rails Upgrade Assistant Skill v1.0
  6. ## Skill Identity
  7. - **Name:** Rails Upgrade Assistant
  8. - **Version:** 1.0
  9. - **Purpose:** Intelligent Rails application upgrades from 7.0 through 8.1.1
  10. - **Based on:** Official Rails CHANGELOGs from GitHub
  11. - **Upgrade Strategy:** Sequential only (no version skipping)
  12. ---
  13. ## Core Functionality
  14. This skill helps users upgrade Rails applications through a sequential three-step process:
  15. ### Step 1: Breaking Changes Detection Script
  16. - Claude generates executable bash script tailored to the specific upgrade
  17. - Script scans user's codebase for breaking changes
  18. - Finds issues with file:line references
  19. - Generates findings report (TXT file)
  20. - Runs in < 30 seconds
  21. - Lists affected files for Neovim integration
  22. ### Step 2: User Runs Script & Shares Findings
  23. - User executes the detection script in their project directory
  24. - Script outputs `rails_{version}_upgrade_findings.txt`
  25. - User shares findings report back with Claude
  26. ### Step 3: Claude Generates Reports Based on Actual Findings
  27. - **Comprehensive Upgrade Report**: Breaking changes analysis with OLD vs NEW code examples, custom code warnings with ⚠️ flags, step-by-step migration plan, testing checklist and rollback plan
  28. - **app:update Preview Report**: Shows exact configuration file changes (OLD vs NEW), lists new files to be created, impact assessment (HIGH/MEDIUM/LOW), Neovim buffer list ready
  29. **User Benefits:**
  30. - ⏱️ Saves 2-3 hours per upgrade (automated detection)
  31. - 🎯 90%+ accuracy in finding breaking changes
  32. - 📋 Clear file:line references for every issue
  33. - 🚀 Reports based on ACTUAL detected issues, not hypothetical
  34. - 📊 50% faster upgrades overall
  35. ---
  36. ## Trigger Patterns
  37. Claude should activate this skill when user says:
  38. **Initial Upgrade Requests (Generate Detection Script):**
  39. - "Upgrade my Rails app to [version]"
  40. - "Help me upgrade from Rails [x] to [y]"
  41. - "What breaking changes are in Rails [version]?"
  42. - "Plan my upgrade from [x] to [y]"
  43. - "What Rails version am I using?"
  44. - "Analyze my Rails app for upgrade"
  45. - "Create a detection script for Rails [version]"
  46. - "Generate a breaking changes script"
  47. - "Find breaking changes in my code"
  48. **After Script Execution (Generate Reports):**
  49. - "Here's my findings.txt"
  50. - "I ran the script, here are the results"
  51. - "The detection script found [X] issues"
  52. - "Can you analyze these findings?"
  53. - *User shares/uploads findings.txt file*
  54. **Specific Report Requests (Only After Findings Shared):**
  55. - "Show me the app:update changes"
  56. - "Preview configuration changes for Rails [version]"
  57. - "Generate the upgrade report"
  58. - "Create the comprehensive report"
  59. ---
  60. ## CRITICAL: Sequential Upgrade Strategy
  61. ### ⚠️ Version Skipping is NOT Allowed
  62. Rails upgrades MUST follow this exact sequence:
  63. ```
  64. 7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x
  65. ```
  66. **You CANNOT skip versions.** Examples:
  67. - ❌ 7.0 → 7.2 (skips 7.1)
  68. - ❌ 7.0 → 8.0 (skips 7.1 and 7.2)
  69. - ✅ 7.0 → 7.1 (correct)
  70. - ✅ 7.1 → 7.2 (correct)
  71. If user requests a multi-hop upgrade (e.g., 7.0 → 8.1):
  72. 1. Explain the sequential requirement
  73. 2. Break it into individual hops
  74. 3. Generate separate reports for each hop
  75. 4. Recommend completing each hop fully before moving to next
  76. ---
  77. ## Available Resources
  78. ### Core Documentation
  79. - `docs/README.md` - Human-readable overview
  80. - `docs/QUICK-REFERENCE.md` - Command cheat sheet
  81. - `docs/USAGE-GUIDE.md` - Comprehensive how-to
  82. ### Version-Specific Guides (Load as needed)
  83. - `version-guides/upgrade-7.0-to-7.1.md` - Rails 7.0 → 7.1
  84. - `version-guides/upgrade-7.1-to-7.2.md` - Rails 7.1 → 7.2
  85. - `version-guides/upgrade-7.2-to-8.0.md` - Rails 7.2 → 8.0
  86. - `version-guides/upgrade-8.0-to-8.1.md` - Rails 8.0 → 8.1
  87. ### Workflow Guides (Load when generating deliverables)
  88. - `workflows/upgrade-report-workflow.md` - How to generate upgrade reports
  89. - `workflows/detection-script-workflow.md` - How to generate detection scripts
  90. - `workflows/app-update-preview-workflow.md` - How to generate app:update previews
  91. ### Examples (Load when user needs clarification)
  92. - `examples/simple-upgrade.md` - Single-hop upgrade example
  93. - `examples/multi-hop-upgrade.md` - Multi-hop upgrade example
  94. - `examples/detection-script-only.md` - Detection script only request
  95. - `examples/preview-only.md` - Preview only request
  96. ### Reference Materials
  97. - `reference/breaking-changes-by-version.md` - Quick lookup
  98. - `reference/multi-hop-strategy.md` - Multi-version planning
  99. - `reference/deprecations-timeline.md` - Deprecation tracking
  100. - `reference/testing-checklist.md` - Comprehensive testing
  101. - `reference/pattern-file-guide.md` - How to use pattern files
  102. - `reference/quality-checklist.md` - Pre-delivery verification
  103. - `reference/troubleshooting.md` - Common issues and solutions
  104. ### Detection Script Resources
  105. - `detection-scripts/patterns/rails-72-patterns.yml` - Rails 7.2 patterns
  106. - `detection-scripts/patterns/rails-80-patterns.yml` - Rails 8.0 patterns
  107. - `detection-scripts/patterns/rails-81-patterns.yml` - Rails 8.1 patterns
  108. - `detection-scripts/templates/detection-script-template.sh` - Bash template
  109. ### Report Templates
  110. - `templates/upgrade-report-template.md` - Main upgrade report structure
  111. - `templates/app-update-preview-template.md` - Configuration preview
  112. ---
  113. ## MCP Tools Integration
  114. ### Required: Rails MCP Server
  115. **Tools:**
  116. - `railsMcpServer:project_info` - Get Rails version, structure, API mode
  117. - `railsMcpServer:get_file` - Read file contents
  118. - `railsMcpServer:list_files` - Browse directories
  119. - `railsMcpServer:analyze_environment_config` - Config files
  120. ### Optional: Neovim MCP Server
  121. **Tools:**
  122. - `nvimMcpServer:get_project_buffers` - List open files
  123. - `nvimMcpServer:update_buffer` - Update file content
  124. ---
  125. ## High-Level Workflow
  126. When user requests an upgrade, follow this workflow:
  127. ### Step 1: Detect Current Version
  128. ```
  129. 1. Call: railsMcpServer:project_info
  130. 2. Store: current_version, target_version, project_type, project_root
  131. ```
  132. ### Step 2: Load Detection Script Resources
  133. ```
  134. 1. Read: detection-scripts/patterns/rails-{VERSION}-patterns.yml
  135. 2. Read: detection-scripts/templates/detection-script-template.sh
  136. 3. Read: workflows/detection-script-workflow.md (for generation instructions)
  137. ```
  138. ### Step 3: Generate Detection Script
  139. ```
  140. 1. Follow workflow in detection-script-workflow.md
  141. 2. Generate version-specific bash script
  142. 3. Deliver script to user
  143. 4. Instruct user to run script and share findings.txt
  144. ```
  145. ### Step 4: Wait for User to Run Script
  146. ```
  147. User runs: ./detect_rails_{version}_breaking_changes.sh
  148. Script outputs: rails_{version}_upgrade_findings.txt
  149. User shares findings back with Claude
  150. ```
  151. ### Step 5: Load Report Generation Resources
  152. ```
  153. 1. Read: templates/upgrade-report-template.md
  154. 2. Read: version-guides/upgrade-{FROM}-to-{TO}.md
  155. 3. Read: templates/app-update-preview-template.md
  156. 4. Read: workflows/upgrade-report-workflow.md
  157. 5. Read: workflows/app-update-preview-workflow.md
  158. ```
  159. ### Step 6: Analyze User's Actual Findings
  160. ```
  161. 1. Parse the findings.txt file
  162. 2. Extract detected breaking changes and affected files
  163. 3. Read user's actual config files for context
  164. 4. Identify custom code patterns from findings
  165. ```
  166. ### Step 7: Generate Reports Based on Findings
  167. **Deliverable #1: Comprehensive Upgrade Report**
  168. - **Workflow:** See `workflows/upgrade-report-workflow.md`
  169. - **Input:** Actual findings from script + version guide data
  170. - **Output:** Report with real code examples from user's project
  171. **Deliverable #2: app:update Preview**
  172. - **Workflow:** See `workflows/app-update-preview-workflow.md`
  173. - **Input:** Actual config files + findings
  174. - **Output:** Preview with real file paths and changes
  175. ### Step 8: Present Reports
  176. ```
  177. 1. Present Comprehensive Upgrade Report first
  178. 2. Present app:update Preview Report second
  179. 3. Explain next steps
  180. 4. Offer interactive help with Neovim (if available)
  181. ```
  182. ---
  183. ## When to Load Detailed Workflows
  184. Load workflow files when you need detailed instructions:
  185. **Step 1 - Load Before Generating Detection Script:**
  186. - `workflows/detection-script-workflow.md` - Before creating detection scripts
  187. **Step 2 - User Runs Script (No Claude action needed)**
  188. **Step 3 - Load Before Generating Reports (After receiving findings):**
  189. - `workflows/upgrade-report-workflow.md` - Before creating upgrade reports
  190. - `workflows/app-update-preview-workflow.md` - Before creating previews
  191. **Load When User Needs Examples:**
  192. - `examples/simple-upgrade.md` - User asks about simple upgrades
  193. - `examples/multi-hop-upgrade.md` - User asks about complex upgrades
  194. - `examples/detection-script-only.md` - User wants only detection script
  195. - `examples/preview-only.md` - User wants only preview
  196. **Load When You Need Reference:**
  197. - `reference/pattern-file-guide.md` - When processing YAML pattern files
  198. - `reference/quality-checklist.md` - Before delivering any output
  199. - `reference/troubleshooting.md` - When encountering issues
  200. ---
  201. ## Quality Checklist
  202. Before delivering, verify:
  203. **For Detection Script:**
  204. - [ ] All {PLACEHOLDERS} replaced with actual values
  205. - [ ] Patterns match target Rails version
  206. - [ ] Script includes all breaking changes from pattern file
  207. - [ ] File paths use user's actual project structure
  208. - [ ] User instructions are clear
  209. **After User Runs Script (Before Generating Reports):**
  210. - [ ] Received and parsed findings.txt from user
  211. - [ ] Identified all detected breaking changes
  212. - [ ] Collected affected file paths
  213. - [ ] Noted custom code warnings from findings
  214. **For Comprehensive Upgrade Report:**
  215. - [ ] All {PLACEHOLDERS} replaced with actual values
  216. - [ ] Used ACTUAL findings from script (not generic examples)
  217. - [ ] Breaking changes section includes real file:line references
  218. - [ ] Custom code warnings based on actual detected issues
  219. - [ ] Code examples use user's actual code from affected files
  220. - [ ] Next steps clearly outlined
  221. **For app:update Preview:**
  222. - [ ] All {PLACEHOLDERS} replaced with actual values
  223. - [ ] File list matches user's actual config files
  224. - [ ] Diffs based on real current config vs target version
  225. - [ ] Neovim buffer list includes only affected files
  226. - [ ] Next steps clearly outlined
  227. **Detailed Checklist:** See `reference/quality-checklist.md`
  228. ---
  229. ## Common Request Patterns
  230. ### Pattern 1: Full Upgrade Request
  231. **User says:** "Upgrade my Rails app to 8.1"
  232. **Action - Phase 1 (Generate Script):**
  233. 1. Load: `workflows/detection-script-workflow.md`
  234. 2. Generate detection script
  235. 3. Deliver script with instructions to run it
  236. 4. Wait for user to share findings.txt
  237. **Action - Phase 2 (Generate Reports):**
  238. 1. Parse findings.txt
  239. 2. Load: `workflows/upgrade-report-workflow.md`
  240. 3. Load: `workflows/app-update-preview-workflow.md`
  241. 4. Generate Comprehensive Upgrade Report (using actual findings)
  242. 5. Generate app:update Preview (using actual findings)
  243. 6. Reference: `examples/simple-upgrade.md` for structure
  244. ### Pattern 2: Multi-Hop Request
  245. **User says:** "Help me upgrade from Rails 7.0 to 8.1"
  246. **Action:**
  247. 1. Explain sequential requirement
  248. 2. Reference: `examples/multi-hop-upgrade.md`
  249. 3. Follow Pattern 1 for FIRST hop (7.0 → 7.1)
  250. 4. After first hop complete, repeat for next hops
  251. ### Pattern 3: Detection Script Only
  252. **User says:** "Create a detection script for Rails 8.0"
  253. **Action:**
  254. 1. Load: `workflows/detection-script-workflow.md`
  255. 2. Generate detection script only
  256. 3. Reference: `examples/detection-script-only.md`
  257. 4. Do NOT generate reports yet (wait for findings)
  258. ### Pattern 4: User Returns with Findings
  259. **User says:** "Here's my findings.txt" or shares script output
  260. **Action:**
  261. 1. Parse findings.txt
  262. 2. Load: `workflows/upgrade-report-workflow.md`
  263. 3. Load: `workflows/app-update-preview-workflow.md`
  264. 4. Generate Comprehensive Upgrade Report
  265. 5. Generate app:update Preview
  266. ### Pattern 5: Preview Only (After Findings Shared)
  267. **User says:** "Show me the app:update changes for Rails 7.2"
  268. **Action:**
  269. 1. Check if user has shared findings
  270. 2. If yes: Load `workflows/app-update-preview-workflow.md` and generate
  271. 3. If no: Ask user to run detection script first
  272. 4. Reference: `examples/preview-only.md`
  273. ---
  274. ## Key Principles
  275. 1. **Always Generate Detection Script First** (unless user only wants reports and has findings)
  276. 2. **Wait for User to Run Script** (reports depend on actual findings)
  277. 3. **Always Use Actual Findings** (no generic examples in reports)
  278. 4. **Always Flag Custom Code** (with ⚠️ warnings based on detected issues)
  279. 5. **Always Use Templates** (for consistency)
  280. 6. **Always Check Quality** (before delivery)
  281. 7. **Load Workflows as Needed** (don't hold everything in memory)
  282. 8. **Sequential Process is Critical** (script → findings → reports)
  283. ---
  284. ## File Organization
  285. This skill follows a modular structure:
  286. ```
  287. rails-upgrade-assistant/
  288. ├── SKILL.md # This file (high-level)
  289. ├── workflows/ # Detailed how-to guides
  290. │ ├── upgrade-report-workflow.md
  291. │ ├── detection-script-workflow.md
  292. │ └── app-update-preview-workflow.md
  293. ├── examples/ # Usage examples
  294. │ ├── simple-upgrade.md
  295. │ ├── multi-hop-upgrade.md
  296. │ ├── detection-script-only.md
  297. │ └── preview-only.md
  298. ├── reference/ # Reference documentation
  299. │ ├── pattern-file-guide.md
  300. │ ├── quality-checklist.md
  301. │ └── troubleshooting.md
  302. ├── version-guides/ # Version-specific guides
  303. ├── templates/ # Report templates
  304. └── detection-scripts/ # Pattern files and templates
  305. ```
  306. **When to Load What:**
  307. - Load `workflows/` when generating deliverables
  308. - Load `examples/` when user needs clarification
  309. - Load `reference/` when you need detailed guidance
  310. ---
  311. ## Success Criteria
  312. A successful upgrade assistance session:
  313. ✅ Generated detection script (Phase 1)
  314. ✅ User ran script and shared findings.txt (Phase 2)
  315. ✅ Generated Comprehensive Upgrade Report using actual findings (Phase 3)
  316. ✅ Generated app:update Preview using actual findings (Phase 3)
  317. ✅ Used user's actual code from findings (not generic examples)
  318. ✅ Flagged all custom code with ⚠️ warnings based on detected issues
  319. ✅ Provided clear next steps
  320. ✅ Offered interactive help (if Neovim available)
  321. **Verification:** See `reference/quality-checklist.md`
  322. ---
  323. **Version:** 1.0
  324. **Last Updated:** November 2, 2025
  325. **Skill Type:** Modular with external workflows and examples

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.