md-review
von alirezarezvanimd-review wandelt Markdown-PR-Beschreibungen mit eingezäunten Unified Diffs und Severity-Callouts in ein einseitiges, zweispaltiges HTML-Code-Review um. Der Skill nutzt Parser-, Annotation- und Renderer-Scripts, erfordert einen benannten Reviewer, unterstützt die Konventionen BLOCKER/MAJOR/MINOR/NIT und erhält barrierefreie Hinweise zur Schwere des Befunds.
Dieser Skill erreicht 83/100 Punkte und ist damit ein solider Kandidat für Verzeichnisnutzer, die strukturierte Markdown-Code-Reviews in teilbares HTML umwandeln möchten. Er bietet klare Trigger, echte Scripts, dokumentierte Einschränkungen und ergänzendes Referenzmaterial, sodass ein Agent ihn mit deutlich weniger Rätselraten ausführen kann als einen generischen Prompt. Nutzer sollten ihn nur installieren, wenn ihr Review-Format zum erwarteten Workflow aus Diff plus Severity-Callouts passt.
- Sehr gut auslösbar: Das Frontmatter legt ausdrücklich fest, dass der Skill verwendet wird, wenn der Orchestrator die Eingabe als REVIEW einstuft oder wenn er direkt über /cs:md-review aufgerufen wird; außerdem sind klare Ablehnungsbedingungen für fehlende Reviewer oder fehlende Diff-Hunks definiert.
- Konkreter ausführbarer Workflow: Der Skill beschreibt eine dreistufige stdlib-Pipeline mit Scripts vom Diff-Parsing über die Annotation-Extraktion bis zum HTML-Rendering, inklusive Nutzungsbeispielen in den Script-Docstrings.
- Gute Designbegründung und konsequente Barrierefreiheit: Die Referenzen dokumentieren Diff-Rendering, PR-Annotation-UX, Severity-Codierung und WCAG 1.4.1-Verhalten mit Badges, die Icon, Farbe und aria-label verwenden.
- Enger Einsatzbereich: Erwartet Markdown-Eingaben für PRs bzw. Code-Reviews mit eingezäunten Unified Diffs und Callouts mit Severity-Tags; Eingaben ohne Diff-Hunks werden abgelehnt, und es ist kein allgemeiner Markdown-zu-HTML-Konverter.
- Die Einstiegshinweise sind etwas unvollständig: Im Skill-Pfad gibt es keinen Installationsbefehl und kein README, daher müssen Nutzer das Setup aus der Skill-Datei und den Scripts ableiten.
Überblick über den md-review skill
Was md-review leistet
md-review ist ein Präsentations-Skill für Code Reviews, der einen Markdown-PR-Review in eine einseitige, zweispaltige HTML-Review-Seite umwandelt. Erwartet wird Review-Markdown mit eingezäunten Unified-diff-Blöcken und Kommentaren mit Severity-Tags wie > [!BLOCKER], > [!MAJOR], > [!MINOR] oder > [!NIT]. Das Ergebnis zeigt links den gerenderten Diff, rechts Annotation-Cards, oben eine Sprungnavigation zu den Findings und unten einen verpflichtenden Footer mit dem Namen des Reviewers.
Für wen und welche Workflows md-review am besten passt
Der md-review skill eignet sich besonders für Teams, die bereits strukturierte Code-Review-Notizen in Markdown schreiben und ein portables HTML-Artefakt zum Teilen, Archivieren oder zur Übergabe außerhalb einer PR-Plattform benötigen. Er passt zu Engineering Leads, Reviewern, Documentation Maintainers und Agent-Workflows, die PR-Analysen in eine sauber aufbereitete Review-Seite überführen. Besonders nützlich ist er, wenn Review-Schweregrade, Verankerung an Zeilen und Barrierefreiheit wichtiger sind als eine einfache Markdown-Zusammenfassung.
Was md-review anders macht
Anders als ein allgemeiner Prompt nach dem Muster „mach diesen Review hübsch“ hat md-review eine klar definierte Pipeline: diff_parser.py extrahiert Unified-Diff-Hunks, annotation_extractor.py ordnet Severity-Callouts dem jeweils nächststehenden vorangehenden Diff-Block zu, und review_html_renderer.py erzeugt das finale HTML. Das Repository dokumentiert außerdem Rendering-Entscheidungen in references/diff_rendering_canon.md, references/pr_annotation_ux.md und references/severity_coding.md. Dadurch ist das Ergebnis berechenbarer als spontane LLM-Formatierung.
Wichtige Voraussetzungen für den Einsatz
Die wichtigste Hürde ist die Form der Eingabe. md-review ist nicht für gewöhnliche Markdown-Seiten, Release Notes oder narrative Reports ohne Diff-Hunks gedacht. Ohne expliziten Reviewer-Namen rendert der Skill nicht, und Severity wird bewusst nicht allein über Farbe codiert; Badges enthalten Icons und aria-label-Text für WCAG 1.4.1. Wenn die Quelle keine echten Unified Diffs enthält, sollte die Aufgabe stattdessen an einen Skill für Dokument-Rendering übergeben werden.
So verwendest du den md-review skill
md-review installieren und relevante Repository-Dateien prüfen
Für Claude-kompatible Skill-Manager installierst du den Skill aus dem GitHub-Repository-Pfad, zum Beispiel:
npx skills add alirezarezvani/claude-skills --skill md-review
Lies nach der Installation zuerst SKILL.md, um die Aufrufregeln zu verstehen. Prüfe anschließend diese Dateien, bevor du den Skill produktiv einsetzt:
scripts/diff_parser.pyfür akzeptierte Diff-Fence-Formate und--infer-diffscripts/annotation_extractor.pyfür Callout-Parsing und Zuordnungsverhaltenscripts/review_html_renderer.pyfür erforderliche Renderer-Flags wie--reviewerassets/md_review_template.htmlfür die finale Seitenstrukturreferences/severity_coding.mdfür Standard- und benutzerdefinierte Severity-Stufen
Eingaben vorbereiten, die md-review parsen kann
Ein guter md-review-Workflow beginnt mit Markdown, bei dem jedes Finding nah an dem Diff steht, den es beschreibt:
# Review: payment retry change
```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
- attempts = 1
+ attempts = 5
+ timeout = None
[!BLOCKER]
This can retry indefinitely if the provider never returns. Add a bounded timeout.
Verwende nach Möglichkeit `diff`-Fenced-Blocks. Der Parser kann einige ungetaggte Fences nur dann ableiten, wenn `--infer-diff` verwendet wird; explizite Fences verringern jedoch Mehrdeutigkeiten. Setze allgemeine Kommentare nur dann vor einen Diff, wenn sie als nicht verankerte Kommentare gerendert werden sollen.
### md-review in einem Agent-Workflow aufrufen
Der Skill kann ausgelöst werden, wenn ein Markdown-HTML-Orchestrator die Eingabe als `REVIEW` klassifiziert, oder direkt mit `/cs:md-review`. Ein vollständiger Prompt sollte das Quell-Markdown, den Reviewer-Namen und eventuelle Änderungen an der Severity-Konvention enthalten:
```text
/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]
Wenn du die Skripte direkt verwendest, ist der praktische Ablauf: Diff-Blöcke in JSON parsen, Annotationen diesen Hunks zuordnen und anschließend HTML mit --reviewer rendern. Die Skripte nutzen ausschließlich die Python-Standardbibliothek, was sie in eingeschränkten CI-Umgebungen oder lokaler Automation leichter ausführbar macht.
Praktische Tipps für bessere Ausgabequalität
Für eine bessere Verankerung sollte jeder Callout direkt nach dem relevanten Diff-Block stehen. Für eine bessere Triage solltest du BLOCKER nur für Probleme verwenden, die zwingend behoben werden müssen, und nicht jedes Anliegen als MAJOR kennzeichnen. Für bessere Scanbarkeit sollte der erste Satz jeder Annotation den eigentlichen Entscheidungspunkt enthalten, weil die Sprungnavigation kurze Vorschauen nutzt. Wenn dein Team andere Labels verwendet, übergib eine benutzerdefinierte Vier-Stufen-Konvention in der Reihenfolge von höchster zu niedrigster Severity, zum Beispiel critical,important,suggestion,nit.
FAQ zum md-review skill
Ist md-review nur für Code Reviews gedacht?
Ja. md-review für Code Review ist bewusst eng zugeschnitten: Der Skill konvertiert Markdown-PR-Reviews mit Diff-Hunks und Severity-Annotationen in eine HTML-Review-Seite. Er ist kein allgemeiner Markdown-Site-Generator, kein PR-Diff-Generator und kein Ersatz dafür, den Review selbst zu schreiben.
Was passiert, wenn mein Markdown keine Diff-Blöcke enthält?
Das passt schlecht zum Skill. Das zentrale Layout hängt von Unified-Diff-Hunks, Zeilennummern, Hinzufügungen, Löschungen und der Zuordnung von Annotationen ab. Ohne Diff-Blöcke wäre das Ergebnis irreführend; das beabsichtigte Verhalten ist daher, die Verarbeitung abzulehnen oder die Aufgabe an einen dokumentorientierten Markdown-zu-HTML-Skill weiterzugeben.
Warum ist md-review besser als ein normaler Prompt?
Ein normaler Prompt kann zwar ansprechendes HTML erzeugen, erfindet aber häufig eigene Layout-Regeln, übersieht Zeilennummer-Konventionen oder verlässt sich bei Severity-Hinweisen nur auf Farbe. md-review nutzt konkrete Parsing- und Rendering-Skripte, eine dokumentierte zweispaltige Review-UX und explizite Barrierefreiheitsanforderungen. Das macht den Skill besser geeignet, wenn Konsistenz und Review-Semantik wichtig sind.
Ist md-review einsteigerfreundlich?
Ja, wenn du bereits Markdown-Code-Fences und Unified Diffs verstehst. Einsteiger, die nur Fließtext-Kommentare haben, müssen möglicherweise zuerst einen echten PR-Diff erzeugen oder einfügen. Der einfachste Einstieg ist, die Beispielmodi in den Skripten auszuführen und anschließend die Beispielstruktur des Markdown an den eigenen Review anzupassen.
So verbesserst du den md-review skill
md-review-Eingaben vor dem Rendern verbessern
Der schnellste Weg zu besserem md-review-Output ist eine bessere Review-Quelle. Gib Dateipfade in standardisierten Unified-Diff-Headern an, erhalte @@-Hunk-Header und belasse genug Kontextzeilen, damit Reviewer die Änderung verstehen. Verwende nach Möglichkeit ein Finding pro Callout; mehrere unabhängige Probleme in einer einzigen MAJOR-Card machen die Sprungnavigation weniger hilfreich.
Häufige Fehler vermeiden
Typische Fehler sind ein fehlendes --reviewer, fehlerhafte Diff-Fences, Severity-Labels außerhalb der konfigurierten Konvention und Annotationen, die zu weit vom referenzierten Diff entfernt stehen. Ein subtilerer Fehler ist, Severity als Tonfall statt als Priorität zu verwenden. Eine scharf formulierte Stilpräferenz sollte trotzdem NIT sein; ein sachlich formulierter Korrektheitsfehler kann BLOCKER sein.
Nach dem ersten HTML-Output iterieren
Prüfe nach dem ersten Rendern drei Dinge: ob jedes Finding in der oberen Sprungnavigation erscheint, ob Annotationen an den beabsichtigten Hunks hängen und ob nicht verankerte Kommentare tatsächlich allgemeine Kommentare sind. Wenn eine Annotation an der falschen Stelle landet, verschiebe sie näher an den relevanten Diff-Block, statt das HTML manuell reparieren zu wollen.
Anpassen, ohne das Review-Modell zu beschädigen
Nutze Anpassungen für Team-Konventionen, nicht um die Struktur aufzuweichen. Eine benutzerdefinierte Severity-Liste ist sinnvoll, wenn deine Organisation Labels wie critical, important, suggestion und nit verwendet. Das Ergebnis in einen Fließtext-Report umzubauen, Severity-Icons zu verstecken oder den Reviewer-Footer zu entfernen, untergräbt das, was md-review garantieren soll: nachvollziehbaren, barrierefreien und diff-zentrierten Review-Output.