rails_skills 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 178573c6ee15fecc50390d962b0497fe63f76caa23a763105bb02cf2bd035742
+  data.tar.gz: 38fe007e723b016ea6ba499681baa7e76b2cdadbe59d8221697e60cd3719c31b
+SHA512:
+  metadata.gz: 58f7d7ea5fd40d5467f11182985ccecd43395f0a2e31aad41894d9a955088ef8c577e93568be38667a2a08e7f66f59bfea57995ad7fcb6a6993f90d7e3e46ad6
+  data.tar.gz: 1303af0ddab82bb8c0eae537997ca52b5ecf945bc1df025f23da37bf027d774826591249a0c7164bd61cdbe3ba088d23a454c17e7ce9036f430bd84ce1d9a97a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergii Mostovyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# RailsSkills
+
+A Ruby gem that organizes AI skills for Rails projects, shared between **Claude** and **Codex**.
+
+RailsSkills creates a `skills/` directory in your Rails root as the canonical location for AI skill definitions, then symlinks it into `.claude/skills` and `.codex/skills` so both AI assistants share the same knowledge base.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rails_skills"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Install with default (basic) preset
+
+```bash
+rails generate rails_skills:install
+```
+
+### Install with a preset
+
+```bash
+rails generate rails_skills:install --preset=basic
+rails generate rails_skills:install --preset=fullstack
+rails generate rails_skills:install --preset=api
+```
+
+### What it creates
+
+```
+your_rails_app/
+├── skills/                    # Shared AI skill files (canonical location)
+│   ├── rails-models/
+│   │   └── SKILL.md
+│   ├── rails-controllers/
+│   │   └── SKILL.md
+│   └── rails-views/
+│       └── SKILL.md
+├── .claude/
+│   ├── skills -> ../skills    # Symlink to shared skills
+│   ├── agents/
+│   ├── commands/
+│   ├── rules/
+│   └── settings.local.json
+└── .codex/
+    └── skills -> ../skills    # Symlink to shared skills
+```
+
+Both Claude and Codex read from the same `skills/` directory via symlinks.
+
+### Presets
+
+| Preset | Skills included |
+|--------|----------------|
+| **basic** | rails-models, rails-controllers, rails-views |
+| **fullstack** | basic + rails-hotwire, rspec-testing |
+| **api** | rails-models, rails-api-controllers, rspec-testing |
+
+### Create a custom skill
+
+```bash
+rails generate rails_skills:skill my_custom_skill
+rails generate rails_skills:skill my_custom_skill --description="My skill description"
+rails generate rails_skills:skill my_custom_skill --with-references
+```
+
+Skills are created in `skills/` and automatically available to both Claude and Codex.
+
+## Skill Library
+
+The gem ships with these pre-built skills:
+
+- **rails-models** - ActiveRecord patterns, migrations, validations, associations
+- **rails-controllers** - Controller actions, routing, REST conventions, filters
+- **rails-views** - ERB templates, layouts, partials, forms, helpers
+- **rails-hotwire** - Turbo Drive, Turbo Frames, Turbo Streams, Stimulus
+- **rails-api-controllers** - API-only controllers, serialization, versioning
+- **rspec-testing** - RSpec patterns for models, requests, and system tests
+- **rails-jobs** - Active Job patterns, background processing
+
+## How It Works
+
+1. `skills/` is the single source of truth for AI skill files
+2. `.claude/skills` is a symlink pointing to `../skills`
+3. `.codex/skills` is a symlink pointing to `../skills`
+4. Edit skills in `skills/` and both AI tools see the changes immediately
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+task default: :spec

data/lib/generators/rails_skills/commands_library/quality.md

@@ -0,0 +1,16 @@
+---
+description: Run code quality checks
+allowed-tools: Bash, Read
+---
+
+## Quality Check
+
+Run the following quality checks on the project and report results:
+
+1. **Linting**: Run `bundle exec rubocop` and report any violations
+2. **Tests**: Run `bundle exec rspec` and report failures
+3. **Security**: Run `bundle exec brakeman --no-pager` if available
+
+Summarize findings and suggest fixes for any issues found.
+
+Use $ARGUMENTS to scope the check (e.g., a specific file or directory).

data/lib/generators/rails_skills/install/install_generator.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsSkills
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :preset, type: :string, default: "basic",
+                            desc: "Preset bundle (basic, fullstack, api)"
+      class_option :skip_agents, type: :boolean, default: false,
+                                 desc: "Don't create default agents"
+
+      def create_skills_directory
+        empty_directory "skills"
+      end
+
+      def create_claude_directory
+        empty_directory ".claude"
+        empty_directory ".claude/commands"
+        empty_directory ".claude/rules"
+        empty_directory ".claude/agents" unless options[:skip_agents]
+      end
+
+      def create_codex_directory
+        empty_directory ".codex"
+      end
+
+      def create_symlinks
+        create_symlink(".claude/skills", "../skills")
+        create_symlink(".codex/skills", "../skills")
+      end
+
+      def copy_claude_settings
+        template "settings.local.json.tt", ".claude/settings.local.json"
+      end
+
+      def install_preset_skills
+        case options[:preset]
+        when "fullstack"
+          install_fullstack_preset
+        when "api"
+          install_api_preset
+        else
+          install_basic_preset
+        end
+      end
+
+      def show_instructions
+        say ""
+        say "RailsSkills installed successfully!", :green
+        say ""
+        say "Directory structure:", :yellow
+        say "  skills/           <- shared AI skill files (canonical location)"
+        say "  .claude/skills    -> ../skills (symlink)"
+        say "  .codex/skills     -> ../skills (symlink)"
+        say ""
+        say "Both Claude and Codex now share the same skills from skills/", :blue
+        say ""
+        say "Next steps:", :yellow
+        say "  rails g rails_skills:skill my_skill   # Create a custom skill"
+        say ""
+      end
+
+      private
+
+      def create_symlink(link_path, target)
+        dest = File.join(destination_root, link_path)
+        if File.symlink?(dest) || File.exist?(dest)
+          say_status :exist, link_path, :blue
+        else
+          File.symlink(target, dest)
+          say_status :symlink, "#{link_path} -> #{target}", :green
+        end
+      end
+
+      def install_basic_preset
+        say "Installing basic preset...", :green
+        install_skill("rails-models")
+        install_skill("rails-controllers")
+        install_skill("rails-views")
+        install_rule("code-style")
+        install_rule("testing")
+        install_command("quality")
+        create_basic_agent unless options[:skip_agents]
+      end
+
+      def install_fullstack_preset
+        say "Installing fullstack preset...", :green
+        install_skill("rails-models")
+        install_skill("rails-controllers")
+        install_skill("rails-views")
+        install_skill("rails-hotwire")
+        install_skill("rspec-testing")
+        install_rule("code-style")
+        install_rule("testing")
+        install_rule("security")
+        install_command("quality")
+        create_fullstack_agent unless options[:skip_agents]
+      end
+
+      def install_api_preset
+        say "Installing API preset...", :green
+        install_skill("rails-models")
+        install_skill("rails-api-controllers")
+        install_skill("rspec-testing")
+        install_rule("code-style")
+        install_rule("testing")
+        install_rule("security")
+        install_command("quality")
+        create_api_agent unless options[:skip_agents]
+      end
+
+      def install_skill(skill_name)
+        skill_dir = "skills/#{skill_name}"
+        empty_directory skill_dir
+
+        skill_source = File.expand_path("../skills_library/#{skill_name}", __dir__)
+        if File.directory?(skill_source)
+          directory skill_source, skill_dir
+        else
+          create_file "#{skill_dir}/SKILL.md", default_skill_content(skill_name)
+        end
+      end
+
+      def install_rule(rule_name)
+        rule_file = ".claude/rules/#{rule_name}.md"
+        rule_source = File.expand_path("../rules_library/#{rule_name}.md", __dir__)
+
+        if File.exist?(rule_source)
+          copy_file rule_source, rule_file
+        else
+          create_file rule_file, default_rule_content(rule_name)
+        end
+      end
+
+      def install_command(command_name)
+        command_file = ".claude/commands/#{command_name}.md"
+        command_source = File.expand_path("../commands_library/#{command_name}.md", __dir__)
+
+        if File.exist?(command_source)
+          copy_file command_source, command_file
+        else
+          create_file command_file, default_command_content(command_name)
+        end
+      end
+
+      def create_basic_agent
+        template "agents/rails-developer.md.tt", ".claude/agents/rails-developer.md"
+      end
+
+      def create_fullstack_agent
+        template "agents/fullstack-dev.md.tt", ".claude/agents/fullstack-dev.md"
+      end
+
+      def create_api_agent
+        template "agents/api-dev.md.tt", ".claude/agents/api-dev.md"
+      end
+
+      def default_skill_content(skill_name)
+        <<~SKILL
+          ---
+          name: #{skill_name}
+          description: #{skill_name.tr('-', ' ').capitalize} skill
+          version: 1.0.0
+          ---
+
+          # #{skill_name.tr('-', ' ').capitalize}
+
+          Add your skill content here.
+        SKILL
+      end
+
+      def default_rule_content(rule_name)
+        <<~RULE
+          # #{rule_name.tr('-', ' ').capitalize} Rules
+
+          Add your project rules and guidelines here.
+        RULE
+      end
+
+      def default_command_content(command_name)
+        <<~COMMAND
+          ---
+          description: #{command_name.tr('-', ' ').capitalize} command
+          allowed-tools: Bash, Read, Edit, Write
+          ---
+
+          ## #{command_name.tr('-', ' ').capitalize}
+
+          Add your command instructions here.
+
+          Use $ARGUMENTS to reference command arguments.
+        COMMAND
+      end
+
+      def app_name
+        Rails.application.class.module_parent_name
+      rescue StandardError
+        "MyApp"
+      end
+
+      def rails_version
+        Rails::VERSION::STRING
+      rescue StandardError
+        "7.0"
+      end
+    end
+  end
+end

data/lib/generators/rails_skills/install/templates/agents/api-dev.md.tt

@@ -0,0 +1,28 @@
+# API Developer Agent
+
+You are an API-focused Rails developer working on **<%= app_name %>** (Rails <%= rails_version %>).
+
+## Skills
+
+Load and follow all skills from the `skills/` directory, with emphasis on:
+- Rails models
+- API controllers
+- RSpec testing
+
+## Guidelines
+
+- Build RESTful JSON APIs
+- Use proper HTTP status codes
+- Implement authentication and authorization
+- Write comprehensive API tests
+- Document endpoints clearly
+- Follow JSON:API or similar conventions
+
+## Workflow
+
+1. Understand the API requirement
+2. Design the endpoint (HTTP method, path, request/response format)
+3. Start with the model and migrations
+4. Build the API controller
+5. Write request specs
+6. Document the endpoint

data/lib/generators/rails_skills/install/templates/agents/fullstack-dev.md.tt

@@ -0,0 +1,28 @@
+# Fullstack Developer Agent
+
+You are a fullstack Rails developer working on **<%= app_name %>** (Rails <%= rails_version %>).
+
+## Skills
+
+Load and follow all skills from the `skills/` directory, with emphasis on:
+- Rails models, controllers, and views
+- Hotwire (Turbo + Stimulus)
+- RSpec testing
+
+## Guidelines
+
+- Follow Rails conventions and best practices
+- Build reactive UIs with Turbo Frames and Turbo Streams
+- Use Stimulus for JavaScript behavior
+- Write comprehensive RSpec tests
+- Use the project's existing patterns and style
+
+## Workflow
+
+1. Understand the requirement
+2. Plan the full-stack implementation (model, controller, views)
+3. Start with the model and migrations
+4. Build the controller with proper actions
+5. Create views with Hotwire integration
+6. Write RSpec tests for all layers
+7. Verify everything works end-to-end

data/lib/generators/rails_skills/install/templates/agents/rails-developer.md.tt

@@ -0,0 +1,22 @@
+# Rails Developer Agent
+
+You are a Rails developer working on **<%= app_name %>** (Rails <%= rails_version %>).
+
+## Skills
+
+Load and follow all skills from the `skills/` directory.
+
+## Guidelines
+
+- Follow Rails conventions and best practices
+- Write clean, tested code
+- Use the project's existing patterns and style
+- Prefer simple solutions over clever ones
+
+## Workflow
+
+1. Understand the requirement
+2. Check existing code for patterns
+3. Implement following Rails conventions
+4. Write tests
+5. Verify everything works

data/lib/generators/rails_skills/install/templates/settings.local.json.tt

@@ -0,0 +1,11 @@
+{
+  "skills": {
+    "autoLoad": true,
+    "path": ".claude/skills"
+  },
+  "agents": {
+    "path": ".claude/agents"
+  },
+  "project": "<%= app_name %>",
+  "rails_version": "<%= rails_version %>"
+}

data/lib/generators/rails_skills/rules_library/code-style.md

@@ -0,0 +1,28 @@
+# Code Style Rules
+
+## Ruby Style
+
+- Use 2 spaces for indentation (not tabs)
+- Prefer double quotes for strings
+- Use modern Ruby syntax (Ruby 3.0+)
+- Prefer `&.` safe navigation over conditional checks
+- Use trailing commas in multi-line arrays and hashes
+
+## Rails Conventions
+
+- Follow RESTful routing patterns
+- Keep controllers thin, models focused
+- Use `before_action` for shared controller setup
+- Use strong parameters for mass assignment protection
+- Prefer ActiveRecord query methods over raw SQL
+
+## Naming
+
+- snake_case for variables, methods, and file names
+- PascalCase for classes and modules
+- Prefix boolean methods with `?` (e.g., `published?`)
+- Prefix destructive methods with `!` (e.g., `publish!`)
+
+## Auto-Fixing
+
+Run `bundle exec rubocop -a` to fix style violations before committing.

data/lib/generators/rails_skills/rules_library/security.md

@@ -0,0 +1,33 @@
+# Security Rules
+
+## Input Handling
+
+- Always use strong parameters in controllers
+- Never trust user input - validate and sanitize
+- Use parameterized queries (ActiveRecord handles this by default)
+- Never interpolate user input into SQL strings
+
+## Authentication
+
+- Use established libraries (Devise, etc.) for authentication
+- Store passwords with bcrypt (`has_secure_password`)
+- Use CSRF protection (enabled by default in Rails)
+- Implement proper session management
+
+## Authorization
+
+- Check permissions in every controller action
+- Use authorization libraries (Pundit, CanCanCan) for complex rules
+- Never rely on hiding UI elements as a security measure
+
+## Output
+
+- ERB auto-escapes output by default - don't bypass with `raw` or `html_safe` unless necessary
+- Sanitize HTML content with `sanitize` helper
+- Set proper Content Security Policy headers
+
+## Secrets
+
+- Never commit secrets, API keys, or credentials to git
+- Use Rails credentials (`rails credentials:edit`) or environment variables
+- Add sensitive files to `.gitignore`

data/lib/generators/rails_skills/rules_library/testing.md

@@ -0,0 +1,27 @@
+# Testing Rules
+
+## General
+
+- Every feature must have tests
+- Test behavior, not implementation details
+- Keep tests fast and independent
+- Use factories (FactoryBot) over fixtures
+
+## Test Types
+
+- **Model specs** for validations, associations, and business logic
+- **Request specs** for controller actions and API endpoints
+- **System specs** for user-facing workflows (use sparingly)
+
+## Conventions
+
+- One assertion per test when practical
+- Use `let` for lazy setup, `let!` when eager evaluation is needed
+- Use `describe` for the subject, `context` for conditions, `it` for behavior
+- Name tests clearly: `it "returns published posts for active users"`
+
+## Running Tests
+
+- `bundle exec rspec` to run all tests
+- `bundle exec rspec spec/models/` to run model specs
+- `bundle exec rspec spec/file.rb:42` to run a specific test

data/lib/generators/rails_skills/skill/skill_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsSkills
+  module Generators
+    class SkillGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :description, type: :string, default: nil,
+                                 desc: "Skill description"
+      class_option :with_references, type: :boolean, default: false,
+                                     desc: "Create references directory"
+
+      def create_skill_directory
+        empty_directory skill_path
+      end
+
+      def create_skill_file
+        template "SKILL.md.tt", "#{skill_path}/SKILL.md"
+      end
+
+      def create_references_directory
+        return unless options[:with_references]
+
+        empty_directory "#{skill_path}/references"
+        create_file "#{skill_path}/references/.keep", ""
+      end
+
+      def show_instructions
+        say "\nSkill '#{file_name}' created in #{skill_path}/", :green
+        say "This skill is available to both Claude and Codex via symlinks.", :blue
+      end
+
+      private
+
+      def skill_path
+        "skills/#{file_name}"
+      end
+
+      def skill_description
+        options[:description] || "Custom skill for #{file_name.tr('-', ' ')}"
+      end
+    end
+  end
+end

data/lib/generators/rails_skills/skill/templates/SKILL.md.tt

@@ -0,0 +1,29 @@
+---
+name: <%= file_name %>
+description: <%= skill_description %>
+version: 1.0.0
+---
+
+# <%= file_name.tr('-', ' ').split.map(&:capitalize).join(' ') %>
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| TODO    | Add commands here |
+
+## Overview
+
+<%= skill_description %>
+
+## Usage
+
+Add usage examples and patterns here.
+
+## Common Patterns
+
+Add frequently used code patterns here.
+
+## Best Practices
+
+Add best practices and conventions here.