html-report
Render a markdown report as one self-contained HTML page for a human reader, in plain English, with the answer first, a table of contents and Mermaid diagrams drawn as images. Use when the user asks for an HTML report, or for a readable page made from a markdown document.
- License 许可
- ISC
- 最近更新
- 2026-11-15
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- html-report
- description
- Render a markdown report as one self-contained HTML page for a human reader, in plain English, with the answer first, a table of contents and Mermaid diagrams drawn as images. Use when the user asks for an HTML report, or for a readable page made from a markdown document.
02 资源文件 7
- 参考文档package-lock.json87.8 KB
- 参考文档package.json194 B
- 脚本scripts/html-report.ts5.4 KB
- 脚本scripts/labels.ts974 B
- 脚本scripts/layout.ts7.1 KB
- 脚本scripts/report.css4.7 KB
- 脚本scripts/runtime.ts1.5 KB
03 SKILL.md 正文
html-report — one page a person can read without help
The reader gets the answer first, the decisions second and the evidence after. The renderer moves the sections; the writer supplies plain text that earns each place.
Run it
CLAUDE_PLUGIN_DATA="${CLAUDE_PLUGIN_DATA}" "${CLAUDE_PLUGIN_ROOT}"/bin/html-report <report.md> <report.html>
The first run installs the pinned renderer (marked, @mermaid-js/mermaid-cli, puppeteer) into ${CLAUDE_PLUGIN_DATA}/html-report. A later run installs again only when package-lock.json changes. The renderer drives the local Chrome or Chromium and downloads no browser.
| exit | meaning |
|---|---|
| 0 | wrote <report.html>; with diagrams, also figures: <dir> (<n>) |
| 1 | a Mermaid diagram did not parse: diagram <n> ("<first line>"): <error>; the target holds no HTML |
| 64 | usage error, or the markdown cannot be read |
| 69 | no Chrome or Chromium, the browser did not start, or the install failed; the markdown stays |
PUPPETEER_EXECUTABLE_PATH selects the browser. When it names a missing path, the renderer stops with exit 69 and searches no further.
What the layout does with your headings
The renderer matches an ## heading by its whole text, after it removes a leading number such as 3. or 0.:
| heading | goes to |
|---|---|
Summary, Answer, The answer, TL;DR |
a blue box at the top, labelled The answer |
Decisions, Decisions for you |
an amber box below it |
Sources, References |
a closed section at the end |
| any other heading | the body, in source order |
A heading such as Decision log stays in the body. The table of contents lists the body ## and ### headings. A table with more than 12 rows closes behind a Show table control, except in the decisions box. The first paragraph after each body ## shows as the section's result.
Write for the reader
The reader did not see the work. Write plain English with fewer words: short sentences, the active voice, one idea in each paragraph. Go technical only when the reader asks for it.
- Name a thing by what it does, not by a working label such as a task ID, a ledger row or a pane name. "The opt-in line, added now" is clear; "T13" is not.
- Define each technical term at its first use. Expand each abbreviation once. With 3 or more terms, add a short word list.
- Give every number its unit and its source. Put the source in a short reference, such as a
path:line, a URL or a command. Do not narrate the probe. - Put the risks in a table of what can go wrong and the fix for each.
- Put a decision in
Decisionsonly when the reader must choose. Give each one a recommendation. - Use a diagram when it replaces a paragraph of explanation.
Write for the layout
- Put the answer in 3 to 5 bullets. Start each bullet with its result in bold.
- Start each body section with one sentence that states its result.
- Give each Mermaid diagram an
accTitle:and anaccDescr:line. They become the image's alternative text; without them the text isDiagram <n>. - Keep a diagram shorter than one screen. Split a tall diagram, or use
flowchart LR.
Check before you hand it over
- Read every PNG in the
figures:directory. Each is a screenshot of one diagram as the page shows it. - A label is clipped or overlaps, or a diagram is too small to read: fix the Mermaid source and run again.
- Read each
looks like a working labelline. Rename the label, or define it on the page, and run again. A label that the page defines can stay. - Give the reader the HTML path. The file holds its styles and its images, so it opens offline.
Honesty labels
| claim | enforced by |
|---|---|
| a diagram that does not parse stops the render | code — exit 1; an earlier page at the target is removed |
| no local browser stops the render | code — exit 69 before any install |
| the answer box holds 3 to 5 bullets | model-judgment — the renderer moves the section and counts nothing |
| each diagram is legible | model-judgment — the screenshots exist; reading them is the check |
| a working label in the prose is reported | advisory — one stderr line per label, exit 0; fenced code, inline code, comments and open-item lines are not scanned |
| the page reads as plain English | model-judgment — the scan finds labels, not jargon |
PDF output and hosting are out of scope.
04 同仓库更多 Skills
ship
Review the dossier branch once, fold the fixup commits into the planned commits, hand the push and PR to the operator, then watch CI. Invoke when the user says "ds:ship", "ship the dossier", or when ds next exits 4.
plan
Open a dossier and write its plan with the operator, then get it checked by a fresh agent before any build. Invoke when the user says "ds:plan", "start a dossier", "plan this", "grill me" in a repo with `.scratchpad/dossier/`, or when work needs more than one commit.
suite-review
Run the monthly evidence review of this repo's plugin skills. Count each skill's opportunities and uses with the census, read what happened where a skill was not used, put each skill in one bucket, act, and write the actions as predictions with a check date. Use when the operator says "suite review" or "monthly review", or when the suite-review line on LATER.md is due.
research-report
Research a technical question with probes on the local system, a web fan-out through deep-research, a grounding pass on every load-bearing claim, and a report rendered as one HTML page. Use when the user asks for a research report, a design study or an evidence-backed recommendation about their own system.
domain-modeling
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.