Initial commit
This commit is contained in:
Zhongwei Li
291
skills/rails-docs-search/SKILL.md
Normal file
291
skills/rails-docs-search/SKILL.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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
|
||||
```markdown
|
||||
## 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`:
|
||||
|
||||
```yaml
|
||||
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
|
||||
```markdown
|
||||
## 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
|
||||
```markdown
|
||||
## 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
|
||||
```markdown
|
||||
## 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**:
|
||||
```markdown
|
||||
⚠️ Failed to fetch guide from rubyonrails.org
|
||||
|
||||
Fallback: Check local knowledge or ask user for clarification.
|
||||
URL attempted: [URL]
|
||||
```
|
||||
|
||||
**Invalid topic**:
|
||||
```markdown
|
||||
❌ Unknown topic: "[topic]"
|
||||
|
||||
Did you mean: [closest match from reference.md]?
|
||||
|
||||
See available topics: @rails-docs-search list
|
||||
```
|
||||
|
||||
**Version not supported**:
|
||||
```markdown
|
||||
⚠️ 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**
|
||||
322
skills/rails-docs-search/reference.md
Normal file
322
skills/rails-docs-search/reference.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# Rails Guides Reference Mappings
|
||||
|
||||
**Purpose**: Maps topic names to official Rails Guides URLs
|
||||
|
||||
**Version**: 1.0.0 (supports Rails 6.1 - 8.0)
|
||||
|
||||
---
|
||||
|
||||
## Topic Mappings
|
||||
|
||||
### Getting Started
|
||||
```yaml
|
||||
getting_started:
|
||||
title: "Getting Started with Rails"
|
||||
url_path: "getting_started.html"
|
||||
version_support: "all"
|
||||
keywords: [tutorial, first app, setup, install]
|
||||
|
||||
initialization:
|
||||
title: "The Rails Initialization Process"
|
||||
url_path: "initialization.html"
|
||||
version_support: "all"
|
||||
keywords: [boot, startup, initialization]
|
||||
```
|
||||
|
||||
### Active Record
|
||||
|
||||
```yaml
|
||||
active_record_basics:
|
||||
title: "Active Record Basics"
|
||||
url_path: "active_record_basics.html"
|
||||
version_support: "all"
|
||||
keywords: [orm, models, database, CRUD]
|
||||
|
||||
active_record_migrations:
|
||||
title: "Active Record Migrations"
|
||||
url_path: "active_record_migrations.html"
|
||||
version_support: "all"
|
||||
keywords: [migrations, schema, database changes]
|
||||
|
||||
active_record_validations:
|
||||
title: "Active Record Validations"
|
||||
url_path: "active_record_validations.html"
|
||||
version_support: "all"
|
||||
keywords: [validation, validates, presence, format]
|
||||
|
||||
active_record_callbacks:
|
||||
title: "Active Record Callbacks"
|
||||
url_path: "active_record_callbacks.html"
|
||||
version_support: "all"
|
||||
keywords: [callbacks, before_save, after_create, lifecycle]
|
||||
|
||||
active_record_associations:
|
||||
title: "Active Record Associations"
|
||||
url_path: "association_basics.html"
|
||||
version_support: "all"
|
||||
keywords: [has_many, belongs_to, has_one, through, polymorphic]
|
||||
|
||||
active_record_querying:
|
||||
title: "Active Record Query Interface"
|
||||
url_path: "active_record_querying.html"
|
||||
version_support: "all"
|
||||
keywords: [query, where, joins, includes, eager loading]
|
||||
```
|
||||
|
||||
### Action Controller
|
||||
|
||||
```yaml
|
||||
action_controller_overview:
|
||||
title: "Action Controller Overview"
|
||||
url_path: "action_controller_overview.html"
|
||||
version_support: "all"
|
||||
keywords: [controllers, requests, responses, filters]
|
||||
|
||||
routing:
|
||||
title: "Rails Routing from the Outside In"
|
||||
url_path: "routing.html"
|
||||
version_support: "all"
|
||||
keywords: [routes, resources, namespace, scope, member, collection]
|
||||
```
|
||||
|
||||
### Action View
|
||||
|
||||
```yaml
|
||||
action_view_overview:
|
||||
title: "Action View Overview"
|
||||
url_path: "action_view_overview.html"
|
||||
version_support: "all"
|
||||
keywords: [views, templates, rendering, partials]
|
||||
|
||||
layouts_and_rendering:
|
||||
title: "Layouts and Rendering in Rails"
|
||||
url_path: "layouts_and_rendering.html"
|
||||
version_support: "all"
|
||||
keywords: [layouts, render, yield, content_for]
|
||||
|
||||
form_helpers:
|
||||
title: "Action View Form Helpers"
|
||||
url_path: "form_helpers.html"
|
||||
version_support: "all"
|
||||
keywords: [forms, form_with, form_for, input fields]
|
||||
```
|
||||
|
||||
### Action Mailer
|
||||
|
||||
```yaml
|
||||
action_mailer_basics:
|
||||
title: "Action Mailer Basics"
|
||||
url_path: "action_mailer_basics.html"
|
||||
version_support: "all"
|
||||
keywords: [email, mailer, deliver, smtp]
|
||||
```
|
||||
|
||||
### Action Cable
|
||||
|
||||
```yaml
|
||||
action_cable_overview:
|
||||
title: "Action Cable Overview"
|
||||
url_path: "action_cable_overview.html"
|
||||
version_support: "all"
|
||||
keywords: [websockets, channels, subscriptions, broadcasting]
|
||||
```
|
||||
|
||||
### Active Job
|
||||
|
||||
```yaml
|
||||
active_job_basics:
|
||||
title: "Active Job Basics"
|
||||
url_path: "active_job_basics.html"
|
||||
version_support: "all"
|
||||
keywords: [jobs, background, queues, sidekiq, delayed_job]
|
||||
```
|
||||
|
||||
### Active Storage
|
||||
|
||||
```yaml
|
||||
active_storage_overview:
|
||||
title: "Active Storage Overview"
|
||||
url_path: "active_storage_overview.html"
|
||||
version_support: "6.0+"
|
||||
keywords: [uploads, files, attachments, S3, cloud storage]
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```yaml
|
||||
testing:
|
||||
title: "Testing Rails Applications"
|
||||
url_path: "testing.html"
|
||||
version_support: "all"
|
||||
keywords: [tests, minitest, rspec, fixtures, factories]
|
||||
```
|
||||
|
||||
### Security
|
||||
|
||||
```yaml
|
||||
security:
|
||||
title: "Securing Rails Applications"
|
||||
url_path: "security.html"
|
||||
version_support: "all"
|
||||
keywords: [security, CSRF, XSS, SQL injection, authentication]
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
```yaml
|
||||
debugging_rails_applications:
|
||||
title: "Debugging Rails Applications"
|
||||
url_path: "debugging_rails_applications.html"
|
||||
version_support: "all"
|
||||
keywords: [debug, byebug, pry, logs, debugging]
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
```yaml
|
||||
configuring:
|
||||
title: "Configuring Rails Applications"
|
||||
url_path: "configuring.html"
|
||||
version_support: "all"
|
||||
keywords: [config, environment, settings, credentials]
|
||||
|
||||
rails_application_templates:
|
||||
title: "Rails Application Templates"
|
||||
url_path: "rails_application_templates.html"
|
||||
version_support: "all"
|
||||
keywords: [templates, generators, app templates]
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
```yaml
|
||||
caching_with_rails:
|
||||
title: "Caching with Rails"
|
||||
url_path: "caching_with_rails.html"
|
||||
version_support: "all"
|
||||
keywords: [cache, caching, fragment cache, low-level cache]
|
||||
|
||||
asset_pipeline:
|
||||
title: "The Asset Pipeline"
|
||||
url_path: "asset_pipeline.html"
|
||||
version_support: "all"
|
||||
keywords: [assets, sprockets, javascript, css, images]
|
||||
```
|
||||
|
||||
### Internationalization
|
||||
|
||||
```yaml
|
||||
i18n:
|
||||
title: "Rails Internationalization (I18n) API"
|
||||
url_path: "i18n.html"
|
||||
version_support: "all"
|
||||
keywords: [i18n, translations, locales, internationalization]
|
||||
```
|
||||
|
||||
### Action Mailbox
|
||||
|
||||
```yaml
|
||||
action_mailbox_basics:
|
||||
title: "Action Mailbox Basics"
|
||||
url_path: "action_mailbox_basics.html"
|
||||
version_support: "6.0+"
|
||||
keywords: [incoming email, mailbox, inbound email]
|
||||
```
|
||||
|
||||
### Action Text
|
||||
|
||||
```yaml
|
||||
action_text_overview:
|
||||
title: "Action Text Overview"
|
||||
url_path: "action_text_overview.html"
|
||||
version_support: "6.0+"
|
||||
keywords: [rich text, trix, wysiwyg, text editor]
|
||||
```
|
||||
|
||||
### Rails 7+ Specific
|
||||
|
||||
```yaml
|
||||
autoloading_and_reloading_constants:
|
||||
title: "Autoloading and Reloading Constants"
|
||||
url_path: "autoloading_and_reloading_constants.html"
|
||||
version_support: "all"
|
||||
keywords: [autoload, zeitwerk, eager loading]
|
||||
|
||||
engines:
|
||||
title: "Getting Started with Engines"
|
||||
url_path: "engines.html"
|
||||
version_support: "all"
|
||||
keywords: [engines, plugins, mountable]
|
||||
|
||||
api_app:
|
||||
title: "Using Rails for API-only Applications"
|
||||
url_path: "api_app.html"
|
||||
version_support: "5.0+"
|
||||
keywords: [api, json, api-only, rest]
|
||||
```
|
||||
|
||||
### Rails 8+ Specific
|
||||
|
||||
```yaml
|
||||
solid_cache:
|
||||
title: "Solid Cache"
|
||||
url_path: "solid_cache.html"
|
||||
version_support: "8.0+"
|
||||
keywords: [solid cache, caching, database cache]
|
||||
|
||||
solid_queue:
|
||||
title: "Solid Queue"
|
||||
url_path: "solid_queue.html"
|
||||
version_support: "8.0+"
|
||||
keywords: [solid queue, jobs, background jobs]
|
||||
|
||||
solid_cable:
|
||||
title: "Solid Cable"
|
||||
url_path: "solid_cable.html"
|
||||
version_support: "8.0+"
|
||||
keywords: [solid cable, websockets, action cable]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Support Legend
|
||||
|
||||
- `all` - Available in Rails 3.0+
|
||||
- `5.0+` - Available from Rails 5.0 onwards
|
||||
- `6.0+` - Available from Rails 6.0 onwards
|
||||
- `7.0+` - Available from Rails 7.0 onwards
|
||||
- `8.0+` - Available from Rails 8.0 onwards
|
||||
|
||||
## URL Construction
|
||||
|
||||
**Pattern**: `https://guides.rubyonrails.org/v{MAJOR.MINOR}/{url_path}`
|
||||
|
||||
**Examples**:
|
||||
- Rails 7.1: `https://guides.rubyonrails.org/v7.1/routing.html`
|
||||
- Rails 8.0: `https://guides.rubyonrails.org/v8.0/routing.html`
|
||||
- Latest: `https://guides.rubyonrails.org/routing.html` (edge)
|
||||
|
||||
## Usage in rails-docs-search
|
||||
|
||||
```ruby
|
||||
# Pseudocode for topic lookup
|
||||
topic = "active_record_associations"
|
||||
mapping = reference[topic]
|
||||
version = detect_rails_version() # e.g., "7.1"
|
||||
url = "https://guides.rubyonrails.org/v#{version}/#{mapping.url_path}"
|
||||
content = WebFetch(url, prompt: "Extract information about associations")
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
**Update frequency**: Quarterly or when new Rails version released
|
||||
|
||||
**Adding new topics**:
|
||||
1. Check official Rails Guides index
|
||||
2. Add mapping with all fields
|
||||
3. Test URL accessibility
|
||||
4. Update this file
|
||||
|
||||
**Version-specific topics**:
|
||||
- Mark with `version_support`
|
||||
- Skill should gracefully handle unavailable guides for older Rails versions
|
||||
Reference in New Issue
Block a user