Use when you have a written implementation plan to execute in a separate session with review checkpoints
doc-rx
0
0
# Install this skill:
npx skills add acardozzo/rx-suite --skill "doc-rx"
Install specific skill from multi-skill repository
# Description
>
# SKILL.md
name: doc-rx
description: >
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.
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/:
1. Save a copy of the report to docs/rx-plans/{this-skill-name}/{date}-report.md
2. For each dimension scoring below 97, invoke the rx-plan skill to create or update the improvement plan at docs/rx-plans/{this-skill-name}/{dimension}/v{N}-{date}-plan.md
3. Update docs/rx-plans/{this-skill-name}/summary.md with current scores
4. Update docs/rx-plans/dashboard.md with overall progress
This happens automatically β the user does not need to run /rx-plan separately.
# Related Skills
Use when starting any conversation - establishes how to find and use skills, requiring Skill...
|
|
# Supported AI Coding Agents
This skill is compatible with the SKILL.md standard and works with all major AI coding agents:
Amp
Antigravity
Claude Code
Clawdbot
Codex
Cursor
Droid
Gemini CLI
GitHub Copilot
Goose
Kilo Code
Kiro CLI
OpenCode
Roo Code
Trae
Windsurf
Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.