Skill Discovery Patterns

Overview

The Rails Enterprise Dev plugin is generic and reusable across all Rails projects. It automatically discovers and uses skills from your project's .claude/skills/ directory, adapting its behavior to whatever patterns and knowledge are available.

Discovery Process

1. Automatic Skill Scanning

At workflow start, the plugin scans .claude/skills/ to find available skills:

Plugin executes skill discovery

bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/discover-skills.sh

Categorizes skills by naming patterns:

- core_rails: rails-conventions, rails-error-prevention

- data_layer: activerecord-patterns, model, database

- service_layer: service-object-patterns, api-development-patterns

- async: sidekiq-async-patterns, job, async

- ui: viewcomponents-specialist, hotwire-patterns, tailadmin-patterns

- i18n: localization, translation

- testing: rspec-testing-patterns, spec, test

- domain: Any skill not matching known patterns

2. Skill Inventory Storage

Discovered skills are stored in settings file for quick access:

.claude/rails-enterprise-dev.local.md

available_skills: core: - rails-conventions - rails-error-prevention - codebase-inspection data: - activerecord-patterns service: - service-object-patterns - api-development-patterns ui: - viewcomponents-specialist - hotwire-patterns - tailadmin-patterns domain: - manifest-project-context # Auto-detected!

3. Dynamic Skill Invocation

Throughout the workflow, agents check for and use available skills:

Example: Database Implementation Phase

1. Check skill inventory: activerecord-patterns available? YES
2. Invoke skill: "I need guidance from activerecord-patterns skill for implementing User model"
3. Extract patterns: N+1 prevention, association patterns, validation strategies
4. Delegate to Data Lead agent with skill context
5. Validate implementation against skill best practices

Skill Categories

Core Rails Skills (Universal)

Purpose: Fundamental Rails patterns applicable to all projects

Skills:

• rails-conventions

• MVC architecture, naming conventions, file organization

• rails-error-prevention

• Common pitfalls, preventive checklists

• codebase-inspection

• Pre-implementation analysis procedures

When Used: All workflows (inspection, planning, validation)

Example Invocation:

Before planning, invoke rails-conventions skill to understand:

• Service object patterns in this project
• Controller organization
• Testing conventions

Data Layer Skills

Purpose: Database schema, models, queries, associations

Skills:

• activerecord-patterns

• Query optimization, associations, scopes

• Custom: model , database , schema

When Used: Database migration and model implementation phases

Example Invocation:

For User authentication model, invoke activerecord-patterns:

• How to prevent N+1 queries
• Association patterns for has_many :through
• Scope best practices
• Validation strategies

Service Layer Skills

Purpose: Business logic, API design, service objects

Skills:

• service-object-patterns

• Service layer architecture

• api-development-patterns

• RESTful API, serialization

• Custom: service , api

When Used: Service and controller implementation phases

Example Invocation:

For payment processing service, invoke service-object-patterns:

• Callable concern usage
• Namespace patterns ({Domain}Manager::{Action})
• Error handling strategies
• Transaction management

Async Skills

Purpose: Background jobs, queues, schedulers

Skills:

• sidekiq-async-patterns

• Background job design

• Custom: job , async , queue

When Used: Background job implementation phase

Example Invocation:

For invoice generation job, invoke sidekiq-async-patterns:

• Job idempotency patterns
• Retry strategies
• Queue priority configuration
• Scheduled job patterns

UI Skills

Purpose: Components, views, frontend frameworks

Skills:

• viewcomponents-specialist

• ViewComponent architecture

• hotwire-patterns

• Turbo Frames, Streams, Stimulus

• tailadmin-patterns

• TailAdmin UI framework

• Custom: component , view , ui , frontend

When Used: Component and view implementation phases

Example Invocation:

For user profile component, invoke:

1. viewcomponents-specialist - Component structure, method exposure
2. tailadmin-patterns - UI styling, color schemes, card layouts
3. hotwire-patterns - Real-time updates with Turbo Streams

Extract:

• TailAdmin card patterns (bg-blue-50, rounded corners)
• ViewComponent slots for customization
• Stimulus controller for interactions

I18n Skills

Purpose: Internationalization, localization, translations

Skills:

• localization

• Multi-language support, RTL, pluralization

• Custom: i18n , translation

When Used: Localization implementation phase

Example Invocation:

For Arabic translation support, invoke localization:

• YAML structure for translations
• RTL CSS patterns
• Locale switcher component
• Date/time formatting
• Pluralization rules

Testing Skills

Purpose: Test strategies, specs, coverage

Skills:

• rspec-testing-patterns

• Unit, integration, system tests

• Custom: spec , test

When Used: Test implementation phase

Example Invocation:

For comprehensive test suite, invoke rspec-testing-patterns:

• Factory patterns
• Shared examples
• Request spec structure
• System test patterns
• Mocking strategies

Domain Skills (Project-Specific)

Purpose: Business domain knowledge, project-specific context

Skills: Any skill not matching known patterns

• manifest-project-context

• Manifest LMS domain knowledge

• ecommerce-domain

• E-commerce business logic

• healthcare-domain

• Healthcare compliance, HIPAA

• Custom project domains

When Used: Inspection and planning phases (optional context)

Example Invocation:

For shipment tracking feature, invoke manifest-project-context:

• Understanding Task model (shipments)
• Bundle concept (delivery routes)
• Carrier relationships
• State machine flows
• Locality/Zone geography

Graceful Degradation

If a skill is not available, the plugin continues with agent's general knowledge:

Example: Project Without tailadmin-patterns

User: /rails-dev add dashboard

Workflow:

1. Check for tailadmin-patterns skill → NOT FOUND
2. Check for custom UI skill → NOT FOUND
3. Log: "No UI framework skill found, using general Rails view patterns"
4. Proceed with standard Rails ERB views
5. Suggest: "Consider adding tailadmin-patterns skill for consistent UI"

No workflow failure - plugin adapts to available skills.

Custom Skill Integration

Adding Project-Specific Skills

• Create skill directory:

mkdir -p .claude/skills/my-custom-skill

• Add SKILL.md with patterns:

name: My Custom Patterns description: Our team's coding standards

My Custom Patterns

Service Layer

• Always use dry-transaction gem

• Include CustomLogging concern ...

• Plugin auto-discovers on next run:

/rails-dev add feature

Plugin scans .claude/skills/

Finds: rails-conventions, activerecord-patterns, my-custom-skill

Uses my-custom-skill during implementation

Naming Conventions for Auto-Categorization

Data layer skills:

• activerecord-*

• -model-

• -database-

• -schema-

Service layer skills:

• service-*

• -service-

• api-*

• -api-

UI skills:

• -component

• -view

• -ui-

• -frontend-

• hotwire-*

• turbo-*

• stimulus-*

Domain skills (anything else):

• *-domain

• *-context

• -business-

• Project-specific names

Multi-Project Example

Project A: Manifest LMS (Full Stack)

.claude/skills/ ├── rails-conventions/ ├── rails-error-prevention/ ├── codebase-inspection/ ├── activerecord-patterns/ ├── service-object-patterns/ ├── api-development-patterns/ ├── sidekiq-async-patterns/ ├── viewcomponents-specialist/ ├── hotwire-patterns/ ├── tailadmin-patterns/ ← TailAdmin UI ├── localization/ ├── rspec-testing-patterns/ ├── devops-lead/ ├── requirements-writing/ └── manifest-project-context/ ← Domain specific

Plugin adapts: Full feature set with all skills

Project B: Simple API (Minimal)

.claude/skills/ ├── rails-conventions/ ├── activerecord-patterns/ ├── service-object-patterns/ ├── api-development-patterns/ └── rspec-testing-patterns/

Plugin adapts: API-focused workflow, no UI skills used

Project C: Different UI Framework

.claude/skills/ ├── rails-conventions/ ├── activerecord-patterns/ ├── bootstrap-patterns/ ← Bootstrap instead of TailAdmin └── jquery-patterns/ ← jQuery instead of Hotwire

Plugin adapts: Uses bootstrap-patterns and jquery-patterns for UI

Skill Invocation Protocol

Format for Agent Skill Requests

I need guidance from the [skill-name] skill for [specific task].

Context:

• Feature: User authentication
• Component: JWT service
• Phase: Service implementation

Questions:

• What service pattern should I follow?
• How to handle token refresh?
• Where to store refresh tokens?

This will inform Backend Lead agent when implementing AuthManager::GenerateToken service.

Skill Response Integration

Based on [skill-name] skill guidance:

Patterns to follow:

1. Use Callable concern (from service-object-patterns)
2. Namespace: AuthManager (from project conventions)
3. Return Result object (from service-object-patterns)

Implementation requirements:

• JWT expiry: 15 minutes (access), 7 days (refresh)
• Store refresh tokens in encrypted database column
• Invalidate on logout

Passing this to Backend Lead for implementation.

Workflow Integration

Phase-Specific Skill Usage

Inspection Phase:

Skills invoked:

• codebase-inspection (mandatory if available)
• rails-conventions (understand patterns)
• domain skills (business context)

Purpose: Understand existing codebase before planning

Planning Phase:

Skills invoked:

• rails-error-prevention (preventive checklist)
• rails-conventions (pattern selection)
• requirements-writing (if user stories needed)
• domain skills (business rules)
• phase-specific skills (api, ui, async based on feature type)

Purpose: Create implementation plan with skill-informed decisions

Implementation Phase:

Skills invoked per layer:

• Database: activerecord-patterns, domain skills
• Models: activerecord-patterns, domain skills
• Services: service-object-patterns, api-development-patterns
• Jobs: sidekiq-async-patterns
• Components: viewcomponents-specialist, ui framework skills
• Views: ui framework skills, hotwire-patterns, localization
• Tests: rspec-testing-patterns

Purpose: Ensure each layer follows established patterns

Review Phase:

Skills invoked:

• rails-error-prevention (validation checklist)
• All used implementation skills (verify adherence)

Purpose: Validate implementation against skill guidelines

Benefits of Skill Discovery

• Portability: Same plugin works across all Rails projects

• Flexibility: Adapts to available skills and patterns

• Extensibility: Easy to add project-specific knowledge

• Consistency: All implementations reference same skills

• Knowledge Capture: Skills document team conventions

• Onboarding: New developers reference skills

• Quality: Consistent patterns across codebase

Troubleshooting

Skill Not Found

Symptom: Plugin says "Skill not available: my-skill"

Solution:

• Check skill exists in .claude/skills/my-skill/

• Ensure SKILL.md file present

• Restart Claude Code

• Re-run skill discovery: bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/discover-skills.sh

Skill Not Categorized Correctly

Symptom: Domain skill categorized as UI skill

Solution:

• Rename skill to match category patterns

• Or: Accept categorization (doesn't affect functionality)

• Plugin still invokes skill based on content, not category

Multiple Domain Skills

Symptom: Project has multiple domain skills

Solution:

• Plugin invokes all domain skills during inspection/planning

• Agents synthesize information from all domain skills

• This is normal for large/complex projects

Summary

The skill discovery system makes the Rails Enterprise Dev plugin:

• Generic: Works with any Rails project

• Adaptive: Uses whatever skills available

• Extensible: Easy to add custom patterns

• Resilient: Graceful degradation if skills missing

• Maintainable: Skills separate from plugin code

Key principle: Plugin provides workflow orchestration, skills provide project-specific knowledge.