acardozzo/doc-rx
skills/doc-rx/SKILL.md
Evaluates documentation quality and developer experience across 8 dimensions and 32 sub-metrics. Assesses whether someone new can understand, onboard, and contribute to a project. Covers README, API docs, code docs, ADRs, onboarding, changelog, tutorials, and error messages. Produces a scored report with actionable recommendations.
development
Updated Mar 26, 2026
$ install --global
skillsauthnpx skillsauth add acardozzo/rx-suite doc-rxInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
70%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 7, 2026, 2:00 PM211.7s1 file scanned
SKILL.md
- name:
- doc-rx
- description:
- >
Prerequisites
None (POSIX only)
Check all dependencies: bash scripts/rx-deps.sh or bash scripts/rx-deps.sh --install
doc-rx — Documentation & Developer Experience Audit
Purpose
A world-class project is not just well-built — it is well-documented. This skill evaluates if someone new can understand, onboard, and contribute to a codebase by auditing documentation quality across 8 dimensions.
Triggers
Activate this skill when the user says any of the following:
- "run doc-rx"
- "documentation audit"
- "evaluate docs"
- "onboarding review"
- "DX check"
- "developer experience"
Execution
- Run
scripts/discover.shfrom the project root to collect raw signals. - Score each of the 32 sub-metrics using the thresholds in
references/grading-framework.md. - Produce output following the templates in
references/output-templates.md.
Dimensions & Sub-Metrics (32 total)
D1: README & Project Overview (15%)
Source: GitHub Open Source Guide, Make a README
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M1.1 | Quick start | Setup in < 5 commands, works first try | | M1.2 | Architecture overview | High-level diagram, module descriptions | | M1.3 | Prerequisites listed | Runtime, tools, env vars, services | | M1.4 | Badges & status | Build status, coverage, version, license |
D2: API Documentation (15%)
Source: Divio Documentation System, Stripe Docs model
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M2.1 | OpenAPI/Swagger spec | Complete, up-to-date, published | | M2.2 | Endpoint documentation | All endpoints, request/response examples | | M2.3 | Authentication guide | Step-by-step, code examples per language | | M2.4 | Error code catalog | All error codes documented with fix suggestions |
D3: Code Documentation (10%)
Source: JSDoc/TSDoc standards, Clean Code (Robert C. Martin)
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M3.1 | Public API documentation | Exported functions/types have JSDoc/TSDoc | | M3.2 | Complex logic comments | Non-obvious code has explanatory comments | | M3.3 | Type documentation | Interfaces/types have description fields | | M3.4 | Example usage | Code examples in doc comments for key functions |
D4: Architecture Decision Records (15%)
Source: Michael Nygard ADR format, adr-tools
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M4.1 | ADR practice | Numbered decisions, stored in docs/adr/ | | M4.2 | ADR completeness | Context, decision, consequences documented | | M4.3 | ADR currency | Recent decisions recorded, not just historical | | M4.4 | ADR discoverability | Indexed, searchable, linked from README |
D5: Onboarding & Contributing (15%)
Source: InnerSource Patterns, GitHub Contributing Guide
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M5.1 | CONTRIBUTING.md | PR process, code style, review expectations | | M5.2 | Dev setup automation | Dev containers, docker-compose, scripts | | M5.3 | First-contribution guide | good-first-issue labels, mentoring process | | M5.4 | Code review guidelines | What reviewers look for, turnaround SLA |
D6: Changelog & Versioning (10%)
Source: Keep a Changelog, Semantic Versioning
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M6.1 | Changelog maintenance | CHANGELOG.md, updated per release | | M6.2 | Conventional commits | Commit messages follow convention | | M6.3 | Semantic versioning | Major/minor/patch correctly applied | | M6.4 | Release notes | Human-readable, highlights breaking changes |
D7: Tutorials & Guides (10%)
Source: Divio Documentation System (tutorials vs how-to vs reference)
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M7.1 | Tutorial exists | Step-by-step for common use cases | | M7.2 | How-to guides | Task-oriented, problem-solving | | M7.3 | Explanation docs | Conceptual, why decisions were made | | M7.4 | Reference docs | Complete, auto-generated where possible |
D8: Error Messages & User-Facing Text (10%)
Source: Write the Docs, Nielsen Error Heuristic
| ID | Sub-Metric | What to Look For | |------|---------------------------|-------------------------------------------------------| | M8.1 | Error message quality | Actionable, includes fix hint, no stack traces to users | | M8.2 | CLI/terminal UX | Help text, colored output, progress indicators | | M8.3 | Log message quality | Structured, includes context, not cryptic | | M8.4 | User-facing copy | Consistent tone, no jargon, i18n-ready |
Scoring
Each sub-metric is scored 0-5. Dimension scores are the average of their sub-metrics multiplied by the dimension weight. The final score is the sum of all weighted dimension scores, yielding a value between 0 and 100.
| Grade | Score Range | Meaning | |-------|-------------|--------------------------------------------| | A+ | 95-100 | Exemplary — sets the standard | | A | 85-94 | Excellent — minor gaps only | | B | 70-84 | Good — clear areas to improve | | C | 55-69 | Fair — significant documentation debt | | D | 40-54 | Poor — onboarding is painful | | F | 0-39 | Failing — docs are missing or misleading |
Auto-Plan Integration
After generating the scorecard and saving the report to docs/audits/:
- Save a copy of the report to
docs/rx-plans/{this-skill-name}/{date}-report.md - For each dimension scoring below 97, invoke the
rx-planskill to create or update the improvement plan atdocs/rx-plans/{this-skill-name}/{dimension}/v{N}-{date}-plan.md - Update
docs/rx-plans/{this-skill-name}/summary.mdwith current scores - Update
docs/rx-plans/dashboard.mdwith overall progress
This happens automatically — the user does not need to run /rx-plan separately.
Related Skills
acardozzo/ux-rx
development
VerifiedTrustedCommunity
Prescriptive UX/UI evaluation producing scored opportunity maps for Next.js + shadcn/ui projects. Evaluates user experience against Nielsen Heuristics, WCAG 2.2, Core Web Vitals, Laws of UX, and Atomic Design. Use when: auditing UX quality, evaluating accessibility, reviewing component usage, identifying missing shadcn components, improving form UX, or when the user says "ux audit", "run ux-rx", "evaluate UX", "accessibility check", "improve user experience", "shadcn review", "how to reach A+ UX", or "UX opportunities". Measures 11 dimensions (44 sub-metrics). Fixed stack: Next.js App Router + shadcn/ui + Tailwind CSS. Leverages shadcn registry to recommend ready-to-use components. Outputs per-page scorecards with before/after Mermaid diagrams.
SKILL.mdUpdated Mar 26, 2026
acardozzo/test-rx
development
VerifiedTrustedCommunity
Evaluates testing strategy and completeness across 8 dimensions (32 sub-metrics): test pyramid balance, test effectiveness, contract/API testing, UI/visual testing, performance/load testing, test data management, CI integration, and test organization. Produces a scored diagnostic with actionable improvement plans.
SKILL.mdUpdated Mar 26, 2026
acardozzo/sec-rx
development
VerifiedTrustedCommunity
Code-level security posture evaluation. Scans for OWASP Top 10 vulnerabilities, authentication flaws, injection vectors, authorization gaps, and data protection issues. Complements arch-rx D9 (architectural security) by inspecting actual source code patterns, dependencies, and security configurations. Produces a scored report across 8 dimensions with 32 sub-metrics mapped to OWASP ASVS and CWE references.
SKILL.mdUpdated Mar 26, 2026
acardozzo/rx-plan
testing
VerifiedTrustedCommunity
Generates versioned improvement plans from rx report results. Creates one plan per dimension that scores below A+ (97). Plans are saved to docs/rx-plans/{domain}/{dimension}/v{N}-{date}-plan.md. Use after running any rx skill, or when the user says "create plan from report", "rx plan", "plan improvements", "generate improvement plan", "what should I fix first", "create roadmap", "improvement plan", "plan from audit", or "next steps from rx".
SKILL.mdUpdated Mar 26, 2026