plannotator/effective-html: HTML Artifact Skills for Coding Agents
Agent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.
At a glance
- What is it?
- Effective HTML is a collection of six agent skills that push coding agents toward self-contained HTML wireframes, prototypes, plans and diagrams. It is a reference collection first and an installable skill set second, and its value depends on whether your agent already writes HTML well.
- Who is it for?
- Adopt it if your agent already produces HTML but the artifacts come out over-designed, half-interactive, or structured as walls of text, and you want wireframes, prototypes, plans and diagrams handled with different rules. Skip it if your workflow is Markdown-only, or if you expect the skills to substitute for a design review you are not doing.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly HTML, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What effective-html is for, and who it is aimed at
Coding agents are good at producing text and mediocre at producing visual artifacts that survive review. A layout question asked in prose gets answered in prose, and the answer is hard to argue with because nobody can see it. Effective HTML addresses that by giving an agent a set of written rules for producing HTML files that stand on their own: a wireframe, an interactive prototype, a plan, a diagram. The repository describes the goal as "useful, self-contained HTML artifacts, from low-fidelity wireframes to working interactive prototypes."
The intended user is someone working with an agent that has file-writing tools and a browser. The README frames the working style as "fat artifacts + fat context": instead of pasting a long explanation into the prompt, you point the agent at artifacts, repositories and folders, and let an HTML file carry the meaning. That is a workflow claim as much as a tooling claim, and it only pays off if the people reviewing the artifact actually open it.
The README is explicit that installation is optional. It says you can use the repository without installing anything, treating it as "a reference first and an installable skill collection second." That ordering matters for evaluation: the six SKILL.md files are readable documents, and you can judge them before you commit to wiring them into an agent.
Six skills, and the routing rule that keeps them apart
The collection is six skills, each with its own SKILL.md. The broad one is html, described as covering "broad HTML requests, mixed artifacts, reports, explainers, presentations, landing pages, tools, and routing to a specialist." The five specialists split by fidelity and by artifact type: design-artifact for creative direction, html-wireframe for low-fidelity layout, html-prototype for working interaction, html-plan for plans and roadmaps, html-diagram for architecture, sequence, process, state, hierarchy, timeline and system diagrams.
The design decision worth noting is how the collection avoids imposing a house style. The README states that design-artifact "provides a reusable design process without prescribing a reusable look," and that visual direction comes from "the conversation, project, audience, and subject." That is the opposite of a component library. It means two artifacts produced under the same skill can look nothing alike, which is right for client work and awkward if you wanted consistency across a documentation set.
The routing logic is layered rather than flat. The html skill routes the work, design-artifact supplies optional creative direction, and the specialist skills own fidelity and behavior. The README also says each skill "remains independently usable," so you can install html-wireframe alone without dragging in the rest of the collection. Detailed guidance is kept only where it is needed, which is a deliberate contrast with the single giant system prompt approach.
Install and a first real use
The README gives one install path for the whole collection and one for individual skills. The npx command below installs every skill into your agent's skill directory; the README does not document an uninstall or rollback command, so if you want a reversible trial, start with the single-skill form instead.
npx skills add plannotator/effective-htmlTo see what the collection contains before installing anything, the README gives a listing flag. Run it first if you are not sure which of the six you want.
npx skills add plannotator/effective-html --listIndividual skills install with --skill and the skill name. The README shows design-artifact, html-wireframe and html-prototype as examples, and the same pattern applies to the other names in the table.
npx skills add plannotator/effective-html --skill html-wireframeIf you use Claude Code, the README documents a plugin marketplace route instead of npx. Both lines are typed into the Claude Code prompt, not the shell.
/plugin marketplace add plannotator/effective-html
/plugin install plannotator-effective-html@effective-htmlFor Codex, the equivalent is a plugin subcommand pair. Note that the first argument is a repository path and the second is the plugin identifier, which is not the same string.
codex plugin marketplace add plannotator/effective-html
codex plugin add plannotator-effective-html@effective-htmlA first real use: with html-wireframe installed, ask your agent for a low-fidelity layout for a settings page and say explicitly that it is a wireframe. The skill's purpose is to keep the output "intentionally unfinished so reviewers focus on structure," so expect grey boxes, placeholder labels and no color decisions. If you get a polished mockup instead, the skill did not take effect and you are looking at the agent's default HTML behavior. The repository ships an example directory at examples/release-readiness/ that is worth opening in a browser before you prompt, so you know what the output is supposed to look like.
Where the collection draws hard lines, and where it does not
The clearest rule in the README concerns prototypes: they "implement one credible flow and its relevant states." One flow, not a tour of the product. That is a real constraint and a useful one, because agents asked for a prototype tend to produce a navigation shell with every link dead. The same paragraph requires keyboard support and responsive behavior, so the prototype is expected to be operable rather than a screenshot with hover effects.
Plans get a different rule: they "preserve source commitments." Read plainly, that means a plan artifact should not quietly drop or reword requirements that came from the original request. This is the kind of instruction that is easy to write and hard to enforce, and the README does not explain how an agent is meant to verify that it complied.
Diagrams are told to "choose a visual model and rendering method that fit the relationship being explained." That leaves the choice open, which is honest but also means quality depends on the agent's judgment about whether a sequence is better drawn as a sequence diagram or a numbered list. The README does not commit to a diagramming library or an output format beyond self-contained HTML.
Across all six, the stated baseline is that every artifact is "responsive, accessible, self-contained, and verified in a browser." Self-contained is the load-bearing word: no external assets, no build step, one file you can open or send. Verified in a browser is the part you should not take on faith, since it is a claim about what the agent did, not a property of the file.
The limitation: skills shape output, they do not check it
Nothing in the repository runs a linter over the generated HTML. The skills are instruction documents, and an agent that ignores an instruction produces a bad artifact that still looks like a successful run. The README's own list of requirements, responsive, accessible, self-contained, verified in a browser, is precisely the set of properties that are easy to claim and tedious to confirm by hand.
Accessibility is the sharpest example. A skill file can tell an agent to use semantic elements and keyboard handlers; it cannot tell you whether the tab order in the finished prototype is sane. Someone has to open the file and press Tab. If your team has no one doing that, the accessibility line in the README is aspirational for your project regardless of what the skill says.
There is a second limitation in the design-artifact skill's deliberate refusal to prescribe a look. That is good for bespoke work and bad if you wanted a set of artifacts that feel like they came from one product. There is no theme file, no token set, and no shared stylesheet mentioned in the repository layout. Consistency across artifacts is left to the conversation, which means it is left to whoever is prompting that day.
Finally, the collection is aimed at HTML artifacts specifically. If your deliverable is a Markdown RFC, a spreadsheet, or a slide deck in a proprietary format, these skills do not address it, and the README does not present them as a general documentation system.
Alternatives and the actual difference in approach
The obvious comparison is a plain system prompt or a project-level instruction file that tells your agent how to write HTML. That approach is one document you control, and it can be as short or as long as you like. The difference here is decomposition: effective-html splits the problem into routing, creative direction, and fidelity-specific rules, and each piece is independently installable. You get narrower instructions per task, at the cost of six files to read and keep in sync with your own conventions.
The README also points to two companion tools rather than competitors. Plannotator, at github.com/backnotprop/plannotator, renders and annotates local HTML, which addresses the review step that the skills themselves do not cover. tot, at github.com/plannotator/tot, creates a shareable link for an HTML file, which addresses distribution. Both sit outside this repository and are linked rather than bundled, so using effective-html does not require either.
A third reference point is the essay the README cites as inspiration: Thariq Shihipar's "The unreasonable effectiveness of HTML." That piece argues for HTML as a communication medium; effective-html is the operational version, turning the argument into per-task instructions. If you agree with the essay but your agent's output is still unusable, the skills are the missing layer. If you disagree with the essay's premise, no amount of skill files will help, because the whole collection assumes artifacts are worth opening in a browser.
Maintenance, cost and licence
The repository is not archived, and the last push was on 2026-09-14, three days before this writing. There are no releases retrieved, so there is no version number to pin and no changelog to read. Upgrades are therefore pull-based: re-running the npx skills add command or the plugin install command is how you would pick up changes, and the README does not describe a versioning scheme or a migration path for skill files that change shape.
The practical upgrade cost is small but not zero. Because the skills are Markdown instructions rather than code, a change to a SKILL.md can alter your agent's behavior on the next run without any dependency resolution telling you something moved. If you fork or edit the skill files to match your conventions, you own the merge.
The licence is MIT, stated in the repository and in the LICENSE file at the top level. That is permissive and imposes no obligations on how you use the skill files in your own projects. This is a description of the licence identifier, not legal advice; if you are redistributing the files or the assets/ directory, read the LICENSE text yourself. The repository also ships a README.zh.md, so the documentation exists in both English and Simplified Chinese, and translations of the skill files are not mentioned in the layout.
Editorial conclusion
Adopt it if your agent already produces HTML but the artifacts come out over-designed, half-interactive, or structured as walls of text, and you want wireframes, prototypes, plans and diagrams handled with different rules. Skip it if your workflow is Markdown-only, or if you expect the skills to substitute for a design review you are not doing. Before installing, open skills/html/SKILL.md and skills/html-prototype/SKILL.md and check that the fidelity rules match what your team means by a prototype, because that word is where the collection draws its sharpest line.
Frequently asked questions
Is HTML still useful today?
The repository's premise is that it is, specifically as a medium for agent output: HTML can visualize almost anything, often more clearly than a wall of text, and a prompt can point at artifacts instead of restating context. The skills exist to make that output self-contained and reviewable rather than decorative.
Is HTML better than Markdown?
The README does not frame it as a contest. It argues that HTML artifacts carry visual meaning that prose struggles with, while the collection's own plan skill targets plans and roadmaps, which are conventionally text documents. The choice depends on whether the reader benefits from seeing structure rather than reading it.
What is HTML useful for in this project?
The six skills cover broad HTML requests, creative direction, low-fidelity wireframes, working prototypes, plans and roadmaps, and diagrams for architecture, sequence, process, state, hierarchy, timeline and system relationships. Every artifact is meant to be responsive, accessible and self-contained.
What's harder, HTML or Python?
The repository does not compare the two languages. What it does say is that the hard part of its own artifacts is not syntax but the rules around them: one credible flow per prototype, plans that preserve source commitments, and diagrams whose visual model fits the relationship being explained.
Community notes