docs: audit README + SKILL — accurate counts, install command, pre-author checklist

- README fully rewritten: correct 36 themes / 31 layouts / 27 CSS + 20 FX anims / 14 full decks
- Add one-line install: npx skills add https://github.com/lewislulu/html-ppt-skill
- List all 36 theme names, 14 full-deck names, and the animation catalogs
- SKILL.md: fix 30 → 31 layouts, 25 → 27 CSS animations
- SKILL.md: add 'Before you author anything' section — always ask user about
  content/style/starting-point, or recommend themes based on audience
- SKILL.md: fix duplicate '5.' in Quick start numbering

README.md

@@ -1,33 +1,180 @@
 # html-ppt — HTML PPT Studio
 
-Author: **lewis** <sudolewis@gmail.com>
+> A world-class AgentSkill for producing professional HTML presentations in
-License: MIT
+> **36 themes**, **14 full-deck templates**, **31 page layouts**, and
+> **47 animations** (27 CSS + 20 canvas FX) — all pure static HTML/CSS/JS, no
+> build step.
 
-A self-contained AgentSkill for producing professional HTML presentations
+**Author:** lewis <sudolewis@gmail.com>
-("slides", "decks", "keynotes", 演讲稿, 幻灯片) in many styles, layouts, and
+**License:** MIT
-animations — all driven by tasteful, hand-tuned templates.
 
-- 24 themes (`assets/themes/*.css`)
+## Install (one command)
-- 30 page layouts (`templates/single-page/*.html`)
-- 25 named animations (`assets/animations/animations.css`)
-- Keyboard-driven runtime with presenter mode, theme cycling, overview grid
-- Zero build: pure static HTML/CSS/JS, CDN deps only (Noto Sans SC, Inter,
-  JetBrains Mono, highlight.js, chart.js)
-- Showcase decks for every theme / layout / animation
-- Headless-Chrome PNG renderer script
-
-## Quick start
 
 ```bash
-# scaffold a new deck
+npx skills add https://github.com/lewislulu/html-ppt-skill
-./scripts/new-deck.sh my-talk
-
-# render a template to PNG
-./scripts/render.sh templates/theme-showcase.html
 ```
 
-Open `templates/theme-showcase.html` / `templates/layout-showcase.html` /
+That registers the skill with your agent runtime. After install, any agent
-`templates/animation-showcase.html` in Chrome to browse the whole catalog.
+that supports AgentSkills can author presentations by asking things like:
 
-See `SKILL.md` for the agent-facing usage guide and `references/` for the
+> "做一份 8 页的技术分享 slides，用 cyberpunk 主题"
-full theme / layout / animation catalogs.
+> "turn this outline into a pitch deck"
+> "做一个小红书图文，9 张，白底柔和风"
+
+## What's in the box
+
+| | Count | Where |
+|---|---|---|
+| 🎨 **Themes** | **36** | `assets/themes/*.css` |
+| 📑 **Full-deck templates** | **14** | `templates/full-decks/<name>/` |
+| 🧩 **Single-page layouts** | **31** | `templates/single-page/*.html` |
+| ✨ **CSS animations** | **27** | `assets/animations/animations.css` |
+| 💥 **Canvas FX animations** | **20** | `assets/animations/fx/*.js` |
+| 🖼️ **Showcase decks** | 4 | `templates/*-showcase.html` |
+| 📸 **Verification screenshots** | 56 | `scripts/verify-output/` |
+
+### 36 Themes
+
+`minimal-white`, `editorial-serif`, `soft-pastel`, `sharp-mono`, `arctic-cool`,
+`sunset-warm`, `catppuccin-latte`, `catppuccin-mocha`, `dracula`, `tokyo-night`,
+`nord`, `solarized-light`, `gruvbox-dark`, `rose-pine`, `neo-brutalism`,
+`glassmorphism`, `bauhaus`, `swiss-grid`, `terminal-green`, `xiaohongshu-white`,
+`rainbow-gradient`, `aurora`, `blueprint`, `memphis-pop`, `cyberpunk-neon`,
+`y2k-chrome`, `retro-tv`, `japanese-minimal`, `vaporwave`, `midcentury`,
+`corporate-clean`, `academic-paper`, `news-broadcast`, `pitch-deck-vc`,
+`magazine-bold`, `engineering-whiteprint`.
+
+Each is a pure CSS-tokens file — swap one `<link>` to reskin the entire deck.
+Browse them all in `templates/theme-showcase.html` (each slide rendered in an
+isolated iframe so theme ≠ theme is visually guaranteed).
+
+### 14 Full-deck templates
+
+Eight extracted from real-world decks, six generic scenario scaffolds:
+
+**Extracted looks**
+- `xhs-white-editorial` — 小红书白底杂志风
+- `graphify-dark-graph` — 暗底 + 力导向知识图谱
+- `knowledge-arch-blueprint` — 蓝图 / 架构图风
+- `hermes-cyber-terminal` — 终端 cyberpunk
+- `obsidian-claude-gradient` — 紫色渐变卡
+- `testing-safety-alert` — 红 / 琥珀警示风
+- `xhs-pastel-card` — 柔和马卡龙图文
+- `dir-key-nav-minimal` — 方向键极简
+
+**Scenario decks**
+- `pitch-deck`, `product-launch`, `tech-sharing`, `weekly-report`,
+  `xhs-post` (9-slide 3:4), `course-module`
+
+Each is a self-contained folder with scoped `.tpl-<name>` CSS so multiple
+decks can be previewed side-by-side without collisions. Browse the full
+gallery in `templates/full-decks-index.html`.
+
+### 31 Single-page layouts
+
+cover · toc · section-divider · bullets · two-column · three-column ·
+big-quote · stat-highlight · kpi-grid · table · code · diff · terminal ·
+flow-diagram · timeline · roadmap · mindmap · comparison · pros-cons ·
+todo-checklist · gantt · image-hero · image-grid · chart-bar · chart-line ·
+chart-pie · chart-radar · arch-diagram · process-steps · cta · thanks
+
+Every layout ships with realistic demo data so you can drop it into a deck
+and immediately see it render.
+
+### 27 CSS animations + 20 Canvas FX
+
+**CSS (lightweight)** — directional fades, `rise-in`, `zoom-pop`, `blur-in`,
+`glitch-in`, `typewriter`, `neon-glow`, `shimmer-sweep`, `gradient-flow`,
+`stagger-list`, `counter-up`, `path-draw`, `morph-shape`, `parallax-tilt`,
+`card-flip-3d`, `cube-rotate-3d`, `page-turn-3d`, `perspective-zoom`,
+`marquee-scroll`, `kenburns`, `ripple-reveal`, `spotlight`, …
+
+**Canvas FX (cinematic)** — `particle-burst`, `confetti-cannon`, `firework`,
+`starfield`, `matrix-rain`, `knowledge-graph` (force-directed physics),
+`neural-net` (signal pulses), `constellation`, `orbit-ring`, `galaxy-swirl`,
+`word-cascade`, `letter-explode`, `chain-react`, `magnetic-field`,
+`data-stream`, `gradient-blob`, `sparkle-trail`, `shockwave`,
+`typewriter-multi`, `counter-explosion`. Each is a real hand-rolled canvas
+module auto-initialised on slide enter via `fx-runtime.js`.
+
+## Quick start (manual, after install or git clone)
+
+```bash
+# Scaffold a new deck from the base template
+./scripts/new-deck.sh my-talk
+
+# Browse everything
+open templates/theme-showcase.html         # all 36 themes (iframe-isolated)
+open templates/layout-showcase.html        # all 31 layouts
+open templates/animation-showcase.html     # all 47 animations
+open templates/full-decks-index.html       # all 14 full decks
+
+# Render any template to PNG via headless Chrome
+./scripts/render.sh templates/theme-showcase.html
+./scripts/render.sh examples/my-talk/index.html 12
+```
+
+## Keyboard cheat sheet
+
+```
+← → Space PgUp PgDn Home End   navigate
+F                               fullscreen
+S                               speaker notes overlay
+O                               slide overview grid
+T                               cycle themes
+A                               cycle a demo animation on current slide
+#/N (URL)                       deep-link to slide N
+```
+
+## Project structure
+
+```
+html-ppt-skill/
+├── SKILL.md                      agent-facing dispatcher
+├── README.md                     this file
+├── references/                   detailed catalogs
+│   ├── themes.md                 36 themes with when-to-use
+│   ├── layouts.md                31 layout types
+│   ├── animations.md             27 CSS + 20 FX catalog
+│   ├── full-decks.md             14 full-deck templates
+│   └── authoring-guide.md        full workflow
+├── assets/
+│   ├── base.css                  shared tokens + primitives
+│   ├── fonts.css                 webfont imports
+│   ├── runtime.js                keyboard + presenter + overview
+│   ├── themes/*.css              36 theme token files
+│   └── animations/
+│       ├── animations.css        27 named CSS animations
+│       ├── fx-runtime.js         auto-init [data-fx] on slide enter
+│       └── fx/*.js               20 canvas FX modules
+├── templates/
+│   ├── deck.html                 minimal starter
+│   ├── theme-showcase.html       iframe-isolated theme tour
+│   ├── layout-showcase.html      all 31 layouts
+│   ├── animation-showcase.html   47 animation slides
+│   ├── full-decks-index.html     14-deck gallery
+│   ├── full-decks/<name>/        14 scoped multi-slide decks
+│   └── single-page/*.html        31 layout files with demo data
+├── scripts/
+│   ├── new-deck.sh               scaffold
+│   ├── render.sh                 headless Chrome → PNG
+│   └── verify-output/            56 self-test screenshots
+└── examples/demo-deck/           complete working deck
+```
+
+## Philosophy
+
+- **Token-driven design system.** All color, radius, shadow, font decisions
+  live in `assets/base.css` + the current theme file. Change one variable,
+  the whole deck reflows tastefully.
+- **Iframe isolation for previews.** Theme / layout / full-deck showcases all
+  use `<iframe>` per slide so each preview is a real, independent render.
+- **Zero build.** Pure static HTML/CSS/JS. CDN only for webfonts, highlight.js
+  and chart.js (optional).
+- **Senior-designer defaults.** Opinionated type scale, spacing rhythm,
+  gradients and card treatments — no "Corporate PowerPoint 2006" vibes.
+- **Chinese + English first-class.** Noto Sans SC / Noto Serif SC pre-imported.
+
+## License
+
+MIT © 2026 lewis &lt;sudolewis@gmail.com&gt;.

SKILL.md

@@ -9,11 +9,20 @@ Author professional HTML presentations as static files. One theme file = one
 look. One layout file = one page type. One animation class = one entry effect.
 All pages share a token-based design system in `assets/base.css`.
 
-Tell the user this skill gives them:
+## Install
-- **36 themes** (`assets/themes/*.css`) — 24 v1 + 12 v2 (cyberpunk-neon, y2k-chrome, retro-tv, japanese-minimal, vaporwave, midcentury, corporate-clean, academic-paper, news-broadcast, pitch-deck-vc, magazine-bold, engineering-whiteprint)
+
-- **14 full-deck templates** (`templates/full-decks/<name>/`) — complete multi-slide decks with scoped `.tpl-<name>` CSS. 8 extracted from real-world decks, 6 generic scenario scaffolds (pitch-deck, product-launch, tech-sharing, weekly-report, xhs-post 3:4, course-module).
+```bash
-- **30 layouts** (`templates/single-page/*.html`) with realistic demo data
+npx skills add https://github.com/lewislulu/html-ppt-skill
-- **25 named CSS animations** (`assets/animations/animations.css`) via `data-anim`
+```
+
+One command, no build. Pure static HTML/CSS/JS with only CDN webfonts.
+
+## What the skill gives you
+
+- **36 themes** (`assets/themes/*.css`) — minimal-white, editorial-serif, soft-pastel, sharp-mono, arctic-cool, sunset-warm, catppuccin-latte/mocha, dracula, tokyo-night, nord, solarized-light, gruvbox-dark, rose-pine, neo-brutalism, glassmorphism, bauhaus, swiss-grid, terminal-green, xiaohongshu-white, rainbow-gradient, aurora, blueprint, memphis-pop, cyberpunk-neon, y2k-chrome, retro-tv, japanese-minimal, vaporwave, midcentury, corporate-clean, academic-paper, news-broadcast, pitch-deck-vc, magazine-bold, engineering-whiteprint
+- **14 full-deck templates** (`templates/full-decks/<name>/`) — complete multi-slide decks with scoped `.tpl-<name>` CSS. 8 extracted from real-world decks (xhs-white-editorial, graphify-dark-graph, knowledge-arch-blueprint, hermes-cyber-terminal, obsidian-claude-gradient, testing-safety-alert, xhs-pastel-card, dir-key-nav-minimal), 6 scenario scaffolds (pitch-deck, product-launch, tech-sharing, weekly-report, xhs-post 3:4, course-module)
+- **31 layouts** (`templates/single-page/*.html`) with realistic demo data
+- **27 CSS animations** (`assets/animations/animations.css`) via `data-anim`
 - **20 canvas FX animations** (`assets/animations/fx/*.js`) via `data-fx` — particle-burst, confetti-cannon, firework, starfield, matrix-rain, knowledge-graph (force-directed), neural-net (pulses), constellation, orbit-ring, galaxy-swirl, word-cascade, letter-explode, chain-react, magnetic-field, data-stream, gradient-blob, sparkle-trail, shockwave, typewriter-multi, counter-explosion
 - **Keyboard runtime** (`assets/runtime.js`) — arrows, T (theme), A (anim), F/S/O
 - **FX runtime** (`assets/animations/fx-runtime.js`) — auto-inits `[data-fx]` on slide enter, cleans up on leave
@@ -25,6 +34,38 @@ Tell the user this skill gives them:
 Use when the user asks for any kind of slide-based output or wants to turn
 text/notes into a presentable deck. Prefer this over building from scratch.
 
+## Before you author anything — ALWAYS ask or recommend
+
+**Do not start writing slides until you understand three things.** Either ask
+the user directly, or — if they already handed you rich content — propose a
+tasteful default and confirm.
+
+1. **Content & audience.** What's the deck about, how many slides, who's
+   watching (engineers / execs / 小红书读者 / 学生 / VC)?
+2. **Style / theme.** Which of the 36 themes fits? If unsure, recommend 2-3
+   candidates based on tone:
+   - Business / investor pitch → `pitch-deck-vc`, `corporate-clean`, `swiss-grid`
+   - Tech sharing / engineering → `tokyo-night`, `dracula`, `catppuccin-mocha`,
+     `terminal-green`, `blueprint`
+   - 小红书图文 → `xiaohongshu-white`, `soft-pastel`, `rainbow-gradient`,
+     `magazine-bold`
+   - Academic / report → `academic-paper`, `editorial-serif`, `minimal-white`
+   - Edgy / cyber / launch → `cyberpunk-neon`, `vaporwave`, `y2k-chrome`,
+     `neo-brutalism`
+3. **Starting point.** One of the 14 full-deck templates, or scratch? Point
+   to the closest `templates/full-decks/<name>/` and ask if it fits. If the
+   user's content suggests something obvious (e.g. "我要做产品发布会" →
+   `product-launch`), propose it confidently instead of asking blindly.
+
+A good opening message looks like:
+
+> 我可以给你做这份 PPT！先确认三件事：
+> 1. 大致内容 / 页数 / 观众是谁？
+> 2. 风格偏好？我建议从这 3 个主题里选一个：`tokyo-night`（技术分享默认好看）、`xiaohongshu-white`（小红书风）、`corporate-clean`（正式汇报）。
+> 3. 要不要用我现成的 `tech-sharing` 全 deck 模板打底？
+
+Only after those are clear, scaffold the deck and start writing.
+
 ## Quick start
 
 1. **Scaffold a new deck.** From the repo root:
@@ -49,7 +90,7 @@ text/notes into a presentable deck. Prefer this over building from scratch.
    `examples/my-talk/` as a starting point. Each folder is self-contained with
    scoped CSS. Catalog in [references/full-decks.md](references/full-decks.md)
    and gallery at `templates/full-decks-index.html`.
-5. **Render to PNG.**
+6. **Render to PNG.**
    ```bash
    ./scripts/render.sh templates/theme-showcase.html       # one shot
    ./scripts/render.sh examples/my-talk/index.html 12      # 12 slides
@@ -83,8 +124,8 @@ Chinese + English deck, and how to export.
 ## Catalogs (load when needed)
 
 - [references/themes.md](references/themes.md) — all 36 themes with when-to-use.
-- [references/layouts.md](references/layouts.md) — all 30 layout types.
+- [references/layouts.md](references/layouts.md) — all 31 layout types.
-- [references/animations.md](references/animations.md) — 25 CSS + 20 canvas FX animations.
+- [references/animations.md](references/animations.md) — 27 CSS + 20 canvas FX animations.
 - [references/full-decks.md](references/full-decks.md) — all 14 full-deck templates.
 - [references/authoring-guide.md](references/authoring-guide.md) — full workflow.
 
@@ -100,17 +141,17 @@ html-ppt/
 │   ├── runtime.js           (keyboard + presenter + overview + theme cycle)
 │   ├── themes/*.css         (36 token overrides, one per theme)
 │   └── animations/
-│       ├── animations.css   (25 named CSS entry animations)
+│       ├── animations.css   (27 named CSS entry animations)
 │       ├── fx-runtime.js    (auto-init [data-fx] on slide enter)
 │       └── fx/*.js          (20 canvas FX modules: particles/graph/fireworks…)
 ├── templates/
 │   ├── deck.html                  (minimal 6-slide starter)
 │   ├── theme-showcase.html        (36 slides, iframe-isolated per theme)
-│   ├── layout-showcase.html       (iframe tour of all 30 layouts)
+│   ├── layout-showcase.html       (iframe tour of all 31 layouts)
 │   ├── animation-showcase.html    (20 FX + 27 CSS animation slides)
 │   ├── full-decks-index.html      (gallery of all 14 full-deck templates)
 │   ├── full-decks/<name>/         (14 scoped multi-slide deck templates)
-│   └── single-page/*.html         (30 layout files with demo data)
+│   └── single-page/*.html         (31 layout files with demo data)
 ├── scripts/
 │   ├── new-deck.sh                (scaffold a deck from deck.html)
 │   └── render.sh                  (headless Chrome → PNG)