rspec-best-practices
Use when writing, reviewing, or cleaning up RSpec tests for Ruby and Rails codebases. Covers spec type selection, factory design, flaky test fixes, shared examples, deterministic assertions, test-driven development discipline, and choosing the best first failing spec for Rails changes. Also applies when choosing between model, request, system, and job specs.
88
85%
Does it follow best practices?
Impact
91%
1.49xAverage score across 3 eval scenarios
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly defines its scope (RSpec testing in Ruby/Rails), lists specific concrete capabilities, and opens with an explicit 'Use when...' clause. It uses third person voice appropriately and includes excellent trigger terms that developers would naturally use. The description is concise yet comprehensive, covering both the what and when effectively.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: spec type selection, factory design, flaky test fixes, shared examples, deterministic assertions, TDD discipline, and choosing the best first failing spec. These are all concrete, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers both what (spec type selection, factory design, flaky test fixes, shared examples, deterministic assertions, TDD discipline) and when ('Use when writing, reviewing, or cleaning up RSpec tests for Ruby and Rails codebases'). The 'Use when...' clause is explicit and upfront. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'RSpec', 'Ruby', 'Rails', 'spec', 'factory', 'flaky test', 'shared examples', 'model spec', 'request spec', 'system spec', 'job spec', 'test-driven development'. These are all terms a developer would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: RSpec testing specifically for Ruby/Rails. The mention of specific spec types (model, request, system, job), factories, and shared examples makes it very unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured skill with excellent workflow clarity and progressive disclosure—the TDD gate workflow with explicit checkpoints is a standout strength, and the integration table cleanly points to related skills. However, it suffers from some redundancy across sections (TDD principles are restated in multiple places) and critically lacks executable RSpec code examples despite being a skill about writing RSpec tests. Adding 2-3 complete, copy-paste-ready spec examples would significantly improve its actionability.
Suggestions
Add 2-3 complete, executable RSpec examples (e.g., a minimal request spec, a model spec with factory, a shared_example usage) to demonstrate the patterns described in prose.
Consolidate overlapping content between HARD-GATE, Rails-First TDD Loop, Common Mistakes, and Red Flags sections—several points (e.g., 'code before test', 'delete means delete', 'start at the boundary') are repeated 3+ times across these sections.
Trim motivational/persuasive language in Common Mistakes table (e.g., 'TDD IS pragmatic' and 'later never comes') which reads as advocacy rather than actionable instruction for Claude.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly well-organized with tables and clear sections, but it's verbose in places—particularly the HARD-GATE section which belabors the 'delete means delete' point repeatedly, the Common Mistakes table includes motivational statements Claude doesn't need, and several rules are restated across multiple sections (e.g., TDD workflow appears in HARD-GATE, Rails-First TDD Loop, and Red Flags). The 'Common Mistakes' and 'Red Flags' sections have significant overlap. | 2 / 3 |
Actionability | The skill provides clear procedural guidance (TDD workflow steps, spec type selection tables, verification checklist) but lacks executable code examples. The only code shown is a good vs bad test description snippet—there are no complete, copy-paste-ready spec examples demonstrating factory usage, request specs, shared examples, or any of the other patterns discussed. For a skill about writing RSpec tests, concrete spec examples would significantly improve actionability. | 2 / 3 |
Workflow Clarity | The multi-step TDD workflow is clearly sequenced with explicit validation checkpoints (run test, validate failure, checkpoint for test design review, checkpoint for implementation proposal, run again, refactor). The HARD-GATE section and Rails-First TDD Loop both provide clear sequences with feedback loops for error recovery. The verification checklist serves as a final validation step. | 3 / 3 |
Progressive Disclosure | The skill is well-structured with a quick reference table up front, followed by progressively detailed sections. It appropriately references related skills (rails-tdd-slices, rails-engine-testing, rspec-service-testing, etc.) with clear 'when to chain' guidance in the Integration table, keeping references one level deep and well-signaled. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- igmarin/rails-agent-skills
- Commit
ae8ea63
- 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.