plannotator/effective-html: Six Agent Skills for HTML Wireframes, Prototypes, and Diagrams

The Problem: AI Agents Produce Inconsistent HTML Artifacts

When an AI coding agent generates an HTML artifact without specific guidance, it makes a series of implicit decisions: the level of fidelity, the visual style, the layout structure, the interaction model, and whether the output is meant to be a rough sketch or a working prototype. Those implicit decisions often do not match what the developer or designer wanted, and correcting them requires iterating through multiple rounds of prompts.

effective-html addresses this by providing six agent skills that encode explicit, specialized guidance for each major type of HTML artifact a coding agent might be asked to produce. Each skill tells the agent what the output should and should not do, how fidelity should be calibrated, what constraints apply, and what the receiver of the artifact needs from it. The result is a more predictable output on the first attempt, with less back-and-forth.

The README describes the approach this way: visual direction comes from the conversation, project, audience, and subject, while the skills handle reliability. This separation is what distinguishes effective-html from writing a generic prompt that asks for "a good wireframe": the skill defines what good means for that specific output type, while the conversation defines what the artifact is about.

The collection was inspired by Thariq Shihipar's essay "The unreasonable effectiveness of HTML," which argues that HTML can visualize almost anything more clearly than a wall of text and that modern AI models benefit from being given rich HTML context. effective-html builds on that premise by providing structured skills that make HTML generation more reliable.

The Six Skills and What Each One Does

The html skill is the broad entry point. It handles mixed artifact requests, reports, explainers, presentations, landing pages, and tools, and it also routes work to a specialist skill when the request is more specific. Think of it as the default handler that escalates to the right specialist.

The design-artifact skill provides creative direction for any HTML artifact without imposing a reusable house style. It gives the agent subject-specific visual guidance while leaving the design language to be determined by the context of each request. This is intentionally stateless: it does not try to enforce brand colors or typography across multiple outputs.

The html-wireframe skill produces low-fidelity layout directions. The README specifies that wireframes should stay intentionally unfinished so that reviewers focus on structure, content hierarchy, navigation flow, and responsive behavior rather than being distracted by visual polish. A wireframe produced with this skill should not look like a finished design.

The html-prototype skill produces working prototypes with realistic states, interaction, keyboard support, and responsive behavior. Unlike the wireframe skill, this one aims for something that looks and behaves like a real application flow, implementing one credible flow and its relevant states rather than a complete feature set.

The html-plan skill handles plans, roadmaps, rollouts, and implementation sequences. Its specific constraint is that it must preserve source commitments: if a plan is derived from a requirements document or a specification, the output must not silently reinterpret or omit commitments made in the source.

The html-diagram skill covers architecture, sequence, process, state, hierarchy, timeline, and system diagrams. Each diagram type has its own visual model and rendering method; the skill selects the approach that fits the relationship being explained rather than defaulting to a generic box-and-arrow style.

Installing the Skills and Available Plugin Formats

The collection installs in one command. The README gives the standard install:

npx skills add plannotator/effective-html

Individual skills can be listed and installed separately:

npx skills add plannotator/effective-html --list
npx skills add plannotator/effective-html --skill html-wireframe
npx skills add plannotator/effective-html --skill html-prototype

For Claude Code specifically, the plugin format uses the slash command interface:

/plugin marketplace add plannotator/effective-html
/plugin install plannotator-effective-html@effective-html

For Codex:

codex plugin marketplace add plannotator/effective-html
codex plugin add plannotator-effective-html@effective-html

The README also notes that you can use the repository without installing anything at all, treating it as a reference first. The skill files in skills/ describe the guidance in a format you can read and adapt into your own prompts. This makes the repository useful even in agent environments that do not yet support the skills protocol.

The Design Principles Behind the Skills

The README describes several design choices that appear across all six skills. Every artifact produced by any skill must be responsive, accessible, self-contained, and verified in a browser. Self-contained means a single HTML file with no external dependencies that need to be served separately.

The skills separate creative freedom from reliability. Visual direction, tone, and subject matter come from the conversation and project context. The skills handle the constraints that apply regardless of content: what fidelity level means for this artifact type, what the receiver needs to be able to evaluate, and what a browser needs to render it correctly.

Wireframes stay unfinished deliberately. The README frames this as a feature: when a wireframe looks polished, reviewers comment on the visual design instead of the content structure and user flow. Keeping wireframes rough forces the review conversation to stay at the right level of abstraction.

Prototypes implement one credible flow. This is a constraint against scope creep: an agent asked to build a complete feature prototype will often produce something that looks complete but handles only the happy path. The html-prototype skill aims for a working implementation of one flow with its actual states, including error and loading states, rather than a facade that only covers the success case.

Using effective-html with Plannotator and tot

The README mentions two companion tools that extend the workflow. Plannotator is a separate tool for rendering and annotating local HTML files. With Plannotator, a developer can open an HTML artifact produced by an agent, annotate it directly in the browser, and use those annotations as context for further refinement. The Plannotator repository is at github.com/backnotprop/plannotator.

The tot tool creates a shareable link for a single HTML file. After an agent produces a prototype or wireframe, tot makes it accessible to collaborators without requiring a deployment. The tot repository is at github.com/plannotator/tot.

Neither tool is required to use effective-html. They extend the workflow for teams that want a full review-and-share loop around their HTML artifacts, but the skills themselves work without them.

The effective-html guide at effectivehtml.com provides additional documentation and practical guidance. The README points there for users who want more context on how to use the skills in different agent environments.

Limitations and When to Use a Different Approach

effective-html does not provide a reusable design system. The design-artifact skill explicitly avoids prescribing a house style, which means two different artifacts produced with the skill will not share fonts, colors, or component patterns unless the conversation explicitly establishes those constraints each time. Teams that need consistent visual branding across multiple AI-generated artifacts need to provide that context themselves or maintain a separate design token document that they reference in each conversation.

The skills also do not generate production-ready code. The html-prototype skill produces a working prototype, not deployable application code. It implements one flow for review purposes. Turning a prototype into a real application requires additional development work beyond what the skill produces.

A broadly comparable approach is providing the agent with a Storybook component library or a Figma component kit as context, rather than HTML skills. Those approaches ground the agent's output in an existing design system, which is stronger when brand consistency is required. effective-html is better suited for early-stage wireframing and diagramming where no design system has been established yet, or for documentation artifacts where visual consistency matters less than communicating a structure or flow clearly.

The repository is maintained under the MIT license. The last push was on 2026-09-14, consistent with active maintenance.

Editorial conclusion

effective-html is the right choice for development teams that use AI coding agents and want consistent, structured HTML outputs rather than one-off improvised artifacts. The six skills cover distinct output types and can be installed individually, so a team that only needs wireframes and diagrams does not have to adopt the full collection. For agents that do not support the skills protocol, the repository also works as a reference: the skill files describe the design principles directly and can inform prompts without any installation. The last push was on 2026-09-14, and the MIT license permits modification, so teams can fork and adjust the skills for their own house standards.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. plannotator/effective-html on GitHub
4. Project website
5. README