From rails-toolkit
Use FIRST on any Ruby on Rails work — the project owner's hard-won Rails gotchas and non-negotiable rules (fixtures, migrations, Stimulus LSP, validation, gems, test suite). Read before writing or changing Rails code.
How this skill is triggered — by the user, by Claude, or both
Slash command
/rails-toolkit:rails-coreThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The entry-point skill for Rails work in this environment. These are personal, hard-won rules that override generic Rails habits. Read this first, then pull in the specific `rails-toolkit:rails-*` skill for the area you're touching.
The entry-point skill for Rails work in this environment. These are personal, hard-won rules that override generic Rails habits. Read this first, then pull in the specific rails-toolkit:rails-* skill for the area you're touching.
Do not modify existing fixtures or add new relationships to them — that silently breaks other tests. If no existing fixture fits what you're testing, create a new one. See [[rails-testing]] for fixture patterns and deterministic UUIDs.
After you add or rename a Stimulus controller, the Stimulus LSP does not refresh until a restart, so it may report a controller as "not a valid Stimulus controller" even though it exists. Ignore these false errors — don't chase them. See [[rails-stimulus]].
Always prefer server-side validation with Hotwire and Turbo over client-side JavaScript validation. Let the model be the source of truth and re-render with Turbo. See [[rails-turbo]] and [[rails-models]].
When a newly-added gem or package is involved, read its actual API/docs rather than relying on memory — APIs drift between versions.
For tables that already have rows, never add a non-nullable or unique column in a single migration. Use the multi-step pattern:
db:rollback needs the namespaced taskIn an app configured with multiple databases (e.g. primary / queue / cache), a bare
bin/rails db:rollback aborts with "you must run the namespaced task". Target the database
explicitly: bin/rails db:rollback:primary STEP=n (and likewise for the other migration tasks
that operate per-database). See [[rails-models]].
A running dev server reads the DB schema once at boot. After a migration that adds
columns — especially an enum-backed column — the already-running process keeps 500ing
(Undeclared attribute type for enum ... must be backed by a database column) until it is
restarted. This is not a code bug; restart after migrating.
How you restart depends on the server: Puma hot-restarts via SIGUSR2, not
touch tmp/restart.txt (that's a Passenger-only trick and does nothing under Puma). Sending
SIGUSR2 makes Puma re-exec in place keeping the same PID, so a foreman/bin/dev dev group
doesn't see a child die and tear everything down (Vite and friends keep running). Everyday app
code (models, controllers, views) auto-reloads and needs no restart — only boot-time state
does (initializers, config/*, Gemfile, env vars, new/enum-backed columns).
A drop-in bin/restart-web wrapper (adjust the pgrep pattern to your app's Puma process tag):
#!/usr/bin/env sh
# Hot-restart the running Puma dev server in place (SIGUSR2).
#
# Puma re-execs itself on SIGUSR2, keeping the same PID, so foreman does not
# see a child die and tear down the whole dev group — Vite keeps running.
# Use this to reload boot-time state: config/initializers, config/*, Gemfile,
# env vars, and new/enum-backed DB columns. Everyday app code (models,
# controllers, views) is auto-reloaded and needs no restart.
#
# Note: this is NOT `touch tmp/restart.txt` — that only works with Passenger.
set -e
pid=$(pgrep -f 'puma .* \[YourApp\]' || true) # match your app's Puma process tag
if [ -z "$pid" ]; then
echo "No running Puma dev server found (is bin/dev running?)." >&2
exit 1
fi
echo "Hot-restarting Puma (pid $pid) via SIGUSR2..."
kill -USR2 "$pid"
echo "Done. Watch the bin/dev terminal for the restart log."
Factory and fixture changes have cascading effects across the entire suite. After any such change (or when optimizing/refactoring factories), run the full test suite — not just the files you touched. Use PARALLEL_WORKERS=1 when you need readable, debuggable output. See [[rails-testing]].
npx claudepluginhub mickzijdel/rails-toolkitProvides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.