Skip to content

Agent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.

Clarify the guide's artifact-first position (#18)

Michael Ramos001d6a972edb
diff --git a/site/content/docs/index.mdx b/site/content/docs/index.mdx
index c498040..d326c57 100644
--- a/site/content/docs/index.mdx
+++ b/site/content/docs/index.mdx
@@ -1,10 +1,26 @@
---
title: Effective HTML guide
-description: Choose and create useful HTML artifacts for work with coding agents.
+description: Use context-rich HTML artifacts to understand, review, and direct agent work.
---
-HTML is useful with agents for the same reason it is useful everywhere else: it
-can combine structure, visual form, and interaction in one inspectable thing.
+Effective HTML is a field guide to making visual, interactive artifacts with
+agents. It is for developers and for anyone who needs to understand, review, or
+direct agent work.
+
+## Start without a skill
+
+You do not need to install a skill to use these patterns. Ask an agent to make
+an HTML artifact, provide the source context and the decision it needs to
+support, then review the result.
+
+The working bias is **fat artifacts and source context; thin prompts and
+skills**. Put the detail in the artifact: realistic content, constraints,
+annotations, states, and interactions. Use a skill when a pattern recurs or a
+team needs shared defaults. Once the pattern is familiar, the skill may stop
+adding value.
+
+HTML is useful with agents because it can combine structure, visual form, and
+interaction in one inspectable thing.
The point is not to replace Markdown. The point is to recognize the decisions
that become easier when the artifact can show layout, compare alternatives,
@@ -36,7 +52,21 @@ fidelity that answers the current question without creating a new distraction.
## What this guide covers
The guide covers wireframes, prototypes, diagrams, browser-native decks, and
-plans. The examples stay inspectable and source-grounded.
+plans. The examples stay inspectable and source-grounded. They demonstrate the
+patterns; they are not prerequisites for using them.
+
+## Where this guide comes from
+
+This guide organizes and extends public practices shared in Thariq Shihipar's
+[Claude Code article about effective
+HTML](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html)
+and its [example gallery](https://thariqs.github.io/html-effectiveness/),
+Geoffrey Litt's work on [understanding as the new
+bottleneck](https://www.geoffreylitt.com/2026/07/02/understanding-is-the-new-bottleneck),
+and projects such as [Frontend
+Slides](https://github.com/zarazhangrui/frontend-slides). They share a practical
+idea: agents can produce artifacts that help people inspect, understand, and
+participate in the work.
Continue with [why HTML](/docs/why-html), or go directly to
[choosing fidelity](/docs/choosing-fidelity).
diff --git a/site/content/docs/why-html.mdx b/site/content/docs/why-html.mdx
index c30b1b9..561949f 100644
--- a/site/content/docs/why-html.mdx
+++ b/site/content/docs/why-html.mdx
@@ -1,13 +1,41 @@
---
title: Why HTML?
-description: Use HTML when the medium makes the decision easier to understand.
+description: Use visible structure when dense prose makes agent work harder to understand.
---
-Markdown is excellent for linear explanation. HTML becomes more useful when
-space, comparison, state, or participation carry part of the meaning.
+Effective HTML helps people understand and participate in agent work. That
+includes developers reviewing code and non-technical collaborators responding
+to a plan, prototype, report, diagram, or explainer.
+
+Markdown remains useful for linear explanation, short plans, and source-grounded
+lists. The problem is not Markdown. The problem is asking dense prose to carry
+information that would be clearer through space, comparison, state, or
+interaction.
<GuideChapterEvidence chapter="why-html" />
+## Put the detail in the artifact
+
+Give the agent the relevant source context and name the decision a person needs
+to make. Keep the prompt direct. Let the artifact carry the working detail
+through realistic content, visible relationships, annotations, controls, and
+states.
+
+The skills in this repository teach recurring patterns and provide useful
+defaults. They are optional. Once you recognize what a useful artifact looks
+like, a direct request may be enough. Add a skill when repetition or consistency
+justifies one.
+
+## Use less prose when structure can explain
+
+Agents can produce more written material than people will read. A well-structured
+visual can communicate hierarchy, alternatives, state, and relationships
+without requiring someone to parse a long document first.
+
+This is often useful when technical teams share work with non-technical
+collaborators. A wireframe, diagram, or working prototype gives everyone the
+same thing to point at, question, and revise.
+
## HTML can show the thing
A layout discussion changes when reviewers can see the hierarchy at the target
@@ -41,9 +69,9 @@ redirect.
## Keep Markdown when it is enough
Prefer Markdown for a linear plan, short explanation, or source-grounded list
-of commitments unless visual or interactive structure adds meaningful
-leverage. HTML is not the default. It is a medium chosen for a particular kind
-of understanding.
+of commitments unless visual or interactive structure makes the work easier to
+understand. Choose HTML for the decisions it can expose, not because every
+agent output needs a webpage.
<GuideHandoff
artifactHref="/examples"