Improve README onboarding
This commit is contained in:
郭浩 committed
1 parent
3652b3c7aa
commit
10c84e3000
2 files changed
+214
No files matched your search
+107
@@ -17,6 +17,38 @@ It ships with two visual systems:
|
||||
|
||||
|
||||
|
||||
## 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:
|
||||
|
||||
@@ -19,6 +19,38 @@
|
||||
|
||||
|
||||
|
||||
## 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。改动请优先:
|
||||
|
||||
Reference in new issue
Block a user