Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

document-engine

Use when writing engine README, install, and configuration docs. Trigger words: engine README, install guide, engine docs.

igmarin · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add igmarin/rails-agent-skills --skill document-engine

About this skill


name: document-engine type: atomic license: MIT description: > Use when writing engine README, install, and configuration docs. Trigger words: engine README, install guide, engine docs. metadata: version: 1.0.0 user-invocable: "true"

Document Engine

Use this skill when writing or maintaining documentation for Rails engines.

Core Process & Constraints

StepSectionFocus
1Installationgem add, bundle, run install generator — show minimum working path first
2Host AssumptionsExplicitly state any host model, job backend, or auth integration assumptions
3ConfigurationAll options with defaults, required vs optional
4MountingExplicit mount MyEngine::Engine, at: '/path' in routes — show once only
5UsageCopyable code for typical workflows
6MigrationsInstall generator, one-time setup, upgrade-impacting changes

Hard gate: All generated documentation MUST satisfy steps 1, 2, and 3 above before proceeding to optional sections.

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

Extended Resources

See CHECKLIST.md for the full recommended README shape and documentation gap checklist. Critical gaps tracked there: installation steps, all config options with defaults, explicit mount path, migration timing, host model/auth assumptions.

  • assets/configuration.md — detailed config option catalog with type info, validation rules, and all supported defaults
  • assets/examples.md — realistic end-to-end usage examples covering common host-app integration workflows
  • assets/installation.md — step-by-step install and generator reference including post-install setup tasks

Output Style

  1. Keep sections short and task-oriented.
  2. Validate against CHECKLIST.md: a checklist item passes when the docs contain a corresponding section with at least one copyable code example or explicit prose statement; it fails when absent, incomplete, or lacking a concrete example. Fix each failing item, then re-run from the top. Do not finalize until all critical items pass.
  3. Section Delineation: Explicitly label mandatory "Hard-Gate" sections (Installation, Configuration, Host Assumptions) and "Optional" sections (Extension Points, Usage Examples).
  4. Upgrade Notes: Include at least one copyable code example in any Upgrade Notes section.
  5. Language — Must be in English unless explicitly requested otherwise.

Common pitfalls to avoid:

  • Duplicate mount MyEngine::Engine ... across multiple sections — show it only once in the primary installation/mounting section.
  • Syntax errors in Ruby/Rails code examples — double-check route mounting and authentication blocks (e.g., authenticate :user, ->(u) { u.admin? } do).

Integration

SkillWhen to chain
create-engineHost-app contract, structure, extension points to document
create-engine-installerInstall generators, setup steps to document
release-engineChangelog, upgrade notes, version documentation
generate-api-collectionWhen documenting or adding API endpoints (keep Postman collection in sync)