Improve README onboarding

README.en.md

@@ -17,6 +17,38 @@ It ships with two visual systems:
 
 ![Style B Swiss International preview](https://github.com/user-attachments/assets/8960e78c-69bb-4b7e-aa95-6fad64b70314)
 
+## 30-second start
+
+```bash
+npx skills add https://github.com/op7418/guizang-ppt-skill --skill guizang-ppt-skill
+```
+
+Or paste this to an AI agent with shell access:
+
+```text
+Install guizang-ppt-skill for me. Clone https://github.com/op7418/guizang-ppt-skill into ~/.claude/skills/guizang-ppt-skill, then verify that SKILL.md, assets/, and references/ exist.
+```
+
+If you already installed it, update with:
+
+```text
+Update guizang-ppt-skill for me. Go to ~/.claude/skills/guizang-ppt-skill, run git pull, then tell me the latest commit.
+```
+
+Then ask your agent:
+
+```text
+Create a Swiss-style deck from this article, around 7 slides, with 2-3 generated visuals.
+```
+
+Other useful prompts:
+
+```text
+Turn this Markdown file into an editorial magazine-style presentation.
+Create a 21:9 social cover from the core idea of this deck.
+Redesign this product screenshot as a 16:10 slide visual.
+```
+
 ## What you get
 
 - 🖋 **Two visual systems**: editorial storytelling for Style A, factual Swiss structure for Style B
@@ -35,6 +67,35 @@ It ships with two visual systems:
 
 **❌ Doesn't fit**: data-heavy tables, training decks (density too low), multi-user collaborative editing (static HTML)
 
+## Common use cases
+
+| Task | Recommended flow |
+|------|------------------|
+| Long article to talk deck | Extract the core argument, then build a 6-10 slide rhythm |
+| Framework / product analysis | Use Style B Swiss with locked layouts and 21:9 hero visuals |
+| Personal talk / opinion piece | Use Style A editorial magazine for stronger narrative rhythm |
+| Deck visuals | In Codex, generate photos, infographics, flow diagrams, system maps, or UI scenes |
+| Social covers | Generate 21:9 main covers, 1:1 share cards, 3:4 vertical covers, and video thumbnails from the same idea |
+| Screenshot normalization | Redesign raw screenshots into template-safe ratios before inserting them into slides |
+
+## Why HTML decks
+
+- **Agent-native editing**: HTML / CSS is plain text, so agents can read, edit, and validate it directly.
+- **Higher visual density than Markdown**: precise layout, positioning, motion, interactivity, and cover formats.
+- **Lightweight delivery**: one HTML file can be opened, presented, sent, screenshotted, or recorded.
+- **Better quality gates**: the Swiss validator can catch layout drift, unsafe image placement, centered body titles, and SVG text traps.
+- **One visual system across outputs**: decks, generated visuals, covers, and screenshot redesigns can share the same style rules.
+
+## Platform support
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Claude Code | Supported | Native Skill workflow for creating and iterating HTML decks |
+| Codex | Supported | Good for deck generation, image generation, and browser-based visual QA |
+| Cursor / other local agents | Works | Requires filesystem access and shell execution |
+| WorkBuddy | In adaptation | Marketplace-ready version is being prepared separately |
+| Plain chatbot | Not recommended | Without filesystem and browser preview, full deck generation is hard to stabilize |
+
 ## Install
 
 ### Option 1: One-line install (recommended)
@@ -134,6 +195,26 @@ The skill can also turn an article or deck idea into platform covers:
 
 The same rule applies: use a few strong keywords, keep the title as the visual center, and do not fill the canvas with body copy.
 
+## Example prompts
+
+Copy any of these prompts into your agent, then attach your article, Markdown file, or image assets:
+
+```text
+Create an 8-slide Swiss-style deck from this article, with 3 generated visuals matched to the template image slots.
+```
+
+```text
+Turn this product analysis document into an editorial magazine-style deck with a strong narrative rhythm.
+```
+
+```text
+From this deck's core idea, create two covers: a 21:9 main cover and a visually paired 1:1 share card.
+```
+
+```text
+Redesign these product screenshots into consistent 16:10 slide visuals. Preserve key UI information; do not add slide titles or footers inside the images.
+```
+
 ## Directory
 
 ```
@@ -202,6 +283,32 @@ If the user asks for a Swiss-style deck without specifying color, default to Int
 - Massimo Vignelli / Helvetica Forever / Swiss International Typographic Style
 - Guizang's offline talk deck series
 
+## Roadmap
+
+- Add more real-world examples and openable HTML deck demos
+- Expand cover formats for more publishing platforms
+- Add more Swiss layout validation rules
+- Improve screenshot redesign and infographic generation workflows
+- Prepare marketplace-specific variants such as WorkBuddy
+- Add more curated theme packs while keeping custom colors restricted
+
+## FAQ
+
+**Can it export to PPTX?**
+The main output is HTML. You can present it in a browser, screenshot it, or record it. PPTX conversion can be done as a separate workflow, but it is not the core path today.
+
+**Why are custom colors not allowed?**
+The skill is designed for stable visual output. Arbitrary colors often break the system, so decks must use curated presets.
+
+**Can I add my own layout?**
+Yes. Style A layouts can be extended in `references/layouts.md`. Style B is stricter: update `template-swiss.html`, `layouts-swiss.md`, `swiss-layout-lock.md`, and the validator together.
+
+**Is Codex image generation required?**
+No. Decks work without generated images. The image flow is only used when you need photos, infographics, UI scenes, or covers.
+
+**How do I update the skill?**
+Run the install command again, or run `git pull` inside your local skill directory.
+
 ## Contributing
 
 Bugs, layout issues, new layout requests — Issues and PRs welcome. Prioritize:

README.md

@@ -19,6 +19,38 @@
 
 ![Style B 瑞士国际主义效果展示](https://github.com/user-attachments/assets/8960e78c-69bb-4b7e-aa95-6fad64b70314)
 
+## 30 秒开始
+
+```bash
+npx skills add https://github.com/op7418/guizang-ppt-skill --skill guizang-ppt-skill
+```
+
+也可以直接把这段话发给有 shell 权限的 AI Agent:
+
+```text
+帮我安装 guizang-ppt-skill。请把 https://github.com/op7418/guizang-ppt-skill 克隆到 ~/.claude/skills/guizang-ppt-skill,安装完成后检查 SKILL.md、assets/、references/ 是否存在。
+```
+
+已经安装过的话,用这段话更新:
+
+```text
+帮我更新 guizang-ppt-skill。请进入 ~/.claude/skills/guizang-ppt-skill 执行 git pull,然后告诉我当前最新 commit。
+```
+
+安装后直接对 Agent 说:
+
+```text
+帮我基于这篇文章做一份瑞士风 PPT,控制在 7 页左右,需要 2-3 张配图。
+```
+
+也可以试这些请求:
+
+```text
+帮我把这份 Markdown 做成杂志风演讲 PPT。
+基于这份 PPT 的核心观点,生成一张公众号 21:9 头图。
+把这张产品截图重新设计成适合 PPT 的 16:10 配图。
+```
+
 ## 效果
 
 - 🖋 **双视觉系统**:电子杂志风负责叙事,瑞士风负责事实表达
@@ -37,6 +69,35 @@
 
 **❌ 不合适**:大段表格数据 / 培训课件(信息密度不够)/ 需要多人协作编辑(静态 HTML)
 
+## 常见使用场景
+
+| 任务 | 推荐方式 |
+|------|---------|
+| 长文章变演讲 PPT | 先抽核心观点,再按 6-10 页节奏生成 deck |
+| 方法论 / 产品分析 | 用 Style B 瑞士风,优先使用锁定版式和 21:9 主图 |
+| 个人分享 / 观点表达 | 用 Style A 电子杂志风,保留更强叙事感 |
+| PPT 配图 | 在 Codex 中用 GPT-Image 2.0 / GPT-M 2.0 生成照片、信息图、流程图、UI 情景图 |
+| 多平台封面 | 从同一份内容生成公众号 21:9、1:1 分享卡、小红书 3:4、视频号横版封面 |
+| 截图统一风格 | 把原始截图重新生成到模板需要的比例,再插入 PPT |
+
+## 为什么是 HTML PPT
+
+- **更适合 Agent 生成和修改**:HTML / CSS 是文本,Agent 能直接读、改、验证。
+- **表现力比 Markdown 更高**:可以做精细排版、空间定位、动画、交互和响应式封面。
+- **交付更轻**:单文件 HTML 可以直接打开、演示、发送、截图。
+- **更容易做质量控制**:瑞士风可以用脚本校验版式、图片槽位、标题对齐和危险 SVG。
+- **更适合视觉内容链路**:同一套主题能覆盖 PPT、配图、封面和截图再设计。
+
+## 平台支持
+
+| 平台 | 状态 | 说明 |
+|------|------|------|
+| Claude Code | 支持 | 原生 Skill 工作流,适合生成和迭代 HTML deck |
+| Codex | 支持 | 适合生成 PPT、调用图片生成能力、做浏览器视觉检查 |
+| Cursor / 其他本地 Agent | 可用 | 需要能读写文件并执行 shell 命令 |
+| WorkBuddy | 适配中 | 单独整理上架版本,去掉平台不需要的渠道差异 |
+| 普通 Chatbot | 不推荐 | 没有文件系统和浏览器预览时,很难稳定生成完整 deck |
+
 ## 安装
 
 ### 方式一:一行命令安装(推荐)
@@ -136,6 +197,26 @@ node scripts/validate-swiss-deck.mjs path/to/index.html
 
 封面原则和 PPT 一样:只用少量关键词,视觉重心落在大标题上,不要把正文堆满。
 
+## 示例请求
+
+复制下面任意一条给 Agent,再附上你的文章、Markdown 或素材文件:
+
+```text
+帮我基于这篇文章生成一份 8 页左右的瑞士风 PPT,需要 3 张配图,图片比例跟模板槽位匹配。
+```
+
+```text
+帮我把这个产品分析文档做成电子杂志风 PPT,重点突出观点和叙事节奏。
+```
+
+```text
+基于这份 PPT 的主题,做两张封面:公众号 21:9 头图和 1:1 分享卡,视觉保持一致。
+```
+
+```text
+把这些产品截图重新设计成统一的 16:10 PPT 配图,保留关键信息,不要画页脚和标题。
+```
+
 ## 目录结构
 
 ```
@@ -203,6 +284,32 @@ guizang-ppt-skill/
 - Massimo Vignelli / Helvetica Forever / 瑞士国际主义网格系统
 - 歸藏线下分享 PPT 系列
 
+## Roadmap
+
+- 补充更多真实案例和可打开的 HTML deck 示例
+- 扩展封面规格,覆盖更多内容平台
+- 增加更多瑞士风版式校验规则
+- 优化截图再设计和信息图生成工作流
+- 整理 WorkBuddy 等平台上架版本
+- 增加更多主题包,但继续限制自定义颜色
+
+## FAQ
+
+**可以导出 PPTX 吗?**
+当前核心交付是 HTML。你可以用浏览器演示、截图或录屏。如果需要 PPTX,建议把 HTML 页面作为视觉稿再转换,但这不是当前主流程。
+
+**为什么不允许自定义颜色?**
+这个 Skill 的重点是稳定产出。自由选色很容易破坏整体风格,所以只允许从预设主题里选。
+
+**我能加自己的版式吗?**
+可以。Style A 可以在 `references/layouts.md` 里扩展；Style B 更严格,需要同步更新 `template-swiss.html`、`layouts-swiss.md`、`swiss-layout-lock.md` 和校验器。
+
+**Codex 配图是必须的吗?**
+不是。没有配图也能生成 PPT。配图流程只在需要照片、信息图、UI 情景图或封面时使用。
+
+**怎么更新到最新版?**
+重新运行安装命令,或在本地 skill 目录执行 `git pull`。
+
 ## 贡献
 
 Bug、排版问题、新布局需求——欢迎开 Issue 或 PR。改动请优先: