borghei/Claude-Skills / markdown-html/md-review
md-review
VerifiedPre-publication quality gate for authored Markdown — heading structure, on-disk link resolution, readability, accessibility, terminology. Use when reviewing docs before publishing, wiring a docs CI gate, or auditing a Markdown corpus.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.1 KB |
| assets/review_report_template.md | markdown | 4.3 KB |
| assets/sample_article.md | markdown | 2.4 KB |
| assets/sample_article_clean.md | markdown | 1.8 KB |
| assets/sample_review_config.json | config | 2.4 KB |
| references/readability-accessibility-and-terminology.md | markdown | 17.7 KB |
| references/review-rulebook-and-severity-model.md | markdown | 20.5 KB |
| scripts/link_checker.py | script | 11.9 KB |
| scripts/md_review_gate.py | script | 15.8 KB |
| scripts/readability_scorer.py | script | 14.1 KB |
assets/review_report_template.md
View on GitHub# Markdown pre-publication review — {{DOCUMENT_TITLE}}
**File:** `{{FILE_PATH}}`
**Reviewed:** {{REVIEW_DATE}}
**Reviewer:** {{REVIEWER}}
**Config profile:** `{{CONFIG_PROFILE}}`
**Gate result:** {{PASS_OR_FAIL}} (fail-on: `{{FAIL_ON_LEVEL}}`)
---
## 1. Verdict
| Metric | Value | Threshold | Status |
| --- | --- | --- | --- |
| Errors | {{ERROR_COUNT}} | 0 | {{ERROR_STATUS}} |
| Warnings | {{WARNING_COUNT}} | {{MAX_WARNINGS}} | {{WARNING_STATUS}} |
| Info | {{INFO_COUNT}} | — | — |
| Broken internal links | {{BROKEN_LINK_COUNT}} | 0 | {{LINK_STATUS}} |
| Flesch Reading Ease | {{FLESCH}} | {{FLESCH_BAND}} | {{FLESCH_STATUS}} |
| Flesch-Kincaid grade | {{FK_GRADE}} | ≤ {{MAX_GRADE}} | {{FK_STATUS}} |
**One-line call:** {{VERDICT_SENTENCE}}
---
## 2. Blocking findings (errors)
Every item here must be fixed before publication.
| ID | Rule | Line | Finding | Fix |
| --- | --- | --- | --- | --- |
| E1 | {{RULE_ID}} | {{LINE}} | {{MESSAGE}} | {{SUGGESTED_FIX}} |
| E2 | | | | |
---
## 3. Non-blocking findings (warnings)
Fix before the next content review cycle.
| ID | Rule | Line | Finding | Owner |
| --- | --- | --- | --- | --- |
| W1 | {{RULE_ID}} | {{LINE}} | {{MESSAGE}} | {{OWNER}} |
| W2 | | | | |
---
## 4. Structure
- **Heading tree depth:** {{MAX_DEPTH}} (limit {{DEPTH_LIMIT}})
- **H1 count:** {{H1_COUNT}} (must be 1)
- **Skipped levels:** {{SKIPPED_LEVELS}}
- **Longest section:** `{{LONGEST_SECTION}}` at {{LONGEST_SECTION_WORDS}} words
- **Heading capitalization style detected:** {{HEADING_CASE}} ({{HEADING_CASE_CONSISTENCY}}% consistent)
Outline as parsed:
```
{{HEADING_OUTLINE}}
```
---
## 5. Links
**Resolved on disk. No network requests were made.**
| Target | Type | Status | Line |
| --- | --- | --- | --- |
| {{LINK_TARGET}} | relative-file / anchor / external | ok / broken / not-checked | {{LINE}} |
**External link inventory ({{EXTERNAL_COUNT}} links, unverified):**
| URL | Occurrences | Host |
| --- | --- | --- |
| {{URL}} | {{COUNT}} | {{HOST}} |
External links are inventoried, never fetched. Verify them manually or with a
separate network-enabled job that runs outside the publication gate.
---
## 6. Readability
| Measure | Value | Target band | Reading |
| --- | --- | --- | --- |
| Flesch Reading Ease | {{FLESCH}} | {{FLESCH_BAND}} | {{FLESCH_READING}} |
| Flesch-Kincaid grade | {{FK_GRADE}} | {{FK_BAND}} | {{FK_READING}} |
| Sentences | {{SENTENCE_COUNT}} | — | — |
| Mean sentence length | {{MEAN_SENTENCE_WORDS}} words | ≤ 20 | {{MSL_STATUS}} |
| Long sentences (> {{LONG_LIMIT}} words) | {{LONG_COUNT}} ({{LONG_PCT}}%) | ≤ {{MAX_LONG_PCT}}% | {{LONG_STATUS}} |
| Passive constructions | {{PASSIVE_COUNT}} ({{PASSIVE_PCT}}%) | ≤ {{MAX_PASSIVE_PCT}}% | {{PASSIVE_STATUS}} |
**Worst sentences to rewrite first:**
1. Line {{LINE}} ({{WORDS}} words): "{{SENTENCE_EXCERPT}}"
2.
3.
---
## 7. Accessibility
| Check | WCAG SC | Result |
| --- | --- | --- |
| Images have meaningful alt text | 1.1.1 Non-text Content (A) | {{ALT_RESULT}} |
| Heading levels not skipped | 1.3.1 Info and Relationships (A) | {{HEADING_RESULT}} |
| Tables have header rows | 1.3.1 Info and Relationships (A) | {{TABLE_RESULT}} |
| Link text is descriptive out of context | 2.4.4 Link Purpose (A) / 2.4.9 (AAA) | {{LINK_TEXT_RESULT}} |
| Document has one descriptive top heading | 2.4.6 Headings and Labels (AA) | {{H1_RESULT}} |
| Language declared in frontmatter | 3.1.1 Language of Page (A) | {{LANG_RESULT}} |
---
## 8. Terminology and style
| Found | Preferred | Occurrences | Lines |
| --- | --- | --- | --- |
| {{FOUND_TERM}} | {{PREFERRED_TERM}} | {{COUNT}} | {{LINES}} |
---
## 9. Decision
- [ ] **Publish** — no errors, warnings accepted by owner
- [ ] **Publish with follow-up** — warnings tracked in {{TICKET}}
- [ ] **Hold** — blocking findings remain
**Signed off by:** {{APPROVER}}
**Date:** {{DATE}}
---
## Appendix — reproduce this report
```bash
python3 markdown-html/md-review/scripts/md_review_gate.py \
--input {{FILE_PATH}} \
--config markdown-html/md-review/assets/sample_review_config.json \
--format text
python3 markdown-html/md-review/scripts/link_checker.py \
--input {{FILE_PATH}} --format text
python3 markdown-html/md-review/scripts/readability_scorer.py \
--input {{FILE_PATH}} \
--config markdown-html/md-review/assets/sample_review_config.json \
--format text
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |