Skip to content
Skills Library
Documents & office · Conversion & formats

html-doc

/html-doc

Generates a polished, static HTML reading view from an existing Markdown PRD or technical design. Use when a user asks to render, present, visualize, or make a PRD or design document easier for humans to read in a browser.

Repository
blueprint ↗
Licence
MIT
Last repository change
12.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/html_doc.py, tests/test_html_doc.py

What it does and when to use it

Generates a polished, static HTML reading view from an existing Markdown PRD or technical design. Use when a user asks to render, present, visualize, or make a PRD or design document easier for humans to read in a browser.

Original author description

Generates a polished, static HTML reading view from an existing Markdown PRD or technical design. Use when a user asks to render, present, visualize, or make a PRD or design document easier for humans to read in a browser.

How it works

  1. Boundaries
  2. Requirements
  3. Workflow
  4. Output standard
  5. Return
Original SKILL.md headings · 115 lines, 752 words
SKILL.md preview
---
name: html-doc
description: Generates a polished, static HTML reading view from an existing Markdown PRD or technical design. Use when a user asks to render, present, visualize, or make a PRD or design document easier for humans to read in a browser.
disable-model-invocation: true
---

# HTML document

Turn one complete Markdown PRD or technical design into one verified static HTML page. Keep Markdown canonical. Change presentation, not meaning.

## Boundaries

- Accept an existing Markdown file or exact inline Markdown.
- Support only `prd` and `design` document kinds.
- For `REQUIREMENTS.md`, pass `--kind prd`. For `ARCHITECTURE.md` or `spec.md`, pass `--kind design`.
- Classify `prd.md` as `prd` and `design.md` as `design`. For other names, use the request or ask if the kind is unclear.
- Do not write requirements, settle design choices, summarize missing content, or edit the source.
- If the source is only a rough brief, use the appropriate authoring skill first.
- Do not hand-edit generated HTML. Change the template or renderer, then regenerate.
- Do not publish or host the result unless the user separately asks.

## Requirements

Generation requires Python 3.11 or newer, Pandoc 3 or newer, Node.js 22.12 or newer, and npm. The skill directory contains a locked Mermaid dependency tree.

Before the first Mermaid render, run:

```bash
npm ci --prefix <skill-directory>
```

Use `scripts/html_doc.py` from this skill directory for all generation and lifecycle operations.

## Workflow

### 1. Read and classify the source

Read the complete source. Confirm it is no larger than 2 MiB. Determine the document kind from the request or the basename mappings above.

Treat content problems separately from presentation problems. If the Markdown contradicts itself, omits a required decision, or contains an invalid diagram, report that source problem. Do not silently repair its meaning.

### 2. Create a candidate

For a file source:

```bash
python3 <skill-directory>/scripts/html_doc.py render <source.md> --kind <prd-or-design> --out <output.html>
```

`--kind` may be omitted only for exact `prd.md` and `design.md` basenames. `--out` may be omitted to create a sibling HTML file.

For exact inline Markdown, pipe it through standard input and provide both kind and output:

```bash
python3 <skill-directory>/scripts/html_doc.py render --inline --kind <prd-or-design> --out <output.html>
```

The command returns JSON containing `candidate`, `output`, and `token`. It does not replace the final output. Keep those exact values for verification and finalization.

If an output lock already exists, do not delete it automatically. It may represent another pending render. Report its path. Use `discard --force-stale` only when the state is known to be abandoned.

### 3. Verify the candidate in a real browser

Open the candidate as a local file. Do not treat source inspection as browser proof.

Check all of these:

- desktop at 1440 CSS pixels;
- tablet at 768 CSS pixels;
- mobile at 390 CSS pixels;
- A4 and US Letter print preview;
- table-of-contents links and section targets;
- keyboard order from skip link through navigation and document links;
- visible focus indicators;
- one `main` landmark and a sensible heading outline;
- unique DOM IDs;
- horizontal overflow, clipped text, code, tables, and diagrams;
- useful diagram alternatives and accessible disclosure controls;
- console errors and failed resource requests;
- operation with browser network access disabled.

Compare the canonical content inside `main` with the Markdown abstract syntax tree. Navigation, source metadata, and derived accessibility text are not canonical content. Each top-level source block must map to one ordered `data-source-block` node with its SHA-256 identity and nested content intact. A Mermaid block maps to one figure whose exact source appears once in its disclosure.

If a presentation defect comes from the shared renderer or styles, fix that source and regenerate. If it is a content defect, leave the source and candidate unchanged and report it.

### 4. Finalize or discard

Only after every check passes, atomically install the candidate:

```bash
python3 <skill-directory>/scripts/html_doc.py finalize --out <output.html> --token <token>
```

If any check fails, remove only this pending candidate:

```bash
python3 <skill-directory>/scripts/html_doc.py discard --out <output.html> --token <token>
```

Finalization performs one same-directory atomic replacement. It never deletes the previous output first. A failed render, check, or replacement must leave the previous verified output byte-for-byte unchanged.

## Output standard

The final page must:

- preserve source wording and order;
- use canonical `prd` or `design` machine metadata;
- record the source path and SHA-256 hash;
- use semantic HTML, inline CSS, and no runtime JavaScript;
- contain no external runtime assets;
- use a restrained blue-grey visual system;
- remain readable without color, a mouse, a wide screen, or network access;
- include responsive and print styles;
- embed validated Mermaid SVG as a base64 image and retain the exact source in a disclosure.

## Return

Stop when the verified candidate is finalized. Report the output path, source
hash, and browser checks performed.
Files in this package (12)
  • SKILL.md 5 KB
  • package-lock.json 84 KB
  • package.json 1 KB
  • agents/openai.yaml 1 KB
  • assets/mermaid.json 1 KB
  • assets/puppeteer.json 1 KB
  • assets/styles.css 7 KB
  • scripts/html_doc.py 28 KB
  • tests/test_html_doc.py 14 KB
  • tests/fixtures/design.md 1 KB
  • tests/fixtures/diagram.mmd 1 KB
  • tests/fixtures/prd.md 1 KB

Versions

The database has no other skills named html-doc.

Database snapshot: 13.11.2026 · package version 76b236451bec (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100render-html
    Render an ARIS Markdown / JSON artifact (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN, research-wiki state, etc.) into a single-file HTML view designed for human reading. Use when the user says \"Render HTML\", \"Here's a copy. HTML Report\", \"render html\", \"make this…
  • 100render-html
    Render an ARIS Markdown / JSON artifact (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN, research-wiki state, etc.) into a single-file HTML view designed for human reading. Use when the user says \"渲染 HTML\", \"出一份 HTML 报告\", \"render html\", \"make this readable\",…
  • 100render-html
    Render an ARIS Markdown / JSON artifact (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN, research-wiki state, etc.) into a single-file HTML view designed for human reading. Use when the user says \"渲染 HTML\", \"出一份 HTML 报告\", \"render html\", \"make this readable\",…
  • 100prd-to-html
    Use when the user wants to read an existing PRD or markdown spec as a human-readable HTML page, or hand one to a stakeholder — triggers include "PRD를 HTML로", "PRD 읽기 좋게 만들어줘", "기획서 HTML로 변환", "convert this PRD to HTML", "make my PRD readable", "PRD를 사람이 읽게". This renders a…
  • 100doc-review
    Use when reviewing a prose plan, spec, PRD, requirements doc, design doc, or brainstorm, or invoking /doc-review. Not for collaborative drafting: use doc-coauthoring.
  • 100edit-doc
    Make a document the reader can edit and save right in the browser, with no server, extension, or login. Two kinds: (1) a standalone HTML document that carries its own editor (reports, letters, guides, notices) — copy skeleton.html and write the content; (2) a Markdown document…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.