html-spec-planning

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: html-spec-planning
description: Create rich HTML documents for project specs, implementation plans, design exploration, RFCs, and brainstorming. Use whenever the user asks for a spec, plan, RFC, design doc, brainstorm, or wants to explore approaches/options/alternatives — even when they don't explicitly say "HTML". Strongly prefer HTML over markdown for any planning artifact longer than a screen, especially when the artifact will be shared with reviewers or fed back to the agent for implementation.
metadata:
  version: "1.2.1"
---

# HTML Spec, Planning & Exploration

Use HTML as the working surface for thinking through problems — brainstorms, alternative explorations, mockups, and implementation plans. Markdown specs over ~100 lines stop getting read; HTML specs get read because they're navigable, visual, and shareable as a link.

## When to use this skill

- "Write a spec / RFC / design doc / proposal for X"
- "I'm not sure how to approach X — explore the options"
- "Make me an implementation plan for X"
- "Brainstorm approaches to X"
- "Lay out the tradeoffs for X"
- Whenever the planning artifact will be reviewed by humans, or later read by another Claude session for implementation

## Output requirements

Save with a descriptive filename like `<topic>-spec.html` or `<topic>-plan.html` so multiple planning artifacts on one project compose into a readable folder rather than colliding on `output.html`.

## HTML output foundation

These defaults apply to **every** artifact this skill produces, on top of the requirements above. If a rule above conflicts with this list, the rule above wins; otherwise these are non-negotiable.

- **Output a real `.html` file the user opens in a browser — never inline-render in chat.** Every artifact this skill produces is a file on disk (`<topic>-<kind>.html`), not an HTML block embedded in the agent's chat surface (claude.ai artifact/canvas widgets, fenced ```html``` blocks, custom rendered iframes, etc.). Inline rendering strips features, themes unpredictably against the surrounding chat (often unreadable in dark mode), and lacks the stable origin and clipboard/network access the submit handler needs. Always write the file. The file itself must be self-contained: no build step, no external runtime, inline CSS and JS. Google Fonts via `<link>` is fine; otherwise nothing loaded from npm or a CDN unless this skill explicitly calls for it.
- **Mobile-responsive.** Collapse cleanly to a single column under ~700px so the artifact opens on a phone — including during incidents, commutes, and link-shares to non-laptop reviewers.
- **No `localStorage` / `sessionStorage` / `IndexedDB`.** Claude.ai artifacts can't use browser storage. State lives in JS memory; the export / copy button is the persistence layer.
- **Real semantic HTML, not screenshots.** Code goes in `<pre><code>` (selectable, copyable). Tabular data goes in `<table>`. Diagrams are inline `<svg>` with real `<g>` and `<path>` elements, not embedded PNGs. The reader should be able to copy any value, line, or label out of the artifact.
- **Build DOM safely; don't sling strings.** Use `textContent` for text and `document.createElement` + `appendChild` for structure. **Never** set `innerHTML` from a string that includes a variable, user input, computed value, or imported data — it's an XSS vector and many agent harnesses (including Claude Code) block it via security hooks. Static literal markup inline in your script is fine.
- **SVG text doesn't wrap — size the shape to the label, or use `<foreignObject>`.** Plain SVG `<text>` overflows silently when the label is longer than the box was sized for, crashing into adjacent shapes. For variable-length or potentially-long labels, wrap with `<foreignObject width="W" height="H">` plus an HTML `<div>` inside — real wrapping, real padding, real `text-overflow:ellipsis`. Plain `<text>` is fine only for short, fixed-length labels — and even then, size the surrounding shape from the label length (