mirror of
https://github.com/plannotator/effective-html.git
synced 2026-09-19 01:11:19 +08:00
Michael Ramos
91 lines
3.5 KiB
Plaintext
91 lines
3.5 KiB
Plaintext
---
|
|
title: Why HTML?
|
|
description: Use visible structure when dense prose makes agent work harder to understand.
|
|
---
|
|
|
|
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
|
|
width. A behavior discussion changes when they can operate the control. A
|
|
system discussion changes when relationships occupy a shared visual field.
|
|
|
|
The artifact reduces translation work between an agent's description and a
|
|
human's judgment.
|
|
|
|
## HTML can hold multiple forms of evidence
|
|
|
|
A single page can combine:
|
|
|
|
- prose that explains the constraint;
|
|
- a wireframe that exposes the hierarchy;
|
|
- a diagram that clarifies the relationship;
|
|
- a control that demonstrates the state change;
|
|
- an annotation that names the unresolved decision.
|
|
|
|
That combination is valuable when each form contributes something different.
|
|
It becomes noise when HTML is used only to decorate information that would be
|
|
clearer as a short document.
|
|
|
|
## HTML can be reviewed as a real boundary
|
|
|
|
A self-contained artifact can be opened at real viewport sizes, navigated with
|
|
a keyboard, inspected for contrast, and tested in loading, empty, failure, and
|
|
success states. Those checks turn a proposal into something concrete enough to
|
|
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 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"
|
|
artifactLabel="Open the examples"
|
|
artifactDescription="Inspect the release-readiness wireframe and prototype."
|
|
sourceHref="https://github.com/plannotator/effective-html"
|
|
skillHref="https://github.com/plannotator/effective-html/blob/main/skills/html/SKILL.md"
|
|
skillLabel="Use the HTML router"
|
|
skillDescription="Decide whether HTML adds useful evidence before building."
|
|
/>
|
|
|
|
<GuideNext
|
|
href="/docs/choosing-fidelity"
|
|
title="Choose the lowest useful fidelity"
|
|
description="Match the artifact's finish to the decision being made now."
|
|
/>
|