solohtml

name

solohtml

description

Create explanation-oriented, presentation-oriented, or prototype-tuning single-file HTML artifacts from Markdown, newly drafted material, or prior chat answers. Use when the user asks to use HTML to present, visualize, explain, prototype, compare, or make content more readable/interactive, including "用 HTML 呈现", "md 转 html", "把回答生成 html", Exploration & Planning, Code Understanding, Research & Learning, Reports, Design, living design systems, component variants, and adjustable UI/animation prototypes. This is for self-contained HTML artifacts, not production websites/apps. Exclude code review findings unless the user separately asks for review.

solohtml

Core contract

Produce a portable .html file with inline CSS and JavaScript that clarifies the material better than Markdown alone. Choose HTML because it can combine structure, visual hierarchy, interaction, state, and copyable outputs in one artifact.

Keep outputs self-contained by default: no CDN, remote fonts, external JS, or external CSS unless the user explicitly allows it. Prefer semantic HTML, CSS variables, responsive layout, accessible controls, and Chinese UI copy when the user writes in Chinese.

This skill builds explanatory artifacts, visual documents, and parameter-tuning prototypes. Do not use it as a replacement for a production frontend skill when the user asks to build an app, website, deployable product, or framework codebase.

Source scenarios

Classify the request before writing HTML:

• A: Markdown exists. Read the referenced .md file or pasted Markdown. Preserve its claims, improve hierarchy, and convert the material into the most useful HTML pattern.
• B: No Markdown exists and the user wants source material created. Draft the Markdown first, save or present it for confirmation, and stop before HTML until the user confirms the content direction.
• C: No Markdown is needed. Convert the requested conversation content, prior answer, or newly requested explanation directly into HTML. If the exact prior answer is ambiguous, ask for the target message or summarize the assumed source before proceeding.

Output contract

Use deterministic file placement:

• A: Write the HTML next to the source Markdown as <source-slug>.html. Do not modify the source .md unless asked.
• B: Write or present <topic-slug>.md first. After user confirmation, write <topic-slug>.html beside it or in the requested output directory.
• C: Write html_outputs/<topic-slug>.html under the current workspace unless the user specifies a path.

Use short, descriptive lowercase slugs. Do not use generic names like output.html, page.html, or index.html unless the user requested that exact file.

Final responses should include only the important deliverable facts: source used, HTML path, validation result, and any verification that could not be completed.

Mode router

Map the user's goal to one primary type and only mix types when it improves the artifact:

• Exploration & Planning: Compare approaches, visualize decision tradeoffs, show implementation phases, risk checkpoints, and recommendation rationale.
• Code Understanding: Explain code, modules, repositories, data flow, call flow, ownership boundaries, and reading paths. Inspect the codebase before drawing conclusions. Do not include review findings or bug-risk lists unless explicitly requested.
• Research & Learning: Explain principles, concepts, mechanisms, or feature behavior with layered disclosure, diagrams, examples, and comprehension scaffolding.
• Reports: Present status, incidents, research findings, metrics, timelines, risks, decisions, and next actions with scan-first structure.
• Design: Turn abstract visual language into concrete directions, living design systems, tokens, layout rules, and component variants.
• Prototyping: Build adjustable HTML controls for UI, design, animation, or interaction tuning. Include sliders, segmented controls, presets, live preview, and one-click copy for parameters/prompts so the user can pass exact settings to an AI.

Read references/html-effectiveness-patterns.md when choosing structure or when the request mentions one of these types. Treat its recipes as the acceptance checklist.

Mode	Must include	Must avoid
Exploration & Planning	option/phase comparison, criteria, tradeoffs, recommendation	vague brainstorming with no decision surface
Code Understanding	module map, reading path, important files, flow explanation	review findings, severity labels, unverified architecture claims
Research & Learning	layered explanation, visual model, examples/non-examples, misconceptions	long essay dumped into a styled page
Reports	executive summary, evidence/metrics, timeline or status, next actions	decorative dashboards with no decision value
Design	tokens, visual direction, component anatomy, variants/states	static mood board with no usable system rules
Prototyping	live preview, controls, presets, reset, copy JSON/CSS/prompt	static screenshot-style design with no copyable parameters

Design language workflow

When visual style materially affects the result, read references/design-language-selection.md, select 3-5 suitable design directions, explain their expected look in plain language, and ask the user to choose before final HTML. Skip this stop only when the user already specified a style or explicitly asked for immediate output.

For non-design explainers, code understanding, and operational reports, choose a restrained default design and mention the choice briefly in the final response.

Build rules

• Start from the artifact's job, not from a generic template.
• Use layout as explanation: grids for comparisons, maps for systems, timelines for sequence, tabs/accordions for layered learning, controls for prototype variables.
• Include an explicit title, source note, and "how to use" only when necessary. Do not clutter the page with meta instructions.
• Use real controls for prototypes: input[type=range], radios, checkboxes, selects, color inputs, preset buttons, and copy buttons.
• Make copy/export panels machine-usable: include JSON, CSS variables, prompt text, or implementation notes that can be copied directly.
• Avoid decorative-only gradients, one-note palettes, oversized marketing heroes, nested cards, overlapping text, and viewport-scaled font sizes.
• Keep cards to repeated items, component examples, modals, or framed tools. Use full-width sections or unframed layouts for page structure.
• For code understanding, include clickable file references in the answer when relevant, but avoid hardcoding local absolute paths inside the exported HTML unless the user wants a local-only artifact.
• For Markdown conversion, keep the original .md unless the user asks to modify it.

Red flags

Stop and correct the artifact if any of these appear:

• Markdown was mechanically wrapped in HTML without changing comprehension.
• The page uses a marketing hero to present routine explanation, code understanding, or reports.
• The design is mostly decorative gradients, card mosaics, or one-note color variation.
• A prototype lacks adjustable controls, presets, or copyable parameters.
• The HTML changes factual claims from the Markdown or source answer to improve the story.
• Code Understanding silently becomes Code Review.
• The file depends on CDN assets without explicit permission.
• The final answer asks the user to manually verify something that can be checked locally.

Verification

Before claiming completion:

• Validate the skill or generated artifact with the cheapest reliable command available. For HTML artifacts, run python <skill-dir>/scripts/validate_html.py <html-file>; add --mode prototype for prototyping outputs.
• For generated HTML, check that the file exists, has a <title>, viewport meta, inline styles, and no obvious empty sections.
• If the HTML has interactions, open it in a browser or use Playwright/available browser tooling to verify that controls change the preview and copy actions work.
• If a dev server is unnecessary, give the local HTML path rather than starting one.

For this skill package itself, run quick_validate.py after edits and run python scripts/validate_html.py --self-test after script changes.