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

1. Create skill directory:

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

2. 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
...

3. 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

1. Portability: Same plugin works across all Rails projects
2. Flexibility: Adapts to available skills and patterns
3. Extensibility: Easy to add project-specific knowledge
4. Consistency: All implementations reference same skills
5. Knowledge Capture: Skills document team conventions
6. Onboarding: New developers reference skills
7. Quality: Consistent patterns across codebase

Troubleshooting

Skill Not Found

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

Solution:

1. Check skill exists in .claude/skills/my-skill/
2. Ensure SKILL.md file present
3. Restart Claude Code
4. 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:

1. Rename skill to match category patterns
2. Or: Accept categorization (doesn't affect functionality)
3. 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.