effective-html: Bộ Skill Tạo HTML Plan và Diagram Đẹp Cho AI Agent

TL;DR

effective-html là bộ 3 agent skill mã nguồn mở do Plannotator phát triển, giúp AI agent như Claude Code hay Codex tạo ra HTML deliverable tự chứa, có tính trực quan cao - thay vì Markdown phẳng truyền thống. Ba skill gồm html, html-diagram, html-plan, cài đặt chỉ với một lệnh npx skills add plannotator/effective-html. Mỗi skill bundle sẵn kho ví dụ html-effectiveness do kỹ sư Anthropic Thariq Shihipar xây dựng, cho phép model tham chiếu offline mà không cần search web. MIT license, hỗ trợ Claude Code, Codex và hơn 10 agent khác qua hệ sinh thái Plannotator.

Markdown Không Còn Đủ Cho AI Agent Output

Từ thuở GPT-4 ra đời với context window 4K-8K token, Markdown trở thành format mặc định cho AI agent vì lý do đơn giản: tiết kiệm token. Nhưng với Claude hiện tại hỗ trợ đến 200K-1M token, lý do đó không còn valid.

Vấn đề thực sự sâu hơn: Markdown linearize mọi thứ. Diff và call-graph vốn là dữ liệu không gian bị ép thành danh sách phẳng. Khi agent output một code review dưới dạng Markdown, reviewer phải tự reconstruct cấu trúc trong đầu - xem file nào thay đổi, severity ở đâu, flow đi như thế nào. Với HTML, tất cả thông tin đó có thể được hiển thị trực quan: side-by-side diff với color-coded severity, jump link theo file, architecture map với call path được highlight.

Thariq Shihipar - kỹ sư làm việc trên Claude Code tại Anthropic - đã chứng minh điều này bằng 20 HTML artifact tự chứa, trải dài 9 loại công việc: code review annotated, design system pages, architecture diagrams, interactive prototypes, research maps, approval queues và custom editors. Luận điểm của ông đặc biệt sắc bén ở một điểm: "Motion và interaction không thể mô tả, chỉ có thể cảm nhận." Một prototype với easing curve thực và luồng bấm được truyền đạt trong vài giây điều mà một đoạn prose không bao giờ làm được.

Thêm vào đó, với các team dùng design system, HTML là medium mà hệ thống đó đã vận hành. Route output qua Markdown tạo ra một bước dịch lossy không cần thiết - vừa mất fidelity, vừa tốn thêm công.

So sánh Markdown vs HTML làm output cho AI agent — Markdown linearize thông tin không gian thành danh sách phẳng. HTML giữ nguyên layout, hierarchy và tương tác. Cùng một dữ liệu, khác hoàn toàn về khả năng inspect và ra quyết định.

effective-html Là Gì và Cách Hoạt Động

effective-html là tập hợp agent skill mã nguồn mở do tổ chức Plannotator phát triển, lấy cảm hứng trực tiếp từ dự án html-effectiveness. Điểm khác biệt then chốt: thay vì chỉ là bài viết và gallery ví dụ, effective-html đóng gói toàn bộ kho ví dụ html-effectiveness vào từng skill file - nghĩa là khi bạn cài đặt, model có tham chiếu chất lượng cao ngay trong local config, không phụ thuộc web search hay context window cạnh kiệt.

Repo cung cấp 3 skill tập trung:

html - tạo HTML file cho bất cứ thứ gì bạn mô tả, theo phong cách effective HTML: clean, self-contained, mở được ngay trên browser
html-diagram - xây dựng sơ đồ kiến trúc và system diagrams full-screen với SVG-first presentation, minimal prose - không dark bg, không wall of text
html-plan - tạo HTML plan pages với visual hierarchy rõ ràng, thích hợp cho sprint plan, project roadmap, feature spec

Về mặt kỹ thuật, mỗi skill nằm trong file SKILL.md riêng tại skills/<skill-name>/SKILL.md, chứa metadata, tool definitions và prompt instructions. Kho ví dụ được bundle local tại references/html-effectiveness/ trong mỗi skill - không cần mạng, không cần search, model tham chiếu trực tiếp. Demo diagram trong README được render bởi Fable 5, và tác giả có kế hoạch thêm nhiều Fable 5 artifact để giúp các model nhỏ hơn distill được phong cách này.

Cài Đặt và Quick Start

Hệ sinh thái npx skills - do Vercel Labs phát triển và mã nguồn mở - hoạt động như npm nhưng dành riêng cho AI agent behaviors, dùng GitHub làm registry. Cú pháp quen thuộc, mental model tương đương:

Concept	npm	skills CLI
Dependency manifest	package.json	.skills.json
Lock file	package-lock.json	skills-lock.json
Install directory	node_modules/	.agents/skills/
Registry	npmjs.com	GitHub

Cài đặt effective-html:

# Cài toàn bộ 3 skill
npx skills add plannotator/effective-html

# Liệt kê skill trước khi cài
npx skills add plannotator/effective-html --list

# Cài từng skill riêng lẻ
npx skills add plannotator/effective-html --skill html-diagram
npx skills add plannotator/effective-html --skill html-plan

Sau khi cài, CLI tự fetch SKILL.md và đặt vào config directory của agent (.agents/skills/ hoặc .claude/skills/ tùy agent). Nếu dùng Claude Code hoặc Codex, có thể cài trực tiếp qua plugin marketplace:

# Claude Code
/plugin marketplace add plannotator/effective-html
/plugin install plannotator-effective-html@effective-html

# Codex
codex plugin marketplace add plannotator/effective-html

Lock file (skills-lock.json) đảm bảo mọi developer trong team và CI environment dùng đúng cùng phiên bản skill. Thêm npx skills experimental_install vào CI pipeline để restore skills tự động.

Ba skill của effective-html: html, html-diagram, html-plan — Ba skill trong effective-html - html cho trang web tổng quát, html-diagram cho sơ đồ kiến trúc SVG, html-plan cho plan page trực quan. Mỗi skill có kho ví dụ tham chiếu riêng được bundle local.

HTML Hay Markdown - Phân Công Lao Động Đúng

effective-html không phải là giải pháp thay thế Markdown hoàn toàn. Câu hỏi đúng không phải là "format nào tốt hơn" mà là "khi nào output nên là source, khi nào nên là surface".

Dùng HTML khi: người đọc cần compare, inspect, filter, triage hoặc ra quyết định trước khi kết quả trở thành committed file. Code review map với severity filter và jump link theo file. Design comparison hiển thị dạng contact sheet. Architecture diagram kết nối toàn bộ system. Prototype cho phép click qua state machine trước khi viết một dòng code.

Giữ Markdown khi: output là durable record - cần được review trong diff, edit tay, quote trong issue, commit vào repo, hoặc được ingest bởi agent sau. Specs, runbooks, decision logs, README.

Workflow lý tưởng: agent tạo HTML artifact → human inspect và ra quyết định → export kết quả về Markdown, JSON hoặc code patch cho permanent record. HTML là review room, Markdown là durable source.

Một lưu ý bảo mật quan trọng: HTML là code thực thi - có thể chứa JavaScript và fetch external resources. Nên treat HTML artifact như untrusted code, không bao giờ bỏ credentials, API key hay customer data vào artifact, và luôn yêu cầu self-contained file không có external network dependencies.

Hệ Sinh Thái Plannotator

effective-html được thiết kế để dùng kết hợp với Plannotator - browser-based review surface chạy local, hỗ trợ Claude Code, Codex, Copilot CLI, Gemini CLI (≥0.36.0), OpenCode, Kiro, Droid, Amp và Pi. Khi agent tạo HTML plan hay code diff, Plannotator tự mở trên browser, cho phép annotate, comment và gửi feedback về agent bằng một click. Sharing có mã hóa AES-256-GCM để collaborate với team.

Ngoài core review surface, Plannotator tích hợp với VS Code (extension để annotate trong editor gutter), Obsidian (auto-save plan vào vault với YAML frontmatter), Bear, và PR workflow trên GitHub/GitLab. Đây là feedback loop khép kín: generate HTML → inspect và annotate → refine ngay trong agent context.

Đáng Thêm Vào Toolbox

effective-html giải quyết một vấn đề thực tế: AI agent tạo ra tài liệu phẳng khi developer cần artifact có thể inspect được. Ba skill tập trung, cài một lệnh, bundle sẵn ví dụ tham chiếu chất lượng cao từ kỹ sư Anthropic - đây là loại tool pragmatic không hoa mỹ nhưng làm đúng việc của nó.

Nếu bạn đang dùng Claude Code, Codex hay bất kỳ coding agent nào khác và muốn output có thể navigate, inspect, và share được - effective-html là điểm bắt đầu hợp lý. via plannotator/effective-html trên GitHub