plannotator/effective-html

HTML is a surprisingly good output format for agents. It renders immediately, carries its own layout and interactivity, and can represent almost any visual artifact — a wireframe, a diagram, a working prototype — without requiring a build step or a runtime. This repo formalizes that intuition into six discrete agent skills, each scoped to a specific kind of artifact and a specific fidelity level.

The design philosophy is worth examining. The skills deliberately separate two concerns that most agent prompting conflates: visual direction and structural reliability. Creative choices — color, tone, audience — come from the conversation. The skills themselves handle fidelity contracts: wireframes stay intentionally rough so reviewers don't fixate on aesthetics, prototypes implement one credible flow rather than every possible state, plans preserve the exact commitments from source material rather than paraphrasing them. That last point matters more than it sounds. Agents summarizing plans tend to quietly drop specifics; a skill that treats source commitments as inviolable is doing something genuinely different.

The routing architecture is also sensible. A broad html skill handles mixed requests and delegates to specialists. design-artifact provides a reusable creative process without locking in a house style — meaning the same skill can produce a dark-mode dashboard and a pastel landing page without either looking like a template. Specialist skills own their own fidelity rules independently, so you can install just html-wireframe without pulling in the whole collection.

Installation is optional and the README says so plainly. The repo is meant to be read as a reference first. The npx skills add command and the Claude Code and Codex plugin paths suggest this is designed for the current generation of agentic coding tools specifically, not general-purpose LLM prompting.

The constraint that every artifact must be responsive, accessible, self-contained, and browser-verified is doing real work. Self-contained is the key word — no external dependencies means the artifact survives being dropped into any context, shared as a file, or rendered in a sandboxed preview. That's the practical reason HTML beats a description or a screenshot for communicating structure to a coding agent: the agent can read it, modify it, and verify it in one pass.

Detailed guidance lives in the individual SKILL.md files linked from the README — the README is intentionally a routing layer, with each specialist skill owning its own fidelity rules. The project credits Thariq Shihipar's writing on HTML effectiveness as its direct inspiration.