gh-nbarthel-claudy-plugins-rails-workflow/skills/rails-api-lookup/SKILL.md

Rails API Lookup

---

name: rails-api-lookup description: Looks up Rails API documentation for specific classes/methods using Ref (primary) or WebFetch (fallback) with API reference version: 1.2.0 author: Rails Workflow Team tags: [rails, api, documentation, reference, ref] priority: 3

Purpose

Fetches precise API documentation from official Rails API docs for specific classes, modules, and methods. Returns signatures, parameters, return values, and usage examples.

Replaces: mcp__rails__search_docs MCP tool (API-specific queries)

Usage

Auto-invoked when agents need API details:

Agent: "What parameters does validates :email accept?"
*invokes rails-api-lookup class="ActiveModel::Validations" method="validates"*

Manual invocation:

@rails-api-lookup class="ActiveRecord::Base" method="where"
@rails-api-lookup class="ActionController::Base"
@rails-api-lookup module="ActiveSupport::Concern"

Supported Lookups

See reference.md for complete class/module list. Common APIs:

Active Record

• ActiveRecord::Base - Model base class
• ActiveRecord::Relation - Query interface (where, joins, etc.)
• ActiveRecord::Associations - Association methods
• ActiveRecord::Validations - Validation methods
• ActiveRecord::Callbacks - Callback methods

Action Controller

• ActionController::Base - Controller base class
• ActionController::Metal - Minimal controller
• ActionController::API - API controller

Action View

• ActionView::Base - View rendering
• ActionView::Helpers - View helpers
• ActionView::Template - Template handling

Active Support

• ActiveSupport::Concern - Module mixins
• ActiveSupport::Callbacks - Callback framework
• ActiveSupport::TimeWithZone - Time handling

Search Process

Step 1: Version Detection

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

Step 2: Class/Method Mapping

Input: class="ActiveRecord::Base" method="where"
Lookup: reference.md → "ActiveRecord/QueryMethods.html#method-i-where"
URL: https://api.rubyonrails.org/v7.1/ActiveRecord/QueryMethods.html#method-i-where

Step 3: Content Fetch

Method 1: Context7 (Fastest):

Tool: context7_fetch
Query: "Rails [version] [class] [method] API"

Method 2: Ref (Token-Efficient):

Tool: ref_search_documentation
Query: "Rails [version] [class] [method] API documentation"
Then: ref_read_url

Method 3: Tavily (Search):

Tool: tavily_search
Query: "Rails [version] [class] [method] API documentation"

Method 4: WebFetch (Fallback):

Tool: WebFetch
URL: [constructed URL from reference.md]
Prompt: "Extract method signature, parameters, and examples for [method]"

Step 4: Response Formatting

## ActiveRecord::QueryMethods#where (v7.1)

**Signature**: `where(**opts)`

**Parameters**:
- `opts` (Hash) - Conditions as key-value pairs
- `opts` (String) - Raw SQL conditions
- `opts` (Array) - SQL with placeholders

**Returns**: `ActiveRecord::Relation`

**Examples**:
User.where(name: 'Alice')
User.where("age > ?", 18)
User.where(age: 18..65)

**Source**: https://api.rubyonrails.org/v7.1/ActiveRecord/QueryMethods.html#method-i-where

Reference Lookup

Class/Method → API URL mapping in reference.md:

ActiveRecord::Base:
  url_path: "ActiveRecord/Base.html"
  common_methods:
    - save: "method-i-save"
    - update: "method-i-update"
    - destroy: "method-i-destroy"

ActiveRecord::QueryMethods:
  url_path: "ActiveRecord/QueryMethods.html"
  common_methods:
    - where: "method-i-where"
    - joins: "method-i-joins"
    - includes: "method-i-includes"

Output Format

Class Overview

## ActiveRecord::Base (v7.1)

Active Record base class for all models.

**Inherits from**: Object
**Includes**: ActiveModel::Validations, ActiveRecord::Persistence

**Common Methods**:
- `.create` - Creates and saves record
- `#save` - Saves record to database
- `#update` - Updates attributes and saves
- `#destroy` - Deletes record from database

**Source**: https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html

Method Details

## ActiveRecord::Base#save (v7.1)

**Signature**: `save(options = {})`

**Parameters**:
- `validate` (Boolean, default: true) - Run validations before saving
- `context` (Symbol) - Validation context
- `touch` (Boolean, default: true) - Update timestamps

**Returns**:
- `true` if saved successfully
- `false` if validation failed

**Raises**:
- `ActiveRecord::RecordInvalid` if `save!` and validation fails

**Examples**:
```ruby
user.save                    # => true/false
user.save(validate: false)   # skip validations
user.save!                   # raises on failure

Source: [full URL]

### Not Found Response
```markdown
## Class/Method Not Found: [class]#[method]

Searched in: Rails [version] API docs

Suggestions:
- Check spelling: "ActiveRecord::Base" (not "ActiveRecords::Base")
- Try class overview: @rails-api-lookup class="ActiveRecord::Base"
- Search guides instead: @rails-docs-search topic="active_record_basics"

Common classes:
- ActiveRecord::Base
- ActionController::Base
- ActiveSupport::Concern

Implementation Details

Tools used (in order of preference):

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

Optional dependencies:

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

URL construction:

Base: https://api.rubyonrails.org/
Versioned: https://api.rubyonrails.org/v7.1/
Class: https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html
Method: https://api.rubyonrails.org/v7.1/ActiveRecord/Base.html#method-i-save

Version handling:

• Rails 8.x → /v8.0/
• Rails 7.1.x → /v7.1/
• Rails 7.0.x → /v7.0/
• Rails 6.1.x → /v6.1/

Caching strategy:

• Cache API documentation for session
• Re-fetch if version changes
• Cache key: {class}:{method}:{version}

Prompt Caching (Opus 4.5 Optimized):

• Use 1-hour cache duration for extended thinking tasks
• API signatures rarely change - maximize cache reuse
• Cache prefix: Include Rails version + common class list in system prompt
• Reduces token costs significantly for repeated API lookups

Error Handling

Network failure:

⚠️ Failed to fetch API docs from api.rubyonrails.org

Fallback: Use Claude's knowledge (may be less accurate)
URL attempted: [URL]

Invalid class name:

❌ Unknown class: "[class]"

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

Tip: Use full module path (e.g., "ActiveRecord::Base", not "Base")

Method not found:

⚠️ Method "[method]" not found in [class]

Class exists, but method not documented or name incorrect.

Available methods in [class]:
- [method1]
- [method2]
[...from reference.md...]

Integration

Auto-invoked by:

• All 7 Rails agents when they need precise API signatures
• @rails-model-specialist for ActiveRecord methods
• @rails-controller-specialist for ActionController methods
• @rails-view-specialist for ActionView helpers

Complements:

• @rails-docs-search (concepts vs API details)
• @rails-pattern-finder (API usage vs code patterns)

Special Features

Multiple methods lookup

@rails-api-lookup class="ActiveRecord::Base" method="save,update,destroy"
→ Returns all three method signatures

Inheritance chain

@rails-api-lookup class="User" inherit=true
→ Shows methods from User, ApplicationRecord, ActiveRecord::Base

Version comparison

@rails-api-lookup class="ActiveRecord::Base" method="save" compare="7.0,7.1"
→ Shows differences between versions

Testing

Test cases:

1. class="ActiveRecord::Base" method="save" → Exact signature
2. class="UnknownClass" → Error with suggestions
3. Network down → Graceful fallback
4. Rails 8.0 method lookup → Uses v8.0 docs
5. Method with multiple signatures → Lists all variants

Notes

• API docs fetched live (not stored in plugin)
• Reference mappings maintained in reference.md
• Version-appropriate URLs ensure API accuracy
• WebFetch tool handles HTML parsing
• This skill focuses on API signatures, use @rails-docs-search for concepts
• Method anchors use Rails convention: #method-i-name (instance), #method-c-name (class)