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.mdxindex 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 decisionsthat 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 coversThe 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.mdxindex 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 thingA layout discussion changes when reviewers can see the hierarchy at the target@@ -41,9 +69,9 @@ redirect.## Keep Markdown when it is enoughPrefer 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.<GuideHandoffartifactHref="/examples"