Coding agents answer in walls of markdown. When the answer has shape — a comparison, an architecture, a timeline, a review — that wall flattens it. htmlify is a skill family that makes agents ship designed, self-contained HTML instead: operator briefs, PR review packets, incident timelines, decision briefs, explainers, interactive boards, and full presentation decks with speaker notes. Zero dependencies, zero build step, one auditable file.

See it live: the gallery — every artifact there was generated by these skills, about this repository.

What's in the box

| Piece | What it is | | --- | --- | | skills/htmlify | Document skill — 10 modes: operator-brief, build-plan, implementation-map, pr-review-packet, release-brief, incident-report, decision-brief, status-report, explainer, prototype/editor | | skills/deckify | Deck skill — 6 modes: talk-deck, workshop-deck, essay-deck, demo-deck, launch-deck, teaching-guide; speaker notes, run-of-show, downloadable guide/PDF | | htmlify-answer CLI | Pipe any text into a designed artifact; validate any artifact against the rich/app/deck safety profiles | | Pi / OMP extension | /htmlify commands, render modes, browser annotation layer | | Claude Code plugin | One-command install of both skills, optional long-answer Stop hook | | Hardcopy | The design system every artifact ships in — engineering-plate language: warm paper, ink hairlines, serif display, mono metadata, one signal-orange accent |

Install

| Agent | Install | | --- | --- | | Claude Code | /plugin marketplace add zakelfassi/htmlify then /plugin install htmlify@htmlify | | Codex | git clone https://github.com/zakelfassi/htmlify.git ~/.htmlify && ln -sfn ~/.htmlify/skills/htmlify ~/.codex/skills/htmlify && ln -sfn ~/.htmlify/skills/deckify ~/.codex/skills/deckify | | Cursor / Windsurf | Clone the repo, point a project rule at skills/htmlify/SKILL.md / skills/deckify/SKILL.md | | Aider / anything | printf '%s' "$ANSWER" \| npx -y @zakelfassi/htmlify htmlify-answer --title "Review" | | Pi / Oh-My-Pi | pi install npm:@zakelfassi/htmlify |

Per-agent recipes, project rules, and hook setup: agent-integrations.md.

How it works

1. Evidence first. The skill reads the repo, git state, PRs, CI, and logs before designing anything; unverifiable claims are stamped needs verification.
2. One HTML file. Inline CSS+JS in the Hardcopy design language. No CDNs, no fonts, no analytics, no build.
3. Prove it. The bundled validator gates the output — then it opens in your browser.

npx -y @zakelfassi/htmlify htmlify-answer --validate artifact.html --profile auto

| Profile | Rules | | --- | --- | | rich | No scripts at all — for model-generated documents | | app | Inline scripts allowed (editors, boards); external scripts, on*= handlers, javascript: URLs still banned | | deck | app plus the deck contract: ≥2 slides, keyboard nav, speaker notes on substantive slides, print CSS | | auto | Detected per file from the document shape |

Exit codes: 0 valid · 1 validation errors · 2 usage/IO. Add --format json for agent consumption.

Artifact modes

| Mode | Use when | Live example | | --- | --- | --- | | operator-brief | What happened, what's next, risks, attention | operator-brief | | pr-review-packet | Motivation, diff tour, reviewer checklist | PR #1 packet | | incident-report | Impact, timeline, root cause, follow-ups | capture bug | | decision-brief | Options, tradeoffs, the call | monorepo decision | | implementation-map | Modules, data flow, hot path | runtime map | | explainer | Concepts, comparisons, glossary, FAQ | HTML vs markdown | | prototype / editor | Interactive triage, tuning, ordering — with export | launch board | | talk-deck (deckify) | Talks with speaker notes + run-of-show | launch talk | | workshop-deck (deckify) | Teaching with exercises + printable guide | skill workshop |

Plus build-plan, release-brief, status-report, and deckify's essay-deck, demo-deck, launch-deck, teaching-guide.

The Pi / OMP runtime (optional)

The npm package doubles as a Pi / Oh-My-Pi extension that captures long answers and exports them on demand:

| Command | Result | | --- | --- | | /htmlify | Quick local HTML of the last long answer (Hardcopy-styled, outline rail, annotation layer) | | /htmlify choose | Render-mode chooser — local, pi (current model second pass), gemini (Gemini CLI, falls back to local) | | /htmlify-comments <json> | Import browser review comments back to the agent as a structured prompt | | /htmlify-version | Show loaded version |

Legacy aliases (/html-last, /html-comments, /html-last-version) keep working. Exports include a trusted annotation layer: select text in the browser, comment, copy Markdown for the agent, or download a JSON bundle. Long answers stay visible in the terminal — export is always explicit.

For agents with hooks, the bundled Claude Code Stop hook archives answers past a threshold (HTMLIFY_MIN_CHARS, default 2500) to HTMLIFY_EXPORT_ROOT — opt-in, see agent-integrations.md.

Migrating from 0.x

1.0 restructures the repo into a skill family. Breaking: the root SKILL.md and references/ moved to skills/htmlify/; clones installed as a skill directory at the repo root must re-install:

ln -sfn /path/to/htmlify/skills/htmlify ~/.codex/skills/htmlify   # and skills/deckify

Unchanged: the htmlify-answer CLI flags and stdin behavior (--validate is additive), the hook path hooks/claude-code-stop-htmlify.js (existing settings.json entries keep working), the Pi/OMP entry points, all /htmlify commands, and the env vars (including the legacy PI_HTML_LONG_ANSWER_* aliases).

Development

corepack enable && pnpm install
pnpm test        # node --test, 35 tests
pnpm lint        # biome
pnpm typecheck   # strict tsc over JSDoc types
node bin/htmlify-answer.js --validate examples/htmlify/*.html examples/deckify/*.html --profile auto

The runtime is dependency-free CommonJS under src/ with strict JSDoc type checking — what ships is what you read. Releases are cut by release-please from conventional commits, published to npm with provenance. See CONTRIBUTING.md.

Trust and security

Extensions and hooks run with your user permissions — install from sources you trust and pin a ref when you need reproducibility. Model-generated HTML is treated as untrusted until validated: scripts (in the rich profile), event-handler attributes, javascript: URLs, external assets/CSS, meta refresh, and oversized output are rejected, with fallback to the local renderer. Interactive profiles still ban every external-execution vector. Found a way around the validator? That's a security report we want: SECURITY.md.

License

Apache-2.0 © Zak El Fassi