A Claude Code skill that generates comprehensive technical debt audits for Ruby and Rails applications.
This skill automates the process of running multiple code quality and security tools, then compiles the results into a single, self-contained HTML report. It analyzes:
- Security Vulnerabilities: bundler-audit, Brakeman, bundler-leak, Trivy
- Dependency Freshness: next_rails, libyear-bundler
- Code Coverage: SimpleCov
- Code Complexity: RubyCritic
- Combined Metrics: Skunk (churn + complexity + coverage)
- Runtime Observability: exception tracking (Sentry, Honeybadger, Rollbar, etc.) and performance monitoring (New Relic, Scout, Skylight, rack-mini-profiler); flags their absence as a best-practice gap
- Framework Health & Stats: Rails/Ruby versions and rails_stats (codebase metrics plus dependency weight via its bundled bundle-stats)
- Development Environment: CI setup, documentation
Every run produces one self-contained index.html that you can open in any browser or share as a single file. It includes:
- An executive summary at the top, synthesized from every tool's output, with a color-coded 100-point health score (red under 50, yellow 50-74, green 75-100)
- A section for each tool with the real numbers pulled from its output
- Visuals — screenshots of the RubyCritic overview (churn vs. complexity) embedded as base64
- The top 3 recommended actions at the end, targeting the highest-priority issues
- Styled with the FastRuby.io styleguide palette and Oxygen font, mobile and tablet friendly, with a link to each open source tool in its section
All output from a run is stored in one timestamped directory so you can keep baselines and compare over time:
tech-debt-audit-YYYYMMDD-HHMMSS/
├── index.html <- the single self-contained report
├── raw/ <- raw text/JSON output from every tool
├── rubycritic/ <- RubyCritic's generated HTML report
└── screenshots/ <- PNG screenshots embedded into index.html
From your Rails project directory, run:
mkdir -p .claude/skills
git clone https://github.com/fastruby/tech-debt-skill.git .claude/skills/tech-debt-auditOnce installed, run the audit with:
claude /tech-debt-auditOr specify a directory:
claude /tech-debt-audit ./path/to/projectThe skill generates a single self-contained index.html (inside the timestamped directory) with:
| Category | Score | Status |
|---|---|---|
| Security | X/20 | Pass/Warning/Fail |
| Dependencies | X/20 | Pass/Warning/Fail |
| Coverage | X/20 | Pass/Warning/Fail |
| Complexity | X/20 | Pass/Warning/Fail |
| Maintainability | X/20 | Pass/Warning/Fail |
Lists all CVEs from bundler-audit organized by severity, plus Brakeman warnings.
Identifies files with high technical debt (high complexity + low coverage + high churn):
| File | SkunkScore | Churn | Coverage |
|---|---|---|---|
| lib/complex_file.rb | 833.04 | 11 | 0% |
Actionable recommendations organized by priority (Critical, High, Medium, Low).
The skill will automatically install these tools if they're not present:
- bundler-audit - Security vulnerability scanner
- brakeman - Static security analyzer for Rails
- bundler-leak - Memory leak detector
- trivy - Filesystem scanner for vulnerable dependencies, leaked secrets, and misconfigurations
- next_rails - Outdated dependency reporter
- libyear-bundler - Dependency freshness calculator
- rubycritic - Code quality reporter
- skunk - Technical debt calculator
- rails_stats - Codebase statistics (used instead of
rake stats); it bundles bundle-stats and reports dependency weight (transitive dependencies per gem) in the same run
To embed the RubyCritic overview chart in the HTML report, the skill renders it with headless Chrome (Google Chrome, google-chrome, or chromium). If no browser is available, the skill skips the screenshots and notes it in the report; everything else still works.
The skill runs your test suite with COVERAGE=true before running Skunk. This is required for accurate SkunkScore calculations.
If you have RSpec:
COVERAGE=true bundle exec rspecIf you have Minitest:
COVERAGE=true bundle exec rake testMake sure your project has SimpleCov configured to generate coverage data.
- 20: No vulnerabilities
- 15: Low severity only
- 10: Some medium severity
- 5: High severity issues
- 0: Critical vulnerabilities
- 20: <10% outdated, <5 libyears
- 15: <20% outdated, <15 libyears
- 10: <40% outdated, <30 libyears
- 5: <60% outdated, <50 libyears
- 0: >60% outdated or >50 libyears
- 20: >90% coverage
- 15: 70-90% coverage
- 10: 50-70% coverage
- 5: 30-50% coverage
- 0: <30% coverage
- 20: No files with complexity >10
- 15: Few files with complexity 11-20
- 10: Some files with complexity 21-50
- 5: Many files with high complexity
- 0: Files with complexity >50
- 20: Excellent setup, CI, documentation
- 15: Good setup with minor gaps
- 10: Adequate but needs improvement
- 5: Significant maintainability issues
- 0: Major maintainability problems
The skill is defined in markdown, making it easy to customize:
- Add new tools or checks
- Modify scoring thresholds
- Change the report format
- Add JavaScript analysis (npm audit, upjs-plato)
- Introducing Skunk: Combine Code Quality and Coverage
- How to Use bundler-audit to Keep Dependencies Secure
- Ruby Dependency Freshness
- Churn vs Complexity vs Coverage
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE for details.
This skill was created by FastRuby.io, a team specializing in Rails upgrades and technical debt remediation.
Need help with your Rails application? Contact us for a tech debt assessment!