Stats
Actions
Tags
From bba
Turn a markdown doc into a single, self-contained visual HTML page that is easy to skim and trustworthy to read. Supports single files and directories (generates one HTML with tab navigation). Use whenever the user wants to read, understand, clean up, summarize, or share AI-generated markdown — specs, OpenSpec change proposals, reference docs, architecture/design docs, RFCs, READMEs — especially when they say the docs are long, dense, full of AI boilerplate ("slop"), hard to skim, or "抓不住重点". Also use when the user wants to translate an English doc into natural Chinese, or asks to "把这个 md 可视化 / 转成 HTML / 去掉套话 / 翻译成中文 / 看懂这份文档". The page surfaces the key points up top, collapses the deep detail, draws Mermaid diagrams for flows/architecture, and keeps the original text one click away. It never rewrites the author's meaning. Prefer this skill over a plain markdown→HTML conversion whenever readability, de-slopping, summarization, or Chinese translation matters.
How this skill is triggered — by the user, by Claude, or both
Slash command
/bba:doc-visualizerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turn one markdown file into one self-contained HTML page that a tired engineer can skim in 30 seconds and trust completely.
Turn one markdown file into one self-contained HTML page that a tired engineer can skim in 30 seconds and trust completely.
The docs that AI coding agents generate (OpenSpec specs, reference docs, architecture write-ups) are usually correct but exhausting: padded with boilerplate, flat in structure, hard to skim, and — when English — awkward to read for a Chinese-speaking team. This skill fixes the reading experience without touching the substance.
"More detail" and "less slop" are not in tension once you separate length from information.
The test for every sentence in the output: does it carry a fact or an action? If not, it goes. If a reader would ask "but why?" or "how?", that's where you add — and only there. Never pad to seem thorough.
This overrides everything below. The output is a better view of the source, never a different document.
补充 / 推测), so the reader always knows what is theirs vs. yours.src/auth/token.ts:42). Enrichment that is your inference is labeled 推测 and phrased tentatively. If you can't ground or honestly mark a claim, don't make it.A good mental model: you are an editor and designer, not a co-author. You re-present and annotate. You never put words in the author's mouth.
Work through these stages in order. Think first, render last.
Read the source markdown fully. If the input path is a directory, recursively find all .md files within it (excluding node_modules, .git, and hidden directories). Sort them by relative path. Then process each file through stages 2–5 individually before rendering. Detect the doc type and language per file. Type and language steer summary phrasing and which diagrams help — but the v1 renderer is general-purpose; don't build type-specific templates yet, just adapt emphasis.
Produce a "本文要点" list of 3–7 bullets — the things a reader must take away — and a one-line summary for each major section. This is the single most valuable output; it's what solves "抓不住重点". Label it clearly as a summary (it's yours, not the author's words). Pull these from the source; do not invent.
Remove boilerplate and empty phrasing per references/slop-blocklist.md. This is deletion and tightening only — never a rewrite of substance. Preserve all technical content, including anything the blocklist would superficially match but that actually carries meaning in context.
Where a reader would get stuck on why or how, add a 补充 callout. If repo access is available and relevant, read the referenced code to ground the explanation and cite the path:line. Otherwise mark it 推测. Do not enrich passages that are already clear — restraint is part of quality.
Follow references/glossary-zh.md. The bar: read like it was written by a Chinese engineer, not translated.
useEffect, PostgreSQL, OAuth, git rebase.译注) only for genuinely ambiguous or culture-bound terms.Fill assets/template.html (single file) or assets/template-dir.html (directory) as the skeleton. Both already contain the CSS, the light/dark theme, the sticky table-of-contents, the collapsible machinery, callout styles, syntax highlighting (highlight.js via CDN) and Mermaid (via CDN). Don't reinvent styling; fill the marked content regions. Read the comments at the top of each template for exactly which regions to replace.
Use assets/template.html. Components to populate:
<details> "深入" blocks so the page skims fast and expands on demand.补充 (sourced addition), 推测 (inferred), 译注 (translation note), plus 信息/注意/警告 as the content warrants.flowchart, sequenceDiagram, graph). The diagram supplements the text; it never replaces the original.Use assets/template-dir.html. The pipeline stages 2–5 run per file; stage 6 renders all files into one HTML. Each file goes through the same fidelity contract.
Components to populate (in addition to per-file components above):
<div class="file-panel" id="file-N"> containing the same structure as a single-file render (header, keypoints, sections). The first file's panel is active by default.<script type="application/json" id="toc-data"> block with each file's section IDs and titles.sec-F-S format (F = file index, S = section index within that file) to avoid ID collisions across files.<source-basename>.bba-doc-viz.html next to the source (e.g. proposal.md → proposal.bba-doc-viz.html).<directory-name>.bba-doc-viz.html inside the directory (e.g. docs/ → docs/docs.bba-doc-viz.html).The .bba-doc-viz.html suffix makes generated files easy to identify and gitignore — suggest that users add *.bba-doc-viz.html to their project's .gitignore. Then tell the user the path and offer to open it.
Reading the surrounding codebase makes enrichment far more accurate — but only use what you actually read, and always cite it (rule 3). If you don't have repo access and the doc references code you'd need to see, say so in the relevant 补充/推测 rather than guessing silently.
Before handing back the HTML, re-read it against the source and confirm:
补充/推测 is either sourced or honestly marked as inference.<details>)..md file found in the directory is represented (no file silently dropped); tab switching correctly shows each file's content and updates the sidebar; section IDs don't collide across files.If anything fails, fix it before delivering. Respecting the original is the whole point; a pretty page that distorts the source is a failure.
references/slop-blocklist.md — what counts as slop, with English + Chinese examples and the keep-don't-cut caveats.references/glossary-zh.md — translation rules, preferred Chinese phrasings, the do-not-translate list, and the banned-word list (extend this over time).assets/template.html — the HTML skeleton for single-file mode.assets/template-dir.html — the HTML skeleton for directory mode.npx claudepluginhub billbai/bba --plugin bbaGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.