Purpose and scope
moai-officer:doc-html-slidecreates presentation slide decks as single-file, self-contained HTML. It inherits the "zero-dependency · inline SVG · design-system-library token contract" architecture of the neighboring skill doc-html-report, but rather than a continuous-scroll document, it provides a 16:9 slide sequence + its own vanilla JS deck runtime(keyboard navigation, fullscreen,?print-pdf print mode, speaker notes toggle).
Core principles:
- Single
.htmlfile — opens instantly viafile://with no external build step or runtime SPA dependency - Infographics are authored directly by the LLM as inline SVG — 100% accurate Korean numbers and labels, sharp when zoomed, reproducible
- Photographic and illustration images are generated with Higgsfield MCP or codex(gpt-image-2) — only permitted backends are used (
references/image-backend-policy.md) - design-system-library 75 brand tokens applied — each token provides a getdesign.md detail page link
- Editable PPTX output is delegated to
doc-pptx(moai-coworker) chaining — not implemented in-house (to prevent duplication and blurred responsibility)
Manuscript SSOT: Every deck uses a structured manuscript deck.json(title/bullets/chart-data/image-path/layout-key/notes) as its single source of truth. Both HTML rendering and (when chained) doc-pptx PPTX rendering consume the same manuscript — not pixel→OOXML reverse mapping but direct manuscript→object generation is the guarantee mechanism for "editable PPTX."
Input
| Argument | Required | Default | Description |
|---|---|---|---|
topic / natural-language topic |
✓ | — | Deck topic, target audience, presentation purpose |
design_system |
— | claude |
claude | clickhouse | clay or the 75 systems of design-system-library. When specified, applies the corresponding brand tokens via Tailwind Play CDN + shadcn vanilla components. The getdesign.md preview link for each token is in references/design-system-links.md |
slide_count / presentation duration |
— | recommended from topic | 3분=5-7장 · 10분=10-15장 · 30분=20-30장 |
aspect_ratio |
— | 16:9 |
16:9(projector standard) | 1:1(social/card news) |
locale |
— | ko |
ko | en — headline and copy language |
image_backend |
— | higgsfield |
higgsfield(Higgsfield MCP, default) | codex(gpt-image-2, ChatGPT subscription quota) | svg-only(SVG decoration only, no images) |
export_pptx |
— | false |
true When specified, produce an editable .pptx in parallel via doc-pptx chaining |
output_path |
— | <cwd>/reports/<slug>-slides-<YYYYMMDD>.html |
Output path |
Output
- Primary deliverable: a single
.htmlfile (<cwd>/reports/<slug>-slides-<YYYYMMDD>.html)- self-contained: opens directly in the browser, can be emailed as an attachment, and used offline
- External dependencies: when design_system is specified, font CDN + Tailwind Play CDN; when unspecified, only 1 font CDN
- Parallel deliverables (
export_pptx: true): editable.pptx(doc-pptx chaining) - Manuscript:
deck.json(common source for both HTML and PPTX, preserved in the output directory)
Core workflow (9 steps)
1. Collect context
AskUserQuestionwith design_system (75 systems, default claude) · presentation time (number of slides) · whether images are needed · whether PPTX output is needed. When selecting design_system, references/design-system-links.mdguide users to each token detail page via the getdesign.md link so they can check with a preview. Lecture/presentation context — In environments with many non-developer audience members, daytime, and projectors, light themes (claude, notion, apple, stripe, mintlify) are safe. Dark is recommended only when the presentation space can be dimmed.
2. Build manuscript SSOT (core)
deck.json Write the manuscript first — title/bullets/chart-data/image-path/layout-key/notes. This manuscript is the common source for both HTML rendering and doc-pptx PPTX rendering. Schema: references/deck-manuscript-schema.md. layout-key is aligned with the 9 doc-pptx archetypes (Title/Agenda/Problem/Solution/Features/Stats/Team/CTA/Closing).
3. Infographic = generate inline SVG directly
Charts, diagrams, KPI cards, and timelines are written directly by the LLM as inline SVG. To ensure 100% accuracy of Korean numbers and labels, do not fall back to bitmap images. Pattern library: references/inline-svg-infographics.md.
4. Generate bitmap images (if needed) — image backend policy
Only slides that require bitmaps that cannot be expressed as SVG, such as photo heroes or illustration concepts, are generated with an image backend. Policy: references/image-backend-policy.md.
| Backend | Model | Authentication | Recommended use |
|---|---|---|---|
higgsfield (default) |
GPT Image 2·Nano Banana Pro·Soul 등 11종 | Higgsfield MCP(API 키) | Production, idempotent, unattended CI |
codex (official addition 2026-06-17) |
gpt-image-2 | codex CLI + ChatGPT OAuth (subscription limit, no API key required) | Local, developer, reuse of subscription limits |
antigravity |
Imagen·Nano Banana (agy -p) | Google OAuth browser + subscription quota | ⚠️ Not recommended — OAuth/quota/unattended CI not possible, local one-off prototype only |
svg-only |
(no image) | — | Offline, cost-sensitive, fast fallback |
Only the above 4 backends are allowed. Other external image backends (MCP, API, gateway) are not used —
references/image-backend-policy.md.
If Korean text is included in the image, moai-media:media-gpt-image-2-promptafter giving verbatim instructions with (6-Block prompt builder), generate with the selected backend.
5. Apply design-system-library tokens
When design_system is specified, systems/<name>.md render tokens → Tailwind Play CDN config + shadcn vanilla components. If unspecified, zero-dependency default template. Reuse the same contract as doc-html-report. Users can check tokens in advance via the getdesign.md link and then select.
6. Assemble single-file HTML deck
16:9 slide container + own vanilla JS deck runtime (keyboard navigation, fullscreen,?print-pdf print mode, speaker notes toggle, progress bar) into a single .html. Runtime implementation: references/html-runtime.md.
- [HARD] Do not render production metadata outside the slides. such as slide count, resolution, number of diagrams, and fonts used; production metadata is not a deliverable but a working note. (Deck control UI such as counters, progress bars, and speaker notes does not fall under this — rubric §production metadata assessment.) If necessary, leave it in HTML comments (
<!-- -->) or indeck.json, and do not put it anywhere that appears on screen — it will be visible to students and clients as is. Rubric #34 checks this as a hard fail. - Icons follow the
deck.json의icon+icon_reasonpair as is (schema §icon slot contract). Do not arbitrarily substitute them at the rendering stage.
7. AI slop post-processing (mandatory)
Apply the ai-slop-reviewer → korean-humanize chain to all slide copy and speaker notes text. Mandatory post-processing rule of this skill (must pass before distribution).
Slide copy QA checklist — 3 types of structural slop S1 patterns (mandatory detection for headlines and copy): Korean structural patterns that the two gates must catch. Detection occurs at the sentence structure level, not the word dictionary level.
| # | Pattern | Detection signal | [Bad example] | Fix |
|---|---|---|---|---|
| 1 | Em-dash contrast headline | Sentence split with an em dash (—) into "X — Y" (em-dash contrast headline) |
[Bad example] "From copy-paste to delegation — if you only give the goal" | Remove the em dash, merge into one sentence, or split into two sentences |
| 2 | Particle/noun-ending fragment | Particle/noun-ending fragment (ends with a particle/noun) | [Bad example] "The key to success — automation" (particle/noun ending) | Rewrite as a complete sentence including a predicate |
| 3 | "From A to B" transition formula | Introduction of the "from X to Y" transition formula | [Bad example] "From Excel to Notion, what changed" (transition formula) | Start with a concrete example instead of a transition formula |
8. PPTX output (optional, when export_pptx: true)
deck.json Pass the doc-pptxmanuscript to (moai-coworker) and chain. doc-pptx generates editable OOXML .pptx with pptxgenjs (manuscript → direct object generation). doc-html-slide itself does not implement PPTX generation logic. Chaining contract: references/pptx-chaining.md.
9. Quantitative QA scoring (mandatory)
[HARD] Render the produced HTML in a browser and score it against the references/deck-quality-rubric.md's 34 criteria. This step is a mandatory gate of the same grade as §7, and is not replaced by a visual skim — the rubric requires DOM measurement (getBoundingClientRect·computed font-sizeand contrast ratio calculation), and those numbers are the evidence.
Why it is nailed down as (mandatory). There was a case where, during the period when this rubric was attached only to the reference document list and was not called at any workflow stage, 12 of the 14 body text types in an actual output deck were distributed while falling below the hard-fail lower bound (#9). The Korean copy in the same deck was excellent — because §7 was in the workflow as "(mandatory)". A gate does not work by mere existence; it works only when it is attached to the pipeline.
9 hard criteria (8 failure groups) — if even one is triggered, reject, fix, and re-render. (#32 and #33 are both icon issues, so they are reported as one failure group, but scoring is done by two independent functions.) (All thresholds are qa-config.json override targets and are not hardcoded as constants.)
| # | Criterion | DOM measurement | Default threshold |
|---|---|---|---|
| 9 | Body font lower bound | Body node computed font-size. Slide width → judged after conversion to pt (1280px slide = 960pt, i.e. 1px = 0.75pt) |
≥24pt (can be lowered to 18pt for online-only decks) |
| 16 | Contrast ratio | WCAG contrast ratio based on relative luminance | Body ≥4.5:1 · Large text ≥3:1 |
| 17 | 3D chart effects | SVG/CSS perspective·rotateX/Y·3D shadow |
Reject when detected |
| 20 | Grid alignment deviation | Standard deviation of coordinates of elements with the same role (title/footer) | Within 1% of slide width |
| 24 | Source line for numerical slides | On slides with numbers, charts, or tables, 출처:/자료:/Source: node |
Reject if absent |
| 28 | Text overflow | scrollHeight > clientHeight or below lower bound after shrinking |
Reject if it occurs |
| 32 | Icon vocabulary diversity | Per normalized icon ID Maximum usage count(max_count_per_normalized_icon) |
Same icon ≤3 times (exceptions for repeated roles are determined by rubric §icon rationale judgment) |
| 33 | Icon semantic rationale | icon_reasonDoes this actually correspond to the verb/action of that phrase — do not pass it merely because the field exists |
Reject if correspondence is unknown |
| 34 | Production metadata exposure | Rendered outside the slide Production metadata·debug text | 0 (runtime UI is allowed — see §below) |
- [HARD] Do not omit pt conversion. #9 judges not the px value but actual projected size. Body 18px in a 1280px deck is 13.5pt, slightly more than half of the projector-based lower bound (24pt). A value that "looks large enough" in px alone gets caught here.
- [HARD] Projected decks for lecture halls and conference rooms do not apply the online relaxation (18pt). Relaxation is limited to archive decks that will only be viewed on screen. If it is unclear which one it is, confirm with the user in §1.
- The soft 25 criteria are scored by a weighted sum of 6 categories and reported along with the score. If it falls below the passing threshold, present the per-item values to the user and confirm whether to revise.
Render inspection practical cautions: Decks with many slides can have a total document height reaching tens of thousands of px, and browser screenshots may return blank images. Measurement should be done not with screenshots but with DOM API(getBoundingClientRect·getComputedStyle·elementFromPoint) and, and if visual confirmation is needed, leave only the target slide and collapse the rest with display:nonebefore capturing.
Other feature checks: Check opening a single HTML,?print-pdf print preview, display of speaker notes, broken image links, Korean font rendering, and compliance with the image backend policy (use only allowed backends), then report PASS/FAIL. When chaining to PPTX, report the doc-pptx QA results together.
Approval request contract (runtime-neutral)
[HARD] The gates of this skill are not tied to specific tool names. AskUserQuestionis merely a means in the Claude runtime, and other runtimes including Codex do not have that tool. If the contract is written in terms of tool names, then in runtimes without that tool the gate becomes an permanent blocker, and all work requiring approval simply stops. That is not safety but failure.
Obtain approval in the following order. From the top, use the first one actually possible.
The definition of approval is not the means but the result: showing the approval form to the user as-is and receiving an explicit response to it. Below are the paths that produce that result, and use the first one possible from the top.
| Rank | Path | Condition |
|---|---|---|
| 1 | The runtime's structured question tool (AskUserQuestion 등) |
When that tool is exposed in the current session |
| 2 | Present the approval form in normal conversation and receive the response on the next turn | When in direct conversation with the user. This path is always open even without the tool |
| 3 | Return a structured blocker → the parent orchestrator asks | When running as a subagent |
[HARD] The runtime's tool execution permission prompt is not approval. That prompt only asks "may this tool be called", and does not display the arguments, estimates, or consent items the gate is supposed to show. Only if the entire approval form and options are actually displayed is it recognized as path 2.
[HARD] Because path 2 exists, the situation of "having no means to ask" is virtually nonexistent. Wherever conversation is possible, the approval form can always be presented in writing. fail-closed applies only to fully unattended execution where neither conversation nor blocker return is possible— only in that case does it stop without executing.
[HARD] When using option 3, the blocker itself must be an approval request. If the superior does not know what to ask, they cannot ask back, and then it deadlocks. It includes all of the following:
- The action to be approved in one line (what is irreversible / how much money is going out)
- All arguments required by the gate (values not summarized)
- List of options — a form the superior can present to the user as-is
- How to resume — upon receiving which answer, what is executed next
[HARD] In unattended execution where all three paths are impossible, do not execute (fail-closed). Having no means to ask does not mean approval was obtained. In this case, record "could not proceed because there was no means of approval" and stop — do not proceed silently. Conversely, stopping because there is no tool even though conversation is possible is also wrong. Use path 2.
This contract is
CLAUDE.local.mdthe gate-side application of §Generality Principle (identical behavior across 2 OSes × 2 runtimes). A gate that runs on only one runtime is considered incomplete.
Design system application (design_system parameters)
design_system As input, load brand tokens from moai-officer:doc-design-libraryand render with Tailwind Play CDN + shadcn vanilla components. It provides the same two render engines as doc-html-report.
design_system |
Engine | External dependencies | Output characteristics |
|---|---|---|---|
| Unspecified | Zero dependencies (default template) | Only 1 font CDN | Offline, print, and email attachment possible |
claude / clickhouse / clay / 75개 |
Tailwind Play CDN | Tailwind CDN + font CDN | Brand mood applied, internet connection required |
Slides suited per theme (automatic recommendation)
| Presentation nature | Recommended design_system |
|---|---|
| Business plan, report, editorial (default) | claude (warm editorial, cream + coral) |
| Technical, data, engineering, dark projector | clickhouse (dark tech) |
| Product introduction, SaaS, startup | notion·apple·stripe·mintlify (light, clean) |
| Marketing, keynote, impact | spotify·nike·airbnb (bold) |
| Non-developer audience, daytime, projector (light safe) | claude(default) · notion · apple · stripe · mintlify |
| Dark (when the room can be dimmed) | clickhouse · vercel · linear.app · supabase · binance |
Lecture recommendation (based on the getdesign.md collection showcase of 74): in a non-developer audience (about 75%), daytime, projector environment, light is safe. Currently,
claudeis reasonable, and if you want to make a change,notion·apple·stripe·mintlify. Dark only when the presentation space can be dimmed —clickhouse·vercel·linear.appetc. Of the total 75, 19 (⚙️) are lightweight tokens, so fonts are based on system sans-serif.
getdesign.md preview link
For each design_system value, references/design-system-links.md의 https://getdesign.md/<slug> link to the detail page. Before choosing a theme, users can open the link to directly check the palette, typography, and mood. The mapping table for all 75 systems (repository system name → getdesign.md slug) is managed in that file.
Chaining Integration
[원고/콘텐츠 스킬] → moai-coworker:ai-slop-reviewer → moai-writer:korean-humanize → moai-officer:doc-html-slide
↓ (export_pptx: true)
moai-officer:doc-pptx
When an image is needed, branch:
doc-html-slide → moai-media:media-higgsfield-image (Higgsfield MCP, 기본)
→ moai-media:media-gpt-image-2-prompt (한국어 verbatim 프롬프트 빌더) → media-higgsfield-image
→ codex exec "$imagegen ..." (image_backend: codex 시, 로컬)
design_system application is automatically loaded from design-system-library — no separate prior skill call is required.
Usage Examples
Example 1: Business plan slide (default claude theme)
AI 슬라이드 스킬 스타트업 사업계획서 10장 슬라이드로 만들어줘. claude 테마로.
Example 2: Data infographic slide + PPTX
3분기 매출 분석 슬라이드 HTML로 만들고, 편집 가능한 PPTX로도 저장해줘.
Example 3: Dark theme tech presentation
신규 API 아키텍처 기술 발표 15장, clickhouse 다크 테마로 슬라이드 HTML 만들어줘.
Example 4: codex backend image
제품 런칭 슬라이드 만들어줘. 히어로 이미지는 codex로 생성하고, notion 테마 적용.
Example 5: Preview themes and choose
슬라이드 만들 건데, 디자인 토큰 후보들 getdesign.md 링크로 보여주고 내가 고를게.
What Not to Do
- Continuous scroll documents are
moai-officer:doc-html-report's responsibility — this skill is dedicated to slide sequences (16:9 pages). - It does not directly generate editable .pptx —
doc-pptx(moai-coworker) chaining delegates it. - Prompts for NotebookLM input are
moai-media:media-notebooklm-slide-prompt's responsibility. - It does not introduce build steps or runtime SPA dependencies such as React/Vue/webpack/vite —
file://immediate open is the principle. references/image-backend-policy.mdOnly the allowed backends (Higgsfield MCP + codex) are used. Other external image backends are not used.- It is not split into multiple files — the HTML output is a single
.htmlfile.
Reference Documents
Design Document
references/deck-manuscript-schema.md— deck.json SSOT schema + doc-pptx archetype mapping conventionreferences/html-runtime.md— self-contained vanilla JS deck runtime (navigation, fullscreen,?print-pdf, speaker notes, zero dependencies)references/inline-svg-infographics.md— inline SVG infographic patterns (charts, diagrams, KPIs, accurate rendering of Korean numbers/labels)references/image-backend-policy.md— image backend policy (Higgsfield + codex official, antigravity not recommended, allowed backends only)references/pptx-chaining.md— doc-pptx chaining convention (editable PPTX guarantee mechanism)references/design-system-links.md— mapping table of 75 systems → getdesign.md linksreferences/deck-quality-rubric.md— slide quantitative QA rubric (6-category weighted sum + hard-fail, HTML/DOM reinterpretation, shared with doc-pptx)references/editorial-deck-doctrine.md— editorial deck doctrine (13-slot layout vocabulary + overflow=0, period action title copy rules — complements mandatory slop chain)
Sample
samples/deck-sample.json— 8-slide business presentation manuscript (deck.json SSOT)samples/deck-sample.html— completed single-file HTML deck (design_system: claude applied)
Neighboring Skills (Chaining)
moai-officer:doc-design-library— 75 brand token SSOTmoai-officer:doc-pptx— editable .pptx generation (chaining)moai-media:media-higgsfield-image— Higgsfield MCP image (default backend)moai-media:media-gpt-image-2-prompt— Korean verbatim image prompt buildermoai-coworker:ai-slop-reviewer→moai-writer:korean-humanize— mandatory post-processing chain
Self QA
When slide generation is complete, open the produced single .html in a browser and check the number of slides, 16:9 ratio, navigation,?print-pdf print mode, speaker notes, Korean font rendering, and infographic SVG accuracy by self-review, and after confirming compliance with the image backend policy (using only allowed backends), report the PASS/FAIL result. When chaining PPTX, integrate and report the doc-pptx QA results (empty placeholders, overflow, color contrast 4.5:1). If there are issues, automatically fix them and regenerate.