prefer-html-output (English)
Help the agent render "long markdown intended for human reading" as HTML when the scenario benefits from it. Based on Anthropic Claude Code engineering lead Thariq Shihipar's html-effectiveness project — 20 real examples.
When to trigger this skill (hybrid mode)
The agent runs the three layers in order before each reply. The user is only prompted when Layer 2 matches.
Layer 1 · Hard exclusion (any match → silently use markdown)
- Output will be consumed by an automated pipeline (writing
.md files, filling PR/issue descriptions, generating commit messages, writing logs, etc.)
- The user explicitly asked for markdown or plain text
- Short replies (~ < 20 lines) or conversational Q&A
- Main output is source code edits, command execution, or debug output
Layer 2 · High-value scenario detection (only matches enter the proposal step)
Consult references/scenario-map.md to see whether the output intent matches one of these categories. The numbers in parentheses correspond to example files in references/examples/:
| Category |
When it matches |
Example IDs |
| Solution / design comparison |
"compare 3 approaches", "several design directions", "A/B/C paths" |
01, 02 |
| Implementation plan |
"implementation roadmap", "milestones + timeline", "risk table" |
16 |
| Code review output |
"PR review report", "diff annotations", "per-file comments" |
03, 17 |
| Code understanding / architecture |
"module dependencies", "unfamiliar package walkthrough" |
04 |
| Design system / component showcase |
"color palette", "component states overview" |
05, 06 |
| Prototype / animation / interaction |
"animation effect", "click flow", "interaction draft" |
07, 08 |
| Diagrams / flowcharts |
"SVG diagram", "deployment flow", "decision tree" |
10, 13 |
| Presentation / report / explainer |
"slide deck", "weekly report", "incident postmortem", "concept explainer", "feature explainer" |
09, 11, 12, 14, 15 |
| Ad-hoc editors (rare) |
"triage board", "feature flag editor", "prompt tuner" |
18, 19, 20 |
Layer 3 · Proposal phrasing
When Layer 2 matches, propose with this format:
This content might work better as HTML (scenario: {category}, reference example #{ID} {slug}). Want me to generate the HTML and open it in your browser? (Reply "keep md" to stay on the original markdown plan.)
- User agrees → enter the generation flow
- User declines ("keep md" / "no" / negative) → use markdown as originally planned. Lower the proposal frequency for the same category in this session.
Generation flow
- Learn the style first: use the Read tool to open the matching example file
references/examples/NN-*.html. Understand its layout, styling, and visualization logic.
- Generate the HTML: use the Write tool to write the complete HTML (with
<!DOCTYPE html>, inline CSS, inline JS where needed) to /tmp/<slug>.html.
- Do not link external CSS/JS libraries (unless the source example itself uses a CDN).
- Prefer semantic tags (section/article/figure).
- Use a sensible font stack appropriate to the content language.
- Call render.sh:
bash ~/.claude/skills/prefer-html-output-en/scripts/render.sh /tmp/<slug>.html --scenario <key>
<key> comes from the "Scenario keyword → ID quick lookup" table at the bottom of references/scenario-map.md.
- Reply to the user: a one-sentence confirmation that includes the final path (read from the script's stdout) and that the browser has been opened.
scenario key quick reference
See the table at the bottom of references/scenario-map.md for the full list. Commonly used:
- Weekly report →
weekly-report (lands in articles/YYYY-MM-DD/)
- Incident postmortem →
incident-report (lands in articles/)
- Concept explainer →
concept-explainer (lands in articles/)
- Feature explainer →
feature-explainer (lands in articles/)
- Slide deck →
slide-deck (lands in articles/)
- Design comparison →
comparison (lands in temp/html-output/)
- Implementation plan →
implementation-plan (lands in temp/)
- PR review →
pr-review (lands in temp/)
- Design system →
design-system (lands in temp/)
- Flowchart →
flowchart (lands in temp/)
If unsure, omit --scenario (defaults to temp/html-output/).
render.sh parameters
bash scripts/render.sh <html_file> [--scenario <key>] [--no-open] [--long-term]
<html_file>: required. Agent writes to /tmp/ first.--scenario <key>: optional. Decides the destination folder.--no-open: optional, debug-only — skip launching the browser.--long-term: optional — force the file into permanent/html/ (long-term storage).
Output: the final absolute path on stdout (single line).
All destination folders are created under the current working directory by default. The skill does not assume any project-specific layout.
Cautions
- Never generate HTML without explicit user consent. This skill is propose → wait → execute by default.
- Always read the matching example before generating. This prevents stylistic drift and "HTML rendering" with poor results.
- If the user declines, drop it. Lower the proposal frequency for similar scenarios for the rest of the session.
- Path decisions go through render.sh only. Don't hand-roll
open or mv — that bypasses the folder convention.
1---2name: prefer-html-output-en3description: When the agent is about to output long markdown (weekly reports, PR reviews, design comparisons, concept explainers, flowcharts, design systems and other deliverables meant for human reading), proactively evaluate whether to render it as HTML instead. Based on the 20 examples from ThariqS/html-effectiveness. Only proposes when a clear high-value scenario is detected; with user consent, generates the HTML file and opens it in the browser.4---56# prefer-html-output (English)78Help the agent render "long markdown intended for human reading" as HTML when the scenario benefits from it. Based on Anthropic Claude Code engineering lead Thariq Shihipar's [html-effectiveness](https://github.com/ThariqS/html-effectiveness) project — 20 real examples.910## When to trigger this skill (hybrid mode)1112The agent runs the three layers in order before each reply. The user is only prompted when Layer 2 matches.1314### Layer 1 · Hard exclusion (any match → silently use markdown)15- Output will be consumed by an automated pipeline (writing `.md` files, filling PR/issue descriptions, generating commit messages, writing logs, etc.)16- The user explicitly asked for markdown or plain text17- Short replies (~ < 20 lines) or conversational Q&A18- Main output is source code edits, command execution, or debug output1920### Layer 2 · High-value scenario detection (only matches enter the proposal step)2122Consult `references/scenario-map.md` to see whether the output intent matches one of these categories. The numbers in parentheses correspond to example files in `references/examples/`:2324| Category | When it matches | Example IDs |25|---|---|---|26| Solution / design comparison | "compare 3 approaches", "several design directions", "A/B/C paths" | 01, 02 |27| Implementation plan | "implementation roadmap", "milestones + timeline", "risk table" | 16 |28| Code review output | "PR review report", "diff annotations", "per-file comments" | 03, 17 |29| Code understanding / architecture | "module dependencies", "unfamiliar package walkthrough" | 04 |30| Design system / component showcase | "color palette", "component states overview" | 05, 06 |31| Prototype / animation / interaction | "animation effect", "click flow", "interaction draft" | 07, 08 |32| Diagrams / flowcharts | "SVG diagram", "deployment flow", "decision tree" | 10, 13 |33| Presentation / report / explainer | "slide deck", "weekly report", "incident postmortem", "concept explainer", "feature explainer" | 09, 11, 12, 14, 15 |34| Ad-hoc editors (rare) | "triage board", "feature flag editor", "prompt tuner" | 18, 19, 20 |3536### Layer 3 · Proposal phrasing3738When Layer 2 matches, propose with this format:3940> This content might work better as HTML (scenario: **{category}**, reference example **#{ID} {slug}**). Want me to generate the HTML and open it in your browser? (Reply "keep md" to stay on the original markdown plan.)4142- User agrees → enter the generation flow43- User declines ("keep md" / "no" / negative) → use markdown as originally planned. Lower the proposal frequency for the same category in this session.4445## Generation flow46471. **Learn the style first**: use the Read tool to open the matching example file `references/examples/NN-*.html`. Understand its layout, styling, and visualization logic.482. **Generate the HTML**: use the Write tool to write the complete HTML (with `<!DOCTYPE html>`, inline CSS, inline JS where needed) to `/tmp/<slug>.html`.49 - Do not link external CSS/JS libraries (unless the source example itself uses a CDN).50 - Prefer semantic tags (section/article/figure).51 - Use a sensible font stack appropriate to the content language.523. **Call render.sh**:53 ```bash54 bash ~/.claude/skills/prefer-html-output-en/scripts/render.sh /tmp/<slug>.html --scenario <key>55 ```56 `<key>` comes from the "Scenario keyword → ID quick lookup" table at the bottom of `references/scenario-map.md`.574. **Reply to the user**: a one-sentence confirmation that includes the final path (read from the script's stdout) and that the browser has been opened.5859## scenario key quick reference6061See the table at the bottom of `references/scenario-map.md` for the full list. Commonly used:6263- Weekly report → `weekly-report` (lands in `articles/YYYY-MM-DD/`)64- Incident postmortem → `incident-report` (lands in `articles/`)65- Concept explainer → `concept-explainer` (lands in `articles/`)66- Feature explainer → `feature-explainer` (lands in `articles/`)67- Slide deck → `slide-deck` (lands in `articles/`)68- Design comparison → `comparison` (lands in `temp/html-output/`)69- Implementation plan → `implementation-plan` (lands in `temp/`)70- PR review → `pr-review` (lands in `temp/`)71- Design system → `design-system` (lands in `temp/`)72- Flowchart → `flowchart` (lands in `temp/`)7374If unsure, omit `--scenario` (defaults to `temp/html-output/`).7576## render.sh parameters7778```79bash scripts/render.sh <html_file> [--scenario <key>] [--no-open] [--long-term]80```8182- `<html_file>`: required. Agent writes to `/tmp/` first.83- `--scenario <key>`: optional. Decides the destination folder.84- `--no-open`: optional, debug-only — skip launching the browser.85- `--long-term`: optional — force the file into `permanent/html/` (long-term storage).8687Output: the final absolute path on stdout (single line).8889All destination folders are created under the current working directory by default. The skill does not assume any project-specific layout.9091## Cautions9293- **Never generate HTML without explicit user consent.** This skill is propose → wait → execute by default.94- **Always read the matching example before generating.** This prevents stylistic drift and "HTML rendering" with poor results.95- **If the user declines, drop it.** Lower the proposal frequency for similar scenarios for the rest of the session.96- **Path decisions go through render.sh only.** Don't hand-roll `open` or `mv` — that bypasses the folder convention.
wechat-gggithub