gh-nbarthel-claudy-plugins-rails-workflow/skills/rails-docs-search/SKILL.md

Rails Docs Search

---

name: rails-docs-search description: Searches Rails Guides for conceptual documentation using Ref (primary) or WebFetch (fallback) with reference mappings version: 1.2.0 author: Rails Workflow Team tags: [rails, documentation, guides, search, ref] priority: 3

Purpose

Fetches conceptual documentation from official Rails Guides based on topics. Returns relevant guide sections with version-appropriate URLs.

Replaces: mcp__rails__search_docs MCP tool

Usage

Auto-invoked when agents need Rails concepts:

Agent: "How do I implement Action Cable subscriptions?"
*invokes rails-docs-search topic="action_cable"*

Manual invocation:

@rails-docs-search topic="active_record_associations"
@rails-docs-search topic="routing"

Supported Topics

See reference.md for complete topic list. Common topics:

Core Concepts

• getting_started - Rails basics and first app
• active_record_basics - ORM fundamentals
• routing - URL patterns and routes
• controllers - Request/response handling
• views - Templates and rendering

Advanced Features

• active_record_associations - Relationships (has_many, belongs_to)
• active_record_validations - Data validation
• active_record_callbacks - Lifecycle hooks
• action_mailer - Email sending
• action_cable - WebSockets

Testing & Security

• testing - Rails testing guide
• security - Security best practices
• debugging - Debugging techniques

Deployment & Configuration

• configuring - Application configuration
• asset_pipeline - Asset management
• caching - Performance caching

Search Process

Step 1: Version Detection

Invokes: @rails-version-detector
Result: Rails 7.1.3
Maps to: https://guides.rubyonrails.org/v7.1/

Step 2: Topic Mapping

Input: topic="active_record_associations"
Lookup: reference.md → "association_basics.html"
URL: https://guides.rubyonrails.org/v7.1/association_basics.html

Step 3: Content Fetch

Method 1: Context7 (Fastest):

Tool: context7_fetch
Query: "Rails [version] [topic]"

Method 2: Ref (Token-Efficient):

Tool: ref_search_documentation
Query: "Rails [version] [topic] documentation"
Then: ref_read_url

Method 3: Tavily (Search):

Tool: tavily_search
Query: "Rails [version] [topic] guide"

Method 4: WebFetch (Fallback):

Tool: WebFetch
URL: [constructed URL from reference.md]
Prompt: "Extract sections about [specific query]"

Note: WebFetch has a built-in 15-minute cache for faster responses
when repeatedly accessing the same URL within a session.

Step 4: Response Formatting

## Rails Guide: Active Record Associations (v7.1)

### belongs_to
A `belongs_to` association sets up a one-to-one connection...

### has_many
A `has_many` association indicates a one-to-many connection...

Source: https://guides.rubyonrails.org/v7.1/association_basics.html

Reference Lookup

Topic → Guide URL mapping in reference.md:

active_record_associations:
  title: "Active Record Associations"
  url_path: "association_basics.html"
  version_support: "all"
  keywords: [has_many, belongs_to, has_one, through]

routing:
  title: "Rails Routing"
  url_path: "routing.html"
  version_support: "all"
  keywords: [routes, resources, namespace]

Output Format

Success Response

## Rails Guide: [Topic Title] (v[X.Y])

[Fetched content from guide...]

### Key Points
- [Summary point 1]
- [Summary point 2]

**Source**: [full URL]
**Version**: [Rails version]

Not Found Response

## Topic Not Found: [topic]

Available topics:
- getting_started
- active_record_basics
- routing
[...more topics...]

Try: @rails-docs-search topic="[one of above]"

Version Mismatch Warning

## Rails Guide: [Topic] (v7.1)

⚠️ **Note**: Guide is for Rails 7.1, but project uses Rails 6.1.
Some features may not be available in your version.

[Content...]

Implementation Details

Tools used (in order of preference):

1. @rails-version-detector - Get project Rails version
2. Read - Load reference.md topic mappings
3. context7_fetch (primary) - Fetch curated docs via Context7 MCP
4. ref_search_documentation (secondary) - Search Rails docs via Ref MCP
5. tavily_search (tertiary) - Optimized search via Tavily MCP
6. WebFetch (fallback) - Fetch guide content if MCPs not available
7. Grep (optional) - Search local cached guides if available

Optional dependencies:

• context7-mcp: Fastest, curated documentation
• ref-tools-mcp: Token-efficient documentation search
• tavily-mcp: Optimized search for LLMs
• If neither installed: Falls back to WebFetch (still works!)

URL construction:

Base: https://guides.rubyonrails.org/
Versioned: https://guides.rubyonrails.org/v7.1/
Guide: https://guides.rubyonrails.org/v7.1/routing.html

Version handling:

• Rails 8.x → /v8.0/ (or latest if 8.0 not published)
• Rails 7.1.x → /v7.1/
• Rails 7.0.x → /v7.0/
• Rails 6.1.x → /v6.1/

Caching strategy:

• Cache fetched guide content for session
• Re-fetch if version changes
• Cache key: {topic}:{version}

Prompt Caching (Opus 4.5 Optimized):

• Use 1-hour cache duration for extended thinking tasks
• Documentation content is stable - leverage longer cache windows
• Cache prefix: Include Rails version in system prompt for cache reuse
• Reduces token costs significantly for repeated lookups

Error Handling

Network failure:

⚠️ Failed to fetch guide from rubyonrails.org

Fallback: Check local knowledge or ask user for clarification.
URL attempted: [URL]

Invalid topic:

❌ Unknown topic: "[topic]"

Did you mean: [closest match from reference.md]?

See available topics: @rails-docs-search list

Version not supported:

⚠️ Rails [version] guides not available.

Using closest version: [fallback version]
Some information may differ from your Rails version.

Integration

Auto-invoked by:

• All 7 Rails agents when they need conceptual information
• @rails-architect for architecture decisions
• User questions about "How do I..." or "What is..."

Complements:

• @rails-api-lookup (this skill = concepts, that skill = API details)
• @rails-pattern-finder (this skill = theory, that skill = code examples)

Special Features

Multi-topic search

@rails-docs-search topic="routing,controllers"
→ Fetches both guides and combines relevant sections

Keyword search within topic

@rails-docs-search topic="active_record_associations" keyword="polymorphic"
→ Focuses on polymorphic association sections only

List available topics

@rails-docs-search list
→ Returns all available topics from reference.md

Testing

Test cases:

1. Topic="routing" + Rails 7.1 → Fetches v7.1 routing guide
2. Topic="unknown" → Returns error with suggestions
3. Network down → Graceful fallback
4. Rails 8.0 (future) → Uses latest available version
5. Multiple topics → Combines results

Notes

• Guides content fetched live (not stored in plugin)
• Reference mappings maintained in reference.md
• Version-appropriate URLs ensure accuracy
• WebFetch tool handles HTML → Markdown conversion
• This skill focuses on concepts, use @rails-api-lookup for API signatures