prototype-spec-html

An open-source AI agent skill that turns a product manager's natural-language requirement description into a single shareable, offline-viewable HTML file containing a three-column prototype workspace with element-level requirement annotations.

What It Does

Give the AI a requirement description like:

做一个订单管理后台，含订单列表页和订单详情页。列表页有搜索框、状态筛选、表格（订单号/客户/金额/状态/时间/操作）和分页；详情页展示订单信息、商品明细和物流跟踪。

The skill generates one .html file with a three-column workspace:

• Fixed header — project / system / requirement name + generation time.
• Left sidebar — clickable page list with hash routing (#page-order-list), each page showing a Web or Mobile badge.
• Center canvas — AI-drawn high-fidelity wireframe prototype with lightweight interactions (hover, collapse, tabs, dialogs). Each page is designed for either Web size (full-width admin layout) or Mobile size (centered phone-frame shell with notch, status bar, and bottom tab bar).
• Right sidebar — element-level requirement annotations linked bidirectionally to the prototype.

Web-Size Page

Web-size pages fill the canvas width with a desktop admin interface: internal sidebar + topbar + content area, just like a real management system.

Mobile-Size Page

Mobile-size pages center a 390px phone-frame shell inside the canvas, complete with notch, status bar, stacked card lists, and a bottom tab bar. No <table> — mobile pages use card lists exclusively.

Element Picking Mode

When adding or editing an annotation, the user clicks "选择元素" (Pick Element) to enter picking mode: the canvas dims, and as the user moves the mouse over the prototype, the element under the cursor is outlined in real time. Clicking an element selects it and auto-fills the data-spec field — no manual typing required. Elements without a data-spec get one assigned automatically.

Bidirectional Linkage

Hovering a prototype element highlights both sides simultaneously — the element itself and its corresponding annotation (yellow background + scroll into view). Hovering an annotation likewise highlights both the annotation and its prototype element. Clicking an annotation highlights both sides and scrolls the prototype element into view. Linkage is suppressed during picking mode to avoid interference.

Key Features

• Single file, zero dependencies — all CSS, JS, and data are inlined. No CDN, no frameworks, no build step. Double-click to open in any browser.
• Per-page size design — each page is designed for Web or Mobile at design time (no runtime viewport switcher). A single HTML can mix both.
• Element-level annotations — every annotation is linked to a specific prototype element via data-spec / id matching, not just page-level.
• Runtime annotation editing — add, edit, and delete annotations directly in the right sidebar using Markdown. An inlined lightweight Markdown renderer (headers, tables, bold, italic, inline code, lists) renders the content to HTML. Changes persist to localStorage and survive page refresh.
• Element picking — pick a prototype element by mouse (hover to preview, click to select) instead of typing data-spec values. User-picked data-spec attributes also persist across refreshes.
• Cross-tool compatible — works with any agent tool that supports the standard SKILL.md format.

Install

This skill follows the standard SKILL.md format and works with any agent tool that supports it.

Option A: via skills CLI

npx skills add https://github.com/Paritck/prototype-spec-html

Option B: manual copy

Copy the prototype-spec-html/ folder (containing SKILL.md and references/) into your agent's skills directory:

| Agent tool | Project-level path | Global path | |---|---|---| | Claude Code | .claude/skills/ | ~/.claude/skills/ | | Codex CLI | .agents/skills/ | ~/.agents/skills/ | | Cursor | .cursor/skills/ | ~/.cursor/skills/ | | GitHub Copilot | .github/skills/ | ~/.copilot/skills/ | | Windsurf | .windsurf/skills/ | ~/.codeium/windsurf/ | | Goose | (per Goose docs) | — | | Zed | (per Zed docs) | — |

Cursor and GitHub Copilot also scan .claude/skills/ for compatibility, so a single copy there covers three tools.

Usage

After installation, just describe your requirement to the AI in any supported tool:

用 prototype-spec-html 生成一个后台管理系统原型：
- 项目名称：客户管理平台
- 页面1（Web）：客户列表（搜索、表格、分页）
- 页面2（Web）：客户详情（基本信息、订单记录、跟进记录）
- 页面3（Mobile）：App首页（快捷入口、最近订单）

The AI will load the skill, follow the 5-step workflow, and deliver a single .html file.

Repository Structure

prototype-spec-html/
├── SKILL.md                              # skill entry: frontmatter + workflow + constraints
├── references/
│   ├── html-template-spec.md             # three-column layout + CSS + JS + element picking
│   └── prototype-prompt-guide.md         # AI drawing rules + Web/Mobile + annotation points
├── demo/
│   ├── order-management-prototype.html   # demo output (open in browser to see it live)
│   └── screenshots/                      # screenshots for README
├── README.md                             # English readme (this file)
├── README_CN.md                          # Chinese readme
└── LICENSE                               # Apache 2.0

How Element-Level Linkage Works

• Prototype elements carry data-spec="annot-001".
• Right-sidebar annotation blocks carry id="annot-001".
• Vanilla JS (inlined) listens for mouseenter and click:
  • Hover a prototype element → both the element and its annotation highlight (yellow) and the annotation scrolls into view.
  • Hover an annotation → both the annotation and its prototype element highlight (yellow).
  • Click an annotation → both sides highlight and the prototype element scrolls into view.
• Switching pages clears all highlights.
• During picking mode, linkage is suppressed so the user can select elements without interference.
• Newly added annotations (via the "选择元素" button) automatically participate in linkage.
• User-picked data-spec attributes persist to localStorage and are restored after refresh.

Demo

Open demo/order-management-prototype.html directly in a browser to see a live example with 4 pages:

1. 订单列表 (Web) — admin table with filter bar, order table, pagination
2. 新建订单 (Web) — form with basic info, product selection, action buttons
3. App首页 (Mobile) — mobile home with banner, quick actions, order cards
4. 订单详情 (Mobile) — mobile order detail with status steps, order info, action buttons

License

Apache 2.0 — see LICENSE for details.