CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

rails-conventions

RoleModel's Rails conventions where they differ from what an agent writes by default: flash wording, the status for failed saves, Simple Form for every form, how route concerns pass the parent type, and two gotchas (`params.expect` with nested attributes, and Lexxy rich-text change events). Use when writing or reviewing a Rails controller, route, form, or view in a RoleModel app. Also use when the user says things like "add a controller for", "build the form for", "add routes for", "add comments to", "why isn't my nested form saving", or "review this controller".

Quality

94%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

96%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An excellent, lean conventions document: every rule states the exact deviation from default Rails behavior with copy-paste-ready values, and both gotchas explain the silent failure mode rather than just the fix. The only defect is the two dangling references, which point to documents that are not present in the bundle and carry no resolvable path.

Suggestions

Give the two referenced documents resolvable paths (e.g., references/polymorphic-parent-resources.md, references/dynamic-forms.md) or ship them in the bundle — as written, neither `polymorphic-parent-resources` nor `dynamic-forms` exists in references/, scripts/, or assets/, so an agent told to "Read" them cannot find them.

DimensionReasoningScore

Conciseness

The body is lean and states only the delta from what an agent already does — "This skill only covers what an agent got wrong without it in baseline tests. Everything else is standard Rails 8 practice, which the agent already follows" — then gives exact values ('Successfully Created Widget', "render :new, status: :unprocessable_content, never :unprocessable_entity") with zero padding. It matches the 5 anchor (every token earns its place) rather than 4 because there is no over-explanation to trim; even the one justification sentence ("This one is a safety rule, kept even though the baseline tests didn't cover it") carries decision-relevant information.

5 / 5

Actionability

Nearly every rule is copy-paste ready: literal flash strings, the exact helper call "simple_form_for :search, url: widgets_path, method: :get", an executable route-concern code block, and both bracket forms ("parts_attributes: [[:id, :name, :_destroy]]" vs "parts_attributes: %i[id name _destroy]") showing correct vs broken. It fits the 5 anchor (specific examples cover the common cases); the only rule without a snippet (admin-only constraint for mounted engines) is a policy rule about something an agent already knows how to implement, so it is not a gap that drops it to 4.

5 / 5

Workflow Clarity

This is a single-purpose conventions skill (under 50 lines) applied at write/review time, so the simple-skill exception applies: each directive is unambiguous on its own, and what little sequencing exists is explicit ("Read `polymorphic-parent-resources` before writing that controller", "called only on collection actions"). No destructive or batch operations are involved, so the validation cap does not apply, and there are no missing checkpoints that would place it at 4.

5 / 5

Progressive Disclosure

The body is short and well-sectioned (Rules / Gotchas), and its two references are one level deep and clearly signaled with when-to-read conditions ("Read `polymorphic-parent-resources` before writing that controller", "Dynamic forms ... use the `turbo_form` gem. Read `dynamic-forms`"). However, both are bare names with no path or link, and neither exists in the bundle — there are no references/, scripts/, or assets/ directories — so navigation cannot be confirmed. It sits above the 3 anchor (references are clearly signaled, not buried, and the inline content is appropriately placed) but below the 5 anchor (easy navigation), because the references are unresolvable as shipped.

4 / 5

Total

19

/

20

Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description that explicitly answers both what and when: it itemizes the concrete convention areas it covers, scopes itself to RoleModel apps to avoid conflicts, and quotes natural user phrases as triggers. The only weakness is thin natural-term coverage on the view side, where no quoted user phrase or file extension appears.

Suggestions

Add one or two natural view-side trigger phrases (e.g., "add a view for", "update this template") so view work matches the controller/route/form trigger coverage.

Name one concrete artifact in the description itself (e.g., routes.rb or an .erb view) to catch file-oriented requests the current trigger list misses.

DimensionReasoningScore

Specificity

The description enumerates multiple concrete, specific items — "flash wording", "the status for failed saves", "Simple Form for every form", "how route concerns pass the parent type", plus two named gotchas ("`params.expect` with nested attributes", and "Lexxy rich-text change events") — giving comprehensive coverage of the skill's stated scope. It matches the 5 anchor rather than 4 because there are no coverage gaps within that scope; the items are concrete, not generic domain mentions.

5 / 5

Completeness

Both halves are explicit: the what is "RoleModel's Rails conventions where they differ from what an agent writes by default" with the itemized list, and the when is "Use when writing or reviewing a Rails controller, route, form, or view in a RoleModel app" followed by concrete quoted trigger phrases. This matches the 5 anchor exactly (clear what AND when with concrete trigger phrases); it is not 4 because the when-clause is already fully explicit, not merely present.

5 / 5

Trigger Term Quality

It includes good natural user-voice triggers — "add a controller for", "build the form for", "add routes for", "why isn't my nested form saving", "review this controller" — plus the artifact nouns "Rails controller, route, form, or view". It falls below the 5 anchor (comprehensive coverage including synonyms and file extensions) because view work has no natural quoted phrase (nothing like "add a view for" or "update this template") and the description itself names no files or extensions (routes.rb, .erb, simple_form_for appear only in metadata, not the description field); it is clearly above the 3 anchor because several natural phrases users would actually say are explicitly present.

4 / 5

Distinctiveness Conflict Risk

The description carves out a clear niche — conventions specific to "a RoleModel app" that differ from default agent output — with distinct triggers (Simple Form, Lexxy, params.expect, route concerns). Generic Rails or web-development skills would not fire on these triggers, so conflict risk is minimal, matching the 5 anchor.

5 / 5

Total

19

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

Total

15

/

16

Passed

Repository

RoleModel/rolemodel-skills

Path

skills/rails-conventions/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.