Lucid

Lucid

What this is for

People hit a wall when an assistant answers a real question with a long, unbroken stream of prose. The information might all be correct, but it arrives as an undifferentiated wall — no hierarchy, nothing to anchor on, no way to tell the load-bearing idea from the aside. The reader has to hold everything in their head at once. That is exactly the moment this skill exists for.

The fix is to split the response into two surfaces that each do one job well:

1. The chat reply stays short. A tight TL;DR plus the few takeaways that matter. Something the person can absorb in fifteen seconds and act on.
2. An HTML artifact carries the full depth. Everything you would have written in prose, but structured — headings, cards, collapsible detail, diagrams, and a learning layer that helps the concept actually stick.

The artifact is not a dumbed-down summary and it is not a transcript of the chat. It is the better version of the long answer: same substance, organized so a human can navigate it, scan it, and learn from it.

When to reach for it

Trigger whenever you notice the answer you are about to give would be long or have several moving parts. Concretely, that includes:

• Explaining a concept, mechanism, or "how/why does X work" question
• Walking through code, a function's logic, or what changed across files
• Laying out an implementation plan, system design, or sequence of steps
• Comparing options, weighing tradeoffs, or reasoning through a decision
• Design and UI work — proposing screens, comparing layouts, or showing states, where the mockup frames let you preview different UI views side by side
• Any reply where you catch yourself about to write five-plus dense paragraphs

The honest test is: "Would the user have to re-read this to follow it?" If yes, build the artifact. Don't wait to be asked — the whole point is to spare the person the wall of text in the first place. For genuinely short answers, skip it; an artifact there is just friction.

Skip it when the moment calls for a fast reply, not a document:

• A quick factual lookup, confirmation, or single yes/no.
• A fast back-and-forth where dropping a file mid-conversation breaks the rhythm.
• Code the user obviously wants inline to copy-paste right now.
• A single opinion, recommendation, or decision with little supporting structure.

When it's a close call, answer in chat. An unwanted artifact costs the reader a click and a context switch for nothing — under-triggering is the cheaper mistake.

The workflow

1. Write the chat reply tight

In chat, give:

• A one- to three-sentence TL;DR — the answer, stated plainly.
• 3–6 key takeaways as a short bullet list — the load-bearing points only.
• A single pointer line telling the user the full breakdown is in the artifact.

That is the whole chat message. Resist the urge to also paste the full explanation here — duplicating it defeats the purpose. The person who only reads chat should still come away correctly informed; the person who wants depth opens the artifact.

2. Build the artifact from the template

The file assets/template.html is a complete, single-file HTML shell with the theme, layout, components, and Mermaid wiring already in place. Copy it to your working/outputs directory, then fill in the content slots. Don't rebuild the CSS or re-derive the structure each time — the template exists so every artifact looks consistent and so you spend your effort on content, not plumbing.

Read references/content-patterns.md for how to structure the body depending on what you're explaining (concept vs. code vs. plan vs. general digest) and for the patterns that make an artifact teach rather than just inform.

A good artifact generally has, in this order:

• A title and one-line framing of what this page answers.
• "At a glance" cards — 3–5 dashboard-style tiles surfacing the highest-value facts (the key number, the verdict, the one thing to remember). This is what the reader sees first and it should stand on its own.
• The main explanation, broken into clearly headed sections. Use collapsible <details> blocks for depth the reader may or may not want, so the page stays scannable but nothing is lost.
• A diagram wherever structure, flow, or relationships are involved — a Mermaid flowchart, sequence, or tree usually beats a paragraph describing the same thing. Don't force one where it doesn't help.
• A "Make it stick" learning section — the mental model, the why-behind-the- what, a worked example, common pitfalls, or a couple of self-check questions. This is what turns a summary into study material and it's a first-class part of the artifact, not an afterthought.
• A short glossary or "key terms" block if you used jargon.

Keep it lightweight: the template uses inline CSS, loads two webfonts, and pulls in Mermaid from a CDN only when a diagram is present. Don't add other heavy libraries — fast load matters more than flourish.

The template ships a deliberate, research-backed look with a reader-facing theme selector (top-right): Dark and White. Both are monochrome — black/white canvas, opacity-based text, hairline strokes — with color reserved for links (underlined) and the semantic callouts. Type is Montserrat for text and Overpass for the uppercase letter-spaced labels. Diagrams sit in a framed container with a fullscreen-expand button and re-theme with the selector. The selector is remembered per reader. All of this is built into the template's CSS variables, so you don't manage themes yourself — just write content with the components and both themes render correctly. Don't hardcode colors or fonts in your content; let the theme variables do the work. The available components are .cards/.card (stat tiles — add .qual for a short word/phrase value instead of a number), .callout in info/good/warn/bad, <details class="drop"> (collapsibles), <div class="diagram"> wrapping a .mermaid block, .terms/.term (glossary), .qa (self-check), auto-styled <table>s, and — for design work — UI mockups (.mockups holding .frame.browser or .frame.phone device frames around a .screen preview canvas). Compose the page from these rather than inventing new styles; see references/content-patterns.md for tables and mockups.

You don't build navigation: when a page has three or more <h2> sections the template auto-generates an "On this page" nav with scrollspy (a floating left rail on wide screens), so just write good section headings. Keep the at-a-glance cards and the learning layer regardless of length.

The template is one file but not fully offline. Fonts, syntax highlighting, and Mermaid load from CDNs at runtime; the page degrades gracefully without a connection (code shows unstyled, a diagram shows its source) but isn't truly self-contained. Describe it as "a single HTML file" — don't promise it works with no network.

3. One page by default; split only when it's genuinely big

A single file with the auto-built "On this page" nav handles almost everything, including long topics — the nav and collapsible drops keep a long page navigable. Reach for multiple linked files only past a real size threshold: roughly when you'd otherwise have four or more heavy <h2> sections that each need their own sub-sections, diagram, or code — i.e. a page so long the TOC itself gets unwieldy. Most answers never hit this; prefer one page when in doubt.

When you do split, give each page the full template (its own hero, cards, learning layer) and wire them together with the multi-file nav: a .sitenav row of page tabs at the top of every page (mark the current one .here) and a .pagenav prev/next pair at the bottom. Tag every internal link class="page-link" so the reader's theme choice follows them across pages. Name the files as a set (extract-user-service-1-overview.html, -2-data-model.html, …) and present the overview/index page. See references/content-patterns.md for the split pattern.

4. Verify before you present

The template ships with placeholder SLOT comments, demo cards, and a demo diagram. Before presenting, confirm none of that leaked through and the page actually renders. Quick gate:

• No leftovers. Grep the file for SLOT and for the demo content (A[Start], Path 1, Decision) — there should be zero matches. Every card, heading, and diagram is real content.
• Diagrams parse. Validate each Mermaid block (a validate_and_render_mermaid_diagram tool, if available, is the fastest check; otherwise eyeball it against the gotchas in references/content-patterns.md). A broken diagram now falls back to showing its source instead of a blank frame, but a clean render is the goal.
• Chat isn't a duplicate. The full prose lives in the artifact, not also in chat.

5. Save and present it

Save the artifact as a .html file in the outputs directory with a descriptive, kebab-case name (e.g. how-jwt-auth-works.html, payment-refactor-walkthrough.html). Then present it to the user with the present_files tool so they get a clickable card. If present_files isn't available, tell them the file path.

What good looks like

A reader should be able to:

• Get the gist from the chat reply alone, without opening anything.
• Open the artifact and, within a few seconds, know the verdict / key facts from the at-a-glance cards.
• Scan headings to find the part they care about, expand only what they need.
• Come away understanding why, not just what — because the learning section gave them a model to hang it on.

Avoid:

• Pasting the full prose into chat and the artifact (pick one home for depth — the artifact).
• An artifact that's just the wall of text with a background color. Structure is the entire value; if it isn't navigable and scannable, it hasn't done its job.
• Diagrams that restate a sentence. Use them for genuine structure, flow, or comparison.
• Heavy frameworks or anything that won't open instantly from a local file.

Quick reference

• Template shell: assets/template.html — copy, then fill the slots.
• Content structure + learning patterns: references/content-patterns.md.
• Output: one .html (single file; loads fonts/highlighting/Mermaid from CDNs), kebab-case name, in outputs, shown via present_files. Verify first: no SLOT or demo content left, diagrams parse.
• Chat stays short: TL;DR + 3–6 takeaways + pointer. Depth lives in the artifact.