
Use when writing, reviewing, or debugging pure Ruby code — idiomatic patterns, modern 3.x+ features (pattern matching, Data.define, endless methods), error handling conventions (raise vs fail, result objects), memoization, and performance idioms. For Rails use rails-guides. For testing use minitest. For code style use sandi-metz-rules.
Official Rails documentation. Use when asked about any Rails-specific topic including ActiveRecord, routing, controllers, views, mailers, jobs, Action Cable, Action Text, Active Storage, migrations, validations, callbacks, associations, caching, security, or internals.
Use when viewing available handoff documents — lists active and archived handoffs with their status, date, topic, and branch
Use when starting a new session and wanting to continue from a previous handoff — reads the latest unrestored handoff document and restores session context
--- name: ruby-upgrade description: Use when upgrading the Ruby interpreter version of a Bundler/Rails app — especially "upgrade to Ruby 4", "bump Ruby to 4.0", "audit Ruby 4 compatibility", "what breaks on Ruby 4", or a specific target like "Ruby 4.0.5". Triggers on Ruby-major risk symptoms: CGI.parse/CGI::Cookie removal, Net::HTTP implicit Content-Type dropped, demoted default gems (ostruct/logger/benchmark/irb), SortedSet, Set#inspect changes, native-extension recompile crashes, openssl 4 pin
Use when capturing session state before switching context, ending a session, or manually preserving progress — creates a structured handoff document in docs/handoffs/ so a future session can resume seamlessly
Use when creating new skills, editing existing skills, or verifying skills work before deployment
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
Use when you have a spec or requirements for a multi-step task, before touching code
Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
Use when executing implementation plans with independent tasks in the current session
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Use when a problem has just been solved and verified working — the fix is fresh, the investigation is in recent history, and the solution is non-trivial enough to capture for future reference
Use when docs/solutions/ learnings may be stale — after refactors, migrations, or dependency upgrades, when a retrieved learning feels outdated or contradicts a recently solved problem, when pattern docs no longer reflect current code, or when reviewing docs/solutions/ for accuracy.
Use when stuck after multiple debug attempts and want to escalate to a stronger one-shot model (GPT-5 Pro, Opus, Gemini Pro) — packages a self-contained "oracle prompt" with Ruby/Rails project briefing, verbatim error, what-was-tried, constraints, and just-enough attached files. Triggers include "ask the oracle", "write a letter to GPT-5", "I'm stuck, draft a prompt for another model", "/tmp/letter.md".
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
Use when creating a git worktree for a Rails project that uses SQLite - copies the main working tree's development SQLite databases (including Rails 8 Solid Queue/Cache/Cable) into the worktree's storage/ directory with proper WAL checkpointing, so the new worktree has real dev data without re-seeding or re-migrating
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
Handle Hotwire form workflows: form submission lifecycle, inline editing, validation errors, typeahead/autocomplete, modal forms, and external form controls. Prefer this skill when the core problem is correctness and UX of form interaction. Use hwc-navigation-content for pagination/tabs/filter navigation, hwc-realtime-streaming for WebSocket/Turbo Stream broadcasting, hwc-media-content for image/video/audio behavior, hwc-ux-feedback for generic loading/transition polish, and hwc-stimulus-fundamentals for framework-level Stimulus APIs not tied to forms.
Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
Implement cross-cutting Hotwire UX feedback patterns: loading states, busy indicators, progress bars, optimistic UI, render interception, and view/page transitions. Prefer this skill when the core goal is perceived performance and user feedback, independent of a single feature domain. Use hwc-forms-validation for form correctness and validation behavior, hwc-navigation-content for navigation/history/cache mechanics, hwc-realtime-streaming for push/stream orchestration, hwc-media-content for media-specific behavior, and hwc-stimulus-fundamentals for base Stimulus API questions.
Implement real-time Hotwire behavior: Turbo Streams over WebSocket/SSE, custom stream actions, inline stream tags, live list updates, and cross-tab state synchronization. Prefer this skill when the core problem is push-based updates or stream action orchestration. Use hwc-navigation-content for pull-based pagination/tab/lazy-navigation flows, hwc-forms-validation for form lifecycle and validation, hwc-media-content for media upload/playback behavior, hwc-ux-feedback for generic loading/progress/transitions, and hwc-stimulus-fundamentals for non-stream Stimulus fundamentals.
Use when upgrading a Rails application from one version to another, assessing upgrade readiness, planning a multi-hop upgrade path, or investigating breaking changes, deprecation warnings, gem compatibility issues, or config.load_defaults transitions between any Rails versions from 5.2 through the latest release.
Use when committing code changes in Ruby or Ruby on Rails projects — guides commit message structure, type selection, and body content following Conventional Commits format
This skill should be used when users request code review, refactoring, or code quality improvements for Ruby codebases. Apply Sandi Metz's four rules for writing maintainable object-oriented code - classes under 100 lines, methods under 5 lines, no more than 4 parameters, and controllers instantiate only one object. Use when users mention "Sandi Metz", "code quality", "refactoring", or when reviewing Ruby code for maintainability.
Build Hotwire navigation and content-discovery flows: Turbo Frame pagination, tabbed navigation, lazy loading, faceted filtering/search, cache lifecycle, scroll restoration, and visit/render control. Prefer this skill when the core problem is request/response navigation state and browser history behavior. Use hwc-forms-validation for form validation and inline edit flows, hwc-realtime-streaming for WebSocket/Turbo Stream push updates, hwc-media-content for image/video/audio features, hwc-ux-feedback for generic loading/progress/transition polish, and hwc-stimulus-fundamentals for Stimulus APIs not centered on navigation.
Cover Stimulus controller fundamentals: lifecycle hooks, values and valueChanged callbacks, targets and target callbacks, outlets, action parameters, keyboard events, and controller architecture patterns. Prefer this skill when the request is primarily about Stimulus APIs and controller design independent of a specific Hotwire domain. Use hwc-forms-validation for form-specific workflows, hwc-navigation-content for Turbo navigation concerns, hwc-realtime-streaming for Turbo Streams/WebSocket patterns, hwc-media-content for media integrations, and hwc-ux-feedback for loading/progress/transition UX patterns.
Rails coding patterns derived from analysis of 37signals' Fizzy codebase. Use when writing Rails code in 37signals/Basecamp style or when asked to follow 37signals patterns. Covers controllers, models, views, Hotwire, testing, database, security, and team philosophy.
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Static analysis security vulnerability scanner for Ruby on Rails applications. Use when analyzing Rails code for security issues, running security audits, reviewing code for vulnerabilities, setting up security scanning in CI/CD, managing security warnings, or investigating specific vulnerability types (SQL injection, XSS, command injection, etc.). Also use when configuring Brakeman, reducing false positives, or integrating with automated workflows.
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
Handle media-heavy Hotwire features: image/video/audio uploads, previews, playback controls, progress tracking, and third-party media integrations (for example WaveSurfer, Swiper, Picture-in-Picture, Blurhash). Prefer this skill when the core problem is media rendering, playback state, or media library integration. Use hwc-realtime-streaming for server-pushed Turbo Stream updates, hwc-navigation-content for non-media pagination/tab/lazy-navigation flows, hwc-forms-validation for form validation and inline-edit behavior, hwc-ux-feedback for generic loading/transition patterns, and hwc-stimulus-fundamentals for Stimulus primitives not specific to media.
Use when implementing any feature or bugfix, before writing implementation code
Write GitHub Pull Request descriptions from branch commits. Use when user asks to write a PR description, create a PR summary, or document changes for a pull request. Analyzes git commits and diffs to produce structured PR documentation.
Generate high-quality git commit messages following Conventional Commits and Chris Beams' Seven Rules. Infers WHY from context and provides clear guidance on structure, scope, and body content.
Produces practical, risk-based testing guidance and minimal test plans for features or changes. Use when user asks what to test, how to pick test cases (boundaries, permissions, state machines), how to improve weak tests, or to review existing tests. Covers equivalence partitions, boundary values, decision tables, and state transitions.