gh-nbarthel-claudy-plugins-rails-workflow/skills/rails-version-detector/SKILL.md

Rails Version Detector

---

name: rails-version-detector description: Detects Rails version from project files (Gemfile.lock, Gemfile, or .ruby-version) version: 1.1.0 author: Rails Workflow Team tags: [rails, version, detection, helper] priority: 2

Purpose

Automatically detects the Rails version in the current project by inspecting:

1. Gemfile.lock (preferred - exact version)
2. Gemfile (fallback - version constraint)
3. .ruby-version or .tool-versions (Ruby version hint)

Returns version information for use by other skills and agents.

Usage

This skill is auto-invoked by other Rails skills when they need version information.

Manual invocation (rarely needed):

@rails-version-detector

Detection Strategy

Priority 1: Gemfile.lock (Exact Version)

# Searches for:
rails (7.1.3)
  actioncable (= 7.1.3)
  actionmailbox (= 7.1.3)
  ...

Extraction logic:

• Pattern: rails \((\d+\.\d+\.\d+)\)
• Returns: Exact version (e.g., "7.1.3")

Priority 2: Gemfile (Version Constraint)

# Searches for:
gem "rails", "~> 7.1.0"
gem 'rails', '>= 7.0.0', '< 8.0'

Extraction logic:

• Pattern: gem ['"]rails['"],\s*['"]([^'"]+)['"]
• Returns: Version constraint (e.g., "~> 7.1.0")
• Interprets: "~> 7.1.0" → "7.1.x"

Priority 3: Ruby Version (Heuristic)

# .ruby-version or .tool-versions
ruby 3.2.2

Mapping:

• Ruby 3.3.x → Rails 7.1+ or 8.0+
• Ruby 3.2.x → Rails 7.0+
• Ruby 3.1.x → Rails 7.0+
• Ruby 3.0.x → Rails 6.1+ or 7.0
• Ruby 2.7.x → Rails 6.0 or 6.1

Returns: Estimated range (e.g., "7.0 or 7.1")

Output Format

Success Response

{
  "version": "7.1.3",
  "source": "Gemfile.lock",
  "confidence": "exact",
  "major": 7,
  "minor": 1,
  "patch": 3
}

Constraint Response

{
  "version": "~> 7.1.0",
  "source": "Gemfile",
  "confidence": "constraint",
  "interpreted_as": "7.1.x",
  "major": 7,
  "minor": 1
}

Heuristic Response

{
  "version": "7.0-7.1",
  "source": ".ruby-version",
  "confidence": "heuristic",
  "ruby_version": "3.2.2",
  "possible_rails": ["7.0", "7.1"]
}

Not Found Response

{
  "version": null,
  "source": null,
  "confidence": "none",
  "error": "No Rails version detected. Is this a Rails project?"
}

Implementation

Tool usage:

• Read tool to read Gemfile.lock, Gemfile, .ruby-version
• Grep tool to search for version patterns
• Fallback to Bash if needed: bundle show rails | grep 'rails-'

Caching:

• Version detection results cached for session
• Re-check if Gemfile.lock modified (check mtime)

Error Handling

Gemfile.lock missing:

• Fallback to Gemfile
• Warn: "Gemfile.lock not found. Run bundle install for exact version."

No version found:

• Return error response
• Suggest: "Ensure gem 'rails' in Gemfile"

Multiple Rails versions:

• Return first match (main Rails gem)
• Ignore: railties, actionpack (these are sub-gems)

Integration

Auto-invoked by:

• @rails-docs-search (to fetch correct version docs)
• @rails-api-lookup (to search version-specific APIs)
• @rails-pattern-finder (to find version-appropriate patterns)
• All 7 Rails agents (to ensure version-compatible code generation)

Manual use case:

User: "What Rails version is this project using?"
Assistant: *invokes @rails-version-detector*
          "This project uses Rails 7.1.3 (detected from Gemfile.lock)"

Testing

Test cases:

1. Rails 7.1.3 in Gemfile.lock → Exact version
2. ~> 7.1.0 in Gemfile → Interpreted as 7.1.x
3. Ruby 3.2.2 only → Heuristic: 7.0-7.1
4. No Rails → Error response
5. Rails 8.0.0 → Correct major version detection

Notes

• This skill replaces the need for mcp__rails__get_rails_info MCP tool
• Version detection is fast (< 1 second)
• Results cached per session to avoid repeated file reads
• Confidence levels help downstream skills decide if they need clarification from user