# Lucid

> Turn long, dense, or hard-to-follow responses into a tight chat summary PLUS a polished, single-file HTML artifact that holds the full depth and doubles as learning material. Use this skill PROACTIVELY whenever a reply is shaping up to be long or multi-part — explaining a concept or how/why something works, walking through code or describing what changed across files, laying out an implementation plan or architecture, comparing options/tradeoffs, or otherwise producing a wall of text the user would have to wade through. Trigger it even when the user does NOT say the word "artifact" — if the honest answer is "this is going to be a lot to read," reach for Lucid. Also trigger on explicit asks like "make this an artifact", "show me this visually", "this is too much text", "I can't follow this", "summarize this so I can actually understand it", or "turn your last answer into a page I can study." Do NOT use it for short, one-line answers, quick factual lookups, or simple confirmations; for a fast back-and-forth whe

- Skill: `shivadharmi/lucid` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add shivadharmi/lucid`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shivadharmi/lucid/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: shivadharmi (https://skillmd.com/u/shivadharmi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shivadharmi/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.