igmarin/rails-engine-docs
rails-engine-docs/SKILL.md
Use when writing or maintaining documentation for Rails engines. Generates README templates, writes installation and configuration guides, documents mount points, extension APIs, and migration notes for host-app adoption. Trigger words: engine README, installation guide, configuration docs, mount instructions, migration notes, extension points, host integration examples, setup documentation.
$ install --global
skillsauthnpx skillsauth add igmarin/rails-agent-skills rails-engine-docsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 30, 2026, 4:46 PM13.9s1 file scanned
SKILL.md
- name:
- rails-engine-docs
- license:
- MIT
- description:
- >
- extension APIs, and migration notes for host-app adoption. Trigger words:
- engine
Rails Engine Docs
Use this skill when the task is to write or improve documentation for a Rails engine.
Engine docs should optimize for host-app adoption. Readers need to know what the engine does, how to install it, how to configure it, and where the boundaries are. All generated documentation (README, guides, examples) must be in English unless the user explicitly requests another language.
Recommended README Shape
- Purpose — what the engine does and when to use it
- Installation — gem add, bundle, run install generator
- Mounting — explicit
mount MyEngine::Engine, at: '/path'in routes - Configuration — all options with defaults, required vs optional
- Usage examples — copyable code for typical workflows
- Migrations / operational steps — install generator, one-time setup
- Extension points — adapters, callbacks, config blocks
- Development and testing — how to run tests or contribute
Documentation Rules
- Document required host-app steps before optional customization.
- Keep examples copyable and close to real code.
- Show the minimum working install path first.
- If the engine assumes any host model, job backend, or auth integration, say so explicitly.
- Document upgrade-impacting changes when setup evolves.
Documentation Gaps to Check
See CHECKLIST.md for the full gap checklist. Critical gaps: installation steps, all config options with defaults, explicit mount path, migration timing, host model/auth assumptions.
Examples
README snippet (install + mount):
## Installation
Add to your Gemfile:
gem 'my_engine'
Run:
bundle install
rails generate my_engine:install
This creates `config/initializers/my_engine.rb`. Mount the engine in `config/routes.rb`:
mount MyEngine::Engine, at: '/admin'
Configuration section:
## Configuration
In `config/initializers/my_engine.rb`:
MyEngine.configure do |config|
config.user_class = "User" # required: host model for current user
config.widget_count = 10 # optional, default 10
end
Output Style
When asked to write docs:
- Start with the minimum install path.
- Show one realistic configuration example.
- Document operational steps explicitly.
- Keep sections short and task-oriented.
- Check each row in the Documentation Gaps checklist — if any is missing, fill it and re-check before finalizing.
Integration
| Skill | When to chain | |-------|----------------| | rails-engine-author | Host-app contract, structure, extension points to document | | rails-engine-installers | Install generators, setup steps to document | | rails-engine-release | Changelog, upgrade notes, version documentation | | api-rest-collection | When documenting or adding API endpoints (keep Postman collection in sync) |
Assets
- assets/configuration.md
- assets/examples.md
- assets/installation.md
Related Skills
igmarin/rails-agent-skills
development
VerifiedTrustedCommunity
Entry point for Rails development workflows covering TDD, RSpec, Service Objects, DDD, GraphQL, Engines, and Code Quality. Use when the user asks about Ruby on Rails development patterns, needs RSpec test suites generated, wants service objects scaffolded, is setting up GraphQL schemas, performing Rails code review, refactoring .rb files, working with domain-driven design, implementing background jobs, conducting Rails security checks, or building Rails engines. Generates RSpec tests, structures service objects, enforces TDD workflows, configures GraphQL schemas, and coordinates domain-driven design patterns. Trigger keywords: Rails, RSpec, TDD, Rails testing, Rails refactor, Rails API, Rails code review, domain driven design, service objects, GraphQL, Rails engine, Ruby, .rb, background jobs, Rails migrations, Rails security check.
21SKILL.mdUpdated May 18, 2026
igmarin/release-engine
development
VerifiedTrustedCommunity
Use when shipping a Rails engine gem — FIRST run full test suite (`bundle exec rspec`) and fix ALL failures, verify gemspec metadata and dependencies match tested Rails/Ruby versions, dry-run: `gem build *.gemspec && gem push --dry-run *.gem` and verify contents, generate CHANGELOG.md organized by category (added/changed/deprecated/removed/fixed), produce step-by-step upgrade notes with before/after code, set semantic version in `lib/[engine_name]/version.rb`, document deprecations with migration paths, load release assets conditionally and state which one informed the output. Trigger words: version bump, changelog, deprecation, gemspec, upgrade, release, publish gem, ship gem.
21SKILL.mdUpdated May 9, 2026
igmarin/tdd
development
VerifiedTrustedCommunity
Orchestrates the full Rails TDD cycle with hard gates: test MUST exist, be run, and FAIL for the correct reason (e.g. undefined method, not syntax error) before any implementation code — propose minimal implementation and wait for user approval → verify test PASSES → run full suite with rubocop, brakeman, rspec all green → produce YARD documentation and self-reviewed PR; phases context/test design→implementation→iterate→finish. Use when practicing test-driven development, red-green-refactor, TDD workflow, writing tests before code, adding tests first, or building a Rails feature where specs must gate implementation.
19SKILL.mdUpdated Jun 5, 2026
igmarin/setup
development
VerifiedTrustedCommunity
Complete Rails project setup loop with hard gates: verify Ruby version matches .ruby-version, Bundler installed, database connection successful, all env vars loaded, and ALL external CI actions pinned to immutable commit SHAs (never mutable tags like @v4) → configure CI/CD pipeline with linting, testing, and security scanning → validate end-to-end with bundle install, db:create, db:migrate, rspec, and write SETUP_CHECKLIST.md; phases context/onboarding→CI/CD configuration→environment validation. Use when starting a new Rails project, running `rails new`, configuring a Gemfile or .ruby-version, setting up a development environment, or wiring up CI/CD for a Ruby on Rails app. Trigger: setup project, new Rails app, configure CI/CD, dev environment setup, rails new, Gemfile setup, .ruby-version, Ruby on Rails project bootstrap.
19SKILL.mdUpdated Jun 5, 2026