Skip to main content
skill CX Codex

html-doc — Claude Code skill: what it does, how to install

The html-doc skill turns a finished Markdown PRD or technical design into a static HTML reading page. It is useful when a document needs browser and print presentation.

MIT 288 installs ★ 438 updated 2026-11-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add owainlewis/blueprint --skill html-doc -a claude-code
Open on GitHub

What html-doc does

html-doc accepts a complete Markdown file or exact inline Markdown and renders one static HTML page for either a prd or design document. Markdown stays canonical: the skill changes presentation rather than requirements or meaning. It does not author missing content, edit the source, or publish the result. Generation and lifecycle steps run through scripts/html_doc.py.

The page uses semantic HTML, inline CSS, responsive and print styles, a table of contents, accessible controls, and embedded Mermaid SVG. Before the first Mermaid render, run npm ci --prefix <skill-directory>. The environment also needs Python 3.11 or newer, Pandoc 3 or newer, Node.js 22.12 or newer, and npm. Without those dependencies, rendering cannot start.

The verification pass opens the candidate in a real browser and checks 1440, 768, and 390 CSS-pixel layouts, A4 and US Letter print views, keyboard order, overflow, console errors, failed requests, and offline operation. Finalization atomically replaces the previous file only after every check passes.

What it helps with

  • turn a Markdown PRD into a readable HTML page
  • present a technical design in a browser and on paper
  • check section links and keyboard navigation
  • render Mermaid diagrams inside a static document
  • preserve source wording while changing its presentation

Example prompts for the agent

  • Turn REQUIREMENTS.md into a static HTML page and verify it in a browser.
  • Render ARCHITECTURE.md as a design document, then check the mobile layout and print view.
  • Use spec.md to create a candidate, inspect its diagrams, and finalize it only after all checks pass.

How to install html-doc

1Skills CLI (Vercel)

npx skills add owainlewis/blueprint --skill html-doc -a claude-code

2Manually: put the files in place

~/.claude/skills/html-doc/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/html-doc/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about html-doc

How do I install html-doc in Claude Code?

Run npx skills add owainlewis/blueprint --skill html-doc -a claude-code, then check ~/.claude/skills/html-doc/SKILL.md.

What does html-doc do?

It renders a finished Markdown PRD or technical design as a static HTML reading page. The skill checks layout, accessibility, diagrams, and print output before finalization.

Which documents and prerequisites does html-doc support?

It supports only prd and design documents. You need Python 3.11 or newer, Pandoc 3 or newer, Node.js 22.12 or newer, and npm; run npm ci --prefix <skill-directory> before the first Mermaid render.

Source text

SKILL.md · MIT
---
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.
user-invocable: true
argument-hint: "<Markdown PRD or design file>"
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.

© owainlewis · MIT · owainlewis/blueprint

Similar skills

All skills for Writing and docs →

From the same set9

plan plan breaks down feature specs into end-to-end tasks designed for an agent to finish in a single pull request. Runs before coding begins to turn requirements into ready-to-build work slices. CX Codex +1 788installs review Runs an isolated read-only code review. It checks changes against specs, probes security flaws, and verifies tests by breaking code deliberately. CX Codex +1 787installs task-to-pr task-to-pr — a skill that carries a spec, issue, or task to an open pull request: branch, tests, Conventional Commits, CI, and an independent review. Merges only on explicit request. CX Codex +1 452installs spec Writes a feature specification before coding begins. It produces a short PRD with user journeys and a technical design for the implementing agent. CX Codex +1 440installs improve The improve Claude Code skill simplifies existing code while preserving its behavior. It targets duplication, dead code, unclear names, and needless abstractions. CX Codex +1 372installs architecture-review architecture-review — a skill for Claude Code and Codex reviews RFCs, ADRs, and technical proposals before code gets written. It flags critical architectural flaws, unsafe patterns, and missing recovery paths. CX Codex +1 347installs architecture Writes or updates the root ARCHITECTURE.md file from a fixed template. It locks in system boundaries, data flow diagrams, and architectural rules. CX Codex +1 331installs codex-issue-coordinator codex-issue-coordinator is a Codex skill that assigns GitHub issues to AI workers, tracks PRs and tests, and merges completed work. It handles batches in one Codex conversation. CX Codex +1 241installs

Project sponsors

Companies that keep this analytics open