md-review

Converts a markdown PR writeup or code review (one with ```diff fenced blocks and severity-tagged > [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT] callouts) into a single-file 2-column HTML review — unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer. Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review. Refuses without explicit --reviewer (a code review must name a human), refuses if no diff hunks present (route to md-document instead), and refuses to encode severity in color only (every badge ships color + icon + aria-label per WCAG 1.4.1). Use after orchestrator routing.

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Quality

Content

86%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.

A well-structured, highly actionable skill body with a clear pipeline, explicit hard rules, and clean progressive disclosure to real reference/script bundles. The main opportunity is trimming the rationale/canon citations in the forcing-question library for token efficiency.

Suggestions

Trim or relocate the 'Forcing-question library' canon citations ('SWE at Google ch. 9', 'research-ops named-owner pattern') to a reference file; the questions themselves are useful but the provenance padding adds tokens Claude doesn't need.

Add an explicit inter-step validation checkpoint in the Pipeline (e.g., 'verify hunks.json is non-empty before extracting annotations') to turn the forward pipeline into a checked workflow.

Drop the restated WCAG 1.4.1 explanation in Hard rule 5 since it already appears verbatim in the description.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with action-oriented sections, but the forcing-question library and repeated provenance citations ('Matt Pocock grill discipline', 'Canon: SWE at Google ch. 9') add rationale Claude does not strictly need and could be trimmed.	4 / 5
Actionability	The Pipeline section gives fully executable, copy-paste-ready bash commands with concrete paths, flags, and a worked example (--reviewer 'Jane Doe' --title 'PR #123: Add retry logic'), and Hard rules specify concrete exit codes.	5 / 5
Workflow Clarity	The three-step pipeline is clearly numbered and sequenced with refusal-based validation gates (exit 3/4) in Hard rules, but there is no explicit inter-step verification or fix-and-retry feedback loop in the pipeline itself.	4 / 5
Progressive Disclosure	The body is a clear overview with well-signaled one-level-deep references ('See references/ for full citations (diff_rendering_canon, severity_coding, pr_annotation_ux)') and real bundle files in references/, scripts/, and assets/ — content is appropriately split and easy to navigate.	5 / 5
	Total	18 / 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, third-person description that states concrete capabilities and explicit trigger conditions with clear distinctiveness from sibling converters. Slight room to broaden natural trigger-term coverage (e.g., .md file extensions).

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'unified-diff on the left, severity-tagged annotation cards on the right, top jump-nav listing every finding, mandatory named reviewer footer' — giving comprehensive coverage of what the converter produces.	5 / 5
Completeness	Explicitly answers both what (converts markdown code review → 2-column HTML) and when ('Triggers when the markdown-html-orchestrator classifies an input as REVIEW, or when invoked directly via /cs:md-review', 'Use after orchestrator routing') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good keyword coverage including natural domain terms ('markdown PR writeup', 'code review', 'diff fenced blocks') and the /cs:md-review slash command, but missing common file-extension triggers like .md and a few synonyms.	4 / 5
Distinctiveness Conflict Risk	Clear niche (code-review markdown → HTML) with explicit routing of non-review inputs to md-document/md-slides and a refusal rule when no diff hunks are present, minimizing overlap with sibling converters.	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: alirezarezvani/claude-skills
Path: markdown-html/skills/md-review/SKILL.md
Commit: 19392f7

Reviewed: ~4 hours ago

Table of Contents

Discovery Implementation Validation

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.