html-artifacts

A Claude skill that switches output from markdown to a single self-contained HTML file when the deliverable is spatial, comparative, interactive, or long-lived.

Based on Thariq Shihipar's The unreasonable effectiveness of HTML (https://thariqs.github.io/html-effectiveness/).

What it does

When you ask Claude for an implementation plan, a code review, a design exploration, a status report, an explainer, a post-mortem, a prototype, or a throwaway editor, this skill makes Claude produce an .html file you can open, scan, and share, instead of a 600-line markdown wall.

A built-in decision prompt tells Claude when HTML wins and when to stay in markdown.

Install

Claude Code (per-user)

mkdir -p ~/.claude/skills/html-artifacts
cp SKILL.md ~/.claude/skills/html-artifacts/SKILL.md

Restart your Claude Code session. The skill loads automatically when its description matches your prompt.

Claude Code (per-team or per-repo)

Drop SKILL.md into your team's skills repo (e.g., your-org/agent-skills) under skills/html-artifacts/SKILL.md. Distribute via npx skills or your preferred installer.

claude.ai (web or desktop)

claude.ai does not load skill files directly. Use the global decision prompt instead:

1. Open decision-prompt.md.
2. Copy the section between the --- markers.
3. Paste into Settings → Profile → Personal Preferences (or into a Project's custom instructions).

This gives Claude the same decision logic as a skill installation. It does not give Claude the full SKILL.md body, but the decision prompt is the part that changes behavior most.

API / system prompt

Paste the section from decision-prompt.md into your system parameter. Pair with Anthropic API artifacts or write the HTML to a file in your application code.

Project skill (claude.ai Projects)

If you want the full SKILL.md scoped to one Project, paste the SKILL.md body (everything below the frontmatter) into the Project's instructions field.

Files

File	Purpose
SKILL.md	The full skill. Use in Claude Code or paste into Project instructions.
decision-prompt.md	A condensed pasteable version of the decision logic. Use in claude.ai User Preferences, API system prompts, or CLAUDE.md.
index.html	The landing page. Demonstrates the skill on itself. Hosts at https://omerakben.github.io/html-artifacts/ once GitHub Pages is enabled.
evals.json	Test prompts for triggering accuracy. Useful if you want to evaluate or iterate on the description.
README.md	This file.

Publish the landing page

After pushing the repo, enable GitHub Pages:

# Settings → Pages → Source: Deploy from a branch → main / (root)
# Or via the gh CLI:
gh api repos/omerakben/html-artifacts/pages -X POST -f source[branch]=main -f source[path]=/

Wait two minutes. The page will be live at https://omerakben.github.io/html-artifacts/. That URL is the link to put in the tweet.

Sharing

The skill is a single Markdown file with no executable code, no network calls, and no dependencies. To share, link to the repo or paste the SKILL.md content directly.

A short version for social posts:

Got tired of agents producing 600-line markdown plans I never reread. Built a Claude skill that switches to a single self-contained HTML file when the deliverable is spatial — implementation plans, post-mortems, design systems, prototypes, status reports. Has a built-in markdown-vs-HTML decision prompt you can paste into User Preferences for any Claude session. Pattern credit: Thariq Shihipar (https://thariqs.github.io/html-effectiveness/).

Verifying the skill triggers

Try these prompts in a session that has the skill installed. The first three should produce HTML files. The last three should stay as markdown or chat replies.

Should produce HTML:

1. "Write me an implementation plan for migrating our Selenium tests to Playwright."
2. "Explain how rate limiting works in this repo."
3. "Compare three approaches for handling auth in our app."

Should stay in markdown:

4. "What's the difference between useMemo and useCallback?"
5. "Fix this typo on line 42."
6. "Write a haiku about deployment day."

If any of the first three return markdown, the skill is undertriggering — open SKILL.md and make the description more pushy on the matching trigger phrase. If any of the last three return HTML, the skill is overtriggering — tighten the negative-trigger list.

License

Pattern: Thariq Shihipar (CC0 / treat as inspiration). Skill text: do whatever you want with it.