PPTClaw Skill Reference
PPTClaw is a local-first presentation editor. Decks are JSON files on disk — you create and edit them directly, and the editor syncs changes live via WebSocket.
Setup
If pptclaw is not installed, install it globally:
CODEBLOCK0
Deck Format
A deck is a folder with this structure:
CODEBLOCK1
manifest.json
CODEBLOCK2
- -
viewport.ratio is height/width (0.5625 = 16:9, giving 1920x1080) - INLINECODE2 is an array of 6 colors used sequentially for chart series, infographic items, etc.
Slide JSON
Each slide file contains one slide object:
CODEBLOCK3
- -
type: "cover", "contents", "transition", "content", "end" - INLINECODE4 : array of typed element objects (see below)
- INLINECODE5 : optional, defaults to white
- INLINECODE6 : optional speaker notes (plain text)
Canvas
- - Size: 1920 x 1080 pixels
- Origin: top-left corner (0, 0)
- All position/size values are in pixels
Base Element Fields
Every element shares these fields:
CODEBLOCK4
Exception: line elements omit height and rotate — they use start/end points instead.
Theme Colors
Use CSS variable references instead of hardcoded hex values to stay consistent with the deck's theme:
| Variable | Purpose |
|---|
| INLINECODE10 | Primary brand color |
| INLINECODE11 |
Secondary/accent color |
|
var(--tx1) | Text color |
|
var(--accent1) to
var(--accent6) | Chart/emphasis colors |
Brightness variants — append a suffix to any theme variable:
- -
var(--primary-plus-50) — lighter (+50 brightness) - INLINECODE16 — darker (-25 brightness)
- Works for all theme colors: secondary, tx1, accent1-6
Theme fonts:
- -
var(--font-heading) — for titles, subtitles, headers - INLINECODE18 — for body text, content, items
Common Style Types
Outline (border)
CODEBLOCK5
Shadow
CODEBLOCK6
Gradient
CODEBLOCK7
Text Element (Inline Reference)
Text is the most common element type, so its full schema is included here. For other element types, run pptclaw element-docs <type>.
CODEBLOCK8
HTML Content Format
The content field uses ProseMirror HTML with inline styles:
CODEBLOCK9
Supported inline styles: font-size (px), color, font-weight, font-style, text-decoration, text-align, font-family.
Font Size Rules
Font sizes in HTML are in px, which equals 2x the PowerPoint pt value. This matters because presentations are viewed on large screens — small text becomes unreadable.
| Role | Pt | Px | Notes |
|---|
| Title | 36pt | 72px | Minimum for slide titles |
| Subtitle |
24pt | 48px | |
| Body | 18pt | 36px | Recommended 36-40px |
| Minimum | 16pt | 32px | Nothing smaller than this |
Common mistake: using web-scale sizes like 14px, 16px, 18px — these are too small for presentations.
Slide Background
CODEBLOCK10
Types: "solid" (with color) or "gradient" (with gradient object). Set backgrounds on the slide object, not by creating a full-canvas shape.
Layout Conventions
Standard Content Page
- - Title: left: 80, top: 80, font-size: 72px, bold
- Content area: left: 80, top: 200, width: 1760, height: 800
- Large elements (charts, infographics, tables) should fill the content area when shown alone
Centering
To horizontally center an element: INLINECODE32
Note: left: 960 does NOT center — it places the element's left edge at the midpoint, pushing it right.
Layout Self-Check
Before finalizing element positions, verify:
- 1. No overlap — element rectangles don't unintentionally intersect
- Readable text — all font sizes >= 32px, content fits within element bounds
- Edge margins — elements stay >= 60px from canvas edges
- Element spacing — >= 20px gap between elements
- Consistency — use 20px card gap and 10px border-radius across all slides
Element Types
Beyond the text element documented above, PPTClaw supports these element types:
| Type | Description | Key Fields |
|---|
| INLINECODE34 | Image with cover/fill, clipping, masking | imageSource, fit, clipShape, mask |
| INLINECODE35 |
Vector shape with optional inner text | shapeId, fill, gradient, text |
|
line | Line/arrow/connector (no height/rotate) | start, end, points, width (stroke) |
|
chart | Data visualization (8 chart types) | chartType, data, color |
|
table | Grid table with styled cells | data (2D TableCell), colWidths, theme |
|
icon | SVG icon by keyword search | keyword, color |
|
artText | Decorative wave text (cover pages only) | content, style, defaultColor |
|
infographic | Template-based infographic/diagram | template, data, color |
Get the full schema for any type:
CODEBLOCK11
CLI Reference
All commands support -p, --port <port> (default: 3059).
pptclaw serve [deck]
Start the editor server as a background daemon. Optionally open a deck immediately.
pptclaw serve # start server
pptclaw serve ./my-deck # start and open deck
pptclaw serve --port 4000 # custom port
Exit code: 0 on success, 1 if server fails to start.
pptclaw open \
Open a deck folder in the running editor.
pptclaw open ./my-deck
pptclaw open ./my-deck --session custom-id
Output: session ID, path, slide count.
pptclaw validate \
Validate a deck folder structure and content. Returns JSON with
valid,
errors,
warnings.
pptclaw validate ./my-deck
Exit code: 0 if valid, 1 if errors found. Requires running server.
pptclaw list-decks
List active sessions (open decks) with slide counts.
CODEBLOCK15
pptclaw status
Show server status, auth state, and active sessions as JSON.
pptclaw init
Copy the PPTClaw skill file to
.claude/skills/pptclaw/SKILL.md in the current directory.
pptclaw element-docs [type...]
Print element type documentation.
CODEBLOCK16
pptclaw search-images \
Search Unsplash images. Returns JSON array of results with id, description, dimensions.
pptclaw download-image \ --deck \
Download an image to a deck's assets folder.
Workflows
Create a New Deck
- 1. Create the folder structure:
CODEBLOCK17
- 2. Write
manifest.json with title, theme, and viewport
- 3. Create slide files in
slides/ (numbered: 001-<id>.json, 002-<id>.json, ...)
- 4. Validate:
CODEBLOCK18
- 5. Open in editor:
CODEBLOCK19
Edit an Existing Slide
- 1. Read the slide JSON file
- Modify the
elements array — add, update, or remove elements - Write the file back — the editor picks up changes automatically via file watcher
- Validate if needed: INLINECODE52
Add Images
- 1. Search for images:
pptclaw search-images "mountain landscape"
- 2. Download to deck assets:
pptclaw download-image <url> --deck ./my-deck
- 3. Reference in slide JSON via
imageSource field on an image element
PPTClaw 技能参考
PPTClaw 是一款本地优先的演示文稿编辑器。演示文稿是磁盘上的 JSON 文件——您可以直接创建和编辑它们，编辑器会通过 WebSocket 实时同步更改。
设置
如果尚未安装 pptclaw，请全局安装：
bash
pnpm add -g pptclaw # 或：npm install -g pptclaw
演示文稿格式
一个演示文稿是一个具有以下结构的文件夹：
my-deck/
├── manifest.json # 标题、主题、视口、幻灯片顺序
├── slides/
│ ├── 001-abc123.json # 幻灯片文件：-.json
│ ├── 002-def456.json
│ └── ...
└── assets/ # 图片和其他媒体文件
├── hero.jpg
└── ...
manifest.json
json
{
title: 我的演示文稿,
format: 1,
viewport: { width: 1920, ratio: 0.5625 },
theme: {
primary: #2563eb,
secondary: #7c3aed,
tx1: #1e293b,
accents: [#2563eb, #7c3aed, #5b9bd5, #ff6b6b, #4ecdc4, #95e1d3],
fontHeading: YouSheBiaoTiHei,
fontBody: Microsoft YaHei
}
}
- - viewport.ratio 是高度/宽度（0.5625 = 16:9，得到 1920x1080）
- theme.accents 是一个包含 6 种颜色的数组，按顺序用于图表系列、信息图项目等
幻灯片 JSON
每个幻灯片文件包含一个幻灯片对象：
json
{
id: abc123,
elements: [ / PPTElement 对象 / ],
background: { type: solid, color: #ffffff },
remark: 演讲者备注文本,
type: content
}
- - type：cover、contents、transition、content、end
- elements：类型化元素对象数组（见下文）
- background：可选，默认为白色
- remark：可选的演讲者备注（纯文本）
画布
- - 尺寸：1920 x 1080 像素
- 原点：左上角 (0, 0)
- 所有位置/尺寸值均以像素为单位
基础元素字段
每个元素共享以下字段：
ts
id: string // 唯一元素 ID
left: number // X 位置（距左边缘的像素数）
top: number // Y 位置（距上边缘的像素数）
width: number // 元素宽度（像素）
height: number // 元素高度（像素）
rotate: number // 旋转角度（度），默认为 0
lock?: boolean // 锁定元素禁止编辑
groupId?: string // 具有相同 groupId 的元素组成一个组
name?: string // 显示名称
link?: { type: web | slide, target: string }
例外情况：line 元素省略 height 和 rotate——它们改用起点/终点。
主题颜色
使用 CSS 变量引用而非硬编码的十六进制值，以保持与演示文稿主题的一致性：
| 变量 | 用途 |
|---|
| var(--primary) | 主要品牌色 |
| var(--secondary) |
次要/强调色 |
| var(--tx1) | 文本颜色 |
| var(--accent1) 到 var(--accent6) | 图表/强调色 |
亮度变体——在任何主题变量后附加后缀：
- - var(--primary-plus-50) — 更亮（+50 亮度）
- var(--primary-minus-25) — 更暗（-25 亮度）
- 适用于所有主题颜色：secondary、tx1、accent1-6
主题字体：
- - var(--font-heading) — 用于标题、副标题、页眉
- var(--font-body) — 用于正文、内容、项目
通用样式类型
轮廓（边框）
ts
{ style?: solid | dashed | dotted, width?: number, color?: string }
阴影
ts
{ offset: number, angle: number, blur: number, color: string, alpha: number }
// offset: 0-100, angle: 0-359, blur: 0-100 (pt), alpha: 0-100 (0=透明)
渐变
ts
{
type: linear | radial,
colors: [{ pos: number, color: string, alpha?: number }], // pos: 0-100%
rotate?: number,
radialStart?: center | top-left | top-right | bottom-left | bottom-right
}
文本元素（内联参考）
文本是最常见的元素类型，因此此处包含其完整模式。对于其他元素类型，请运行 pptclaw element-docs 。
ts
interface PPTTextElement extends PPTBaseElement {
type: text
content: string // ProseMirror HTML
defaultColor: string // 后备颜色（被内联 HTML 样式覆盖）
fill?: string // 背景填充色
lineHeight?: number // 行高倍数，默认为 1.5
wordSpace?: number // 字间距，默认为 0
paragraphSpace?: number // 段落间距（像素），默认为 5
opacity?: number // 0-1，默认为 1
vertical?: boolean // 垂直文本模式
outline?: Outline
shadow?: Shadow
textType?: title | subtitle | content | item | itemTitle | notes | header | footer
}
HTML 内容格式
content 字段使用带有内联样式的 ProseMirror HTML：
html
标题文本
正文段落
支持的内联样式：font-size（px）、color、font-weight、font-style、text-decoration、text-align、font-family。
字号规则
HTML 中的字号以 px 为单位，等于 PowerPoint pt 值的 2 倍。这一点很重要，因为演示文稿是在大屏幕上观看的——小文本会变得难以阅读。
| 角色 | Pt | Px | 备注 |
|---|
| 标题 | 36pt | 72px | 幻灯片标题的最小值 |
| 副标题 |
24pt | 48px | |
| 正文 | 18pt | 36px | 建议 36-40px |
| 最小值 | 16pt | 32px | 不得小于此值 |
常见错误：使用网页级尺寸如 14px、16px、18px——这些对于演示文稿来说太小了。
幻灯片背景
json
{
background: {
type: solid,
color: var(--primary-plus-80)
}
}
类型：solid（带 color）或 gradient（带 gradient 对象）。在幻灯片对象上设置背景，而不是通过创建全画布形状。
布局约定
标准内容页
- - 标题：left: 80, top: 80, font-size: 72px, bold
- 内容区域：left: 80, top: 200, width: 1760, height: 800
- 大型元素（图表、信息图、表格）单独显示时应填满内容区域
居中
要水平居中一个元素：left = (1920 - width) / 2
注意：left: 960 不会居中——它会把元素的左边缘放在中点，使其偏右。
布局自查
在最终确定元素位置之前，请验证：
- 1. 无重叠——元素矩形不会意外相交
- 文本可读——所有字号 >= 32px，内容适合元素边界内
- 边缘边距——元素距离画布边缘 >= 60px
- 元素间距——元素之间间距 >= 20px
- 一致性——所有幻灯片使用 20px 卡片间距和 10px 圆角
元素类型
除了上述文档记录的文本元素外，PPTClaw 还支持以下元素类型：
|
