Prose to Deck

Transform long-form writing into a polished, full-screen scrollable HTML presentation.

Output is a single self-contained .html file inside a dedicated project folder.

Example requests

• Turn this article into a scrollable slide-style HTML presentation.
• Visualize this essay as a polished single-file presentation for review.
• Convert this transcript into an editorial HTML deck with mode=auto.

Execution Modes

In both modes, every stage produces a file. The difference is only whether execution pauses for approval.

HITL response rules (applies to all checkpoints):

• User replies "go" → update progress.md status to approved, continue to next phase
• User replies with change instructions → apply changes, re-notify
• mode=auto → log decision to Decisions Log, continue immediately

Project Folder

Every execution creates a dedicated working directory. By default it lives under ./projects/ in the current working directory. All intermediate work and the final output live there unless you intentionally pass a different project root to the init script.

projects/<slug>-<timestamp>/
  progress.md              ← created by init script; tracks stage status throughout execution
  01-analysis.md           ← Phase 1 output: content analysis
  02-slide-plan.md         ← Phase 2 output: slide sequence plan  [HITL-1]
  03-visual-direction.md   ← Phase 3 output: visual direction decision  [HITL-2]
  04-build-notes.md        ← Phase 4 output: per-slide layout notes
  index.html               ← Phase 4 output: final presentation

Artifact formats are defined in individual reference files:

• progress.md format → references/artifact-progress.md
• 01-analysis.md format → references/artifact-analysis.md
• 02-slide-plan.md format → references/artifact-slide-plan.md
• 03-visual-direction.md format → references/artifact-visual-direction.md
• 04-build-notes.md format → references/artifact-build-notes.md

Resuming interrupted execution: read progress.md to determine where to resume. Do not re-run stages already marked done or approved. Use this table:

When resuming from Phase 3 or later, re-read the references for that phase before continuing — do not assume prior context is still loaded.

Phase 1 — Content Analysis

Goal: Understand the source material. No design decisions yet.

Read: references/artifact-analysis.md

Steps

1. Parse invocation parameters: source, author, mode, style. If source is missing, ask the user to provide it before proceeding.
2. If source is a file path, read the file. Do not proceed until full content is read.
3. Derive the base slug from the article title (lowercase, hyphens, max 40 chars). Then run the bundled Python init script to create the project folder and all artifact files:

```bash

python scripts/init_project.py "" "" "" "$(pwd)/projects"

```

If the environment exposes python3 instead of python, use python3 with the same arguments.

The fourth argument is the project root. Use $(pwd)/projects by default, or pass a different absolute path only when the user explicitly wants another location.

The script appends a timestamp with second-level precision to the slug (for example career-guide-20260401-143022) and adds a numeric suffix if needed to avoid collisions. It then creates the project directory, writes the initial progress.md, and touches all artifact files.

Capture the final slug from the script's stdout and combine it with the project root to get the actual directory path for all subsequent file paths.

Do not create any project files manually.

1. Update progress.md: phase1: in-progress. Then immediately update the Source field in progress.md with the actual file path provided (or "inline text" if the content was given directly in the message). The init script cannot know the source — this is your responsibility to fill in.
2. Answer these three questions:

How many distinct ideas are here?

Count ideas, not words. A 2000-word essay built around one central claim is still one idea.

Five short paragraphs each making a separate argument are five ideas.

What is the logical structure?

Don't force the content into a named category. Instead, ask:

• What does the author want the reader to _feel_ by the end — convinced, equipped, reframed, or moved?
• Where does the tension live? Is it between old and new, between two opposing views, between a problem and its fix, or between what people believe and what's actually true?
• How does the argument move? Does it build (each idea requires the previous), branch (parallel threads that converge), or spiral (returning to the same core from new angles)?
• Is there a moment of surprise or reversal? Where does it land in the sequence?
• What would be lost if you removed the first slide? The last? That tells you what's load-bearing.

Name the structure in your own words — something like "builds from misconception to correction" or "three parallel lenses on one problem" is more useful than a generic label. The name should predict the slide sequence.

What is the single most important thing?

If this presentation had only one slide, what would it say?

1. Write 01-analysis.md (format: references/artifact-analysis.md).
2. Update progress.md: phase1: done.

Proceed to Phase 2 immediately. No HITL here.

Phase 2 — Slide Plan

Goal: Decide how to map the content into a slide sequence. This is a creative decision.

Read: references/artifact-slide-plan.md, references/headline-system.md

Steps

Update progress.md: phase2: in-progress.

For each slide, determine:

• Job — one phrase, 5 words max. If you can't name it, split the slide.
• Main claim — the one thing it must communicate. This is the full judgment, not automatically the on-screen title.
• Display headline — the title language the reader sees first. By default this should be shorter, sharper, and more visual than the full claim.
• Support line — optional, but strongly encouraged whenever the headline is compressed. Use it to recover nuance instead of forcing the headline to carry the entire argument.
• Content shape — what is the natural form of this information?

Content shape questions to ask:

• A single powerful statement — how much space does this idea need to land?
• Two things in tension — how should their visual weight relate?
• Parallel items with no ranking — what holds them together without implying order?
• Items with a clear hierarchy — how does size, position, or weight express the levels?
• A progression over time — what connects the steps, and what separates them?
• A quantitative claim — does a visual encoding make the magnitude more immediate?
• Relationships between concepts — are the connections as important as the nodes?
• A quote or moment of emphasis — what does this need around it to land with force?

Sequence rules:

• Always open with a cover (title + core thesis + @author if provided)
• Always close with a conclusion (key takeaway, not a summary of summaries)
• Every slide earns the next — the sequence should have momentum
• Never pad to hit a number.
• Never compress two distinct ideas to save space.
• Hard limit: maximum 15 slides total. If the content analysis yields more than 13 distinct ideas, make merging decisions here — combine closely related ideas into one slide rather than deferring the problem to Phase 4. A presentation that can't be told in 15 slides hasn't been edited yet.

Headline rules:

Use references/headline-system.md.

In Phase 2, explicitly choose Display headline and Support line instead of assuming the Main claim becomes the title.

Record only genuine poster-style exceptions in the Headline exceptions section of 02-slide-plan.md.

Write 02-slide-plan.md (format: references/artifact-slide-plan.md).

HITL-1 Checkpoint

Update progress.md: phase2: awaiting-approval (review) or phase2: approved-auto (auto).

If mode=review: notify the user and stop. Use the actual project directory path, not the placeholder:

✋ HITL-1 — Slide plan ready

Wrote `[project-dir]/02-slide-plan.md`.
This is the most important checkpoint; the plan drives all downstream work.

Reply: go / change requests

If mode=auto: log to progress.md decisions log and continue:

[AUTO] HITL-1: <N> slides
  Core thesis: "<thesis>"
  Slide jobs: Cover | <job2> | <job3> | ... | Conclusion

Phase 3 — Visual Direction

Goal: Establish the visual identity of this presentation. This is a design judgment, not a form to fill.

Read: references/design-system.md, references/artifact-visual-direction.md

design-system.md contains design principles — how to think about color, typography, layout, motion,

and consistency. Read it to inform your judgment, not to find ready-made answers.

materials.md (loaded in Phase 4) contains the actual implementation tools — CDN links, libraries,

CSS patterns. Don't pre-read it now.

Steps

Update progress.md: phase3: in-progress.

Seed check (always run, regardless of whether style was passed): Read references/style-seeds.md now. Scan the available seeds and identify whether the content clearly matches one by background and tone. Record your finding in 03-visual-direction.md under a Seed match field — even if no style parameter was passed. This makes the design decision reproducible and surfaces the seed system to future runs.

If style= was passed at invocation: find the matching seed and treat its background, tone, and avoid fields as hard constraints for this phase. Everything else — specific palette values, typefaces, motifs, atmosphere — is still decided by content analysis. The seed narrows the search space; it does not replace the design judgment.

If no style parameter was provided: let the content lead entirely. If a seed matches well, note it but do not treat it as a constraint — it is informational only. Ask yourself:

What does this content feel like?

Not what category it belongs to — what is its texture? A technical argument has different weight than

a personal essay. A call to action has different energy than a retrospective. The visual direction

should make that texture visible.

Who encounters this, and where?

A presentation shared on social media needs to pop at thumbnail size. A focused reading session

rewards quieter, more typographic choices. A live screen presentation benefits from high contrast

and generous scale. The same content can be right for different contexts — pick one and commit.

What should the reader feel on the first slide?

Intrigued? Challenged? Welcomed? Impressed? That emotional entry point shapes everything:

background darkness, type weight, accent intensity, whether atmosphere effects add drama or distraction.

What visual idea could make this memorable?

Beyond palette and fonts — is there a structural visual motif that could run through the presentation?

A recurring geometric element, a consistent use of negative space, a typographic treatment that

becomes a signature? The best presentations have a visual idea, not just a visual style.

From these answers, make decisions and commit to them. Write 03-visual-direction.md

(format: references/artifact-visual-direction.md) — but treat the format as a minimum record,

not a ceiling. If your direction has nuances the format doesn't capture, add them.

HITL-2 Checkpoint

Update progress.md: phase3: awaiting-approval (review) or phase3: approved-auto (auto).

If mode=review: notify the user and stop. Use the actual project directory path, not the placeholder:

✋ HITL-2 — Visual direction ready

Wrote `[project-dir]/03-visual-direction.md`.

Reply: go / change requests

If mode=auto: log and continue:

[AUTO] HITL-2: —

Phase 4 — Design and Build

Goal: Build the HTML. Phase 2 gives you the content structure; Phase 3 gives you the visual identity.

Use both as your brief. Every slide will still require concrete layout decisions — that's expected.

Make them in the spirit of the plan, not against it.

Read: references/materials.md, references/headline-system.md, references/artifact-build-notes.md, references/qa-checklist.md

materials.md is the implementation toolkit — icon libraries, chart/diagram tools, animation utilities,

CDN links, and CSS patterns with exactly one correct form. Use what the content needs; ignore the rest.

Before starting, re-read 02-slide-plan.md in full. The Content shape column is your primary brief for each slide's layout decision. Do not rely on memory of Phase 2 — the plan is the source of truth.

Update progress.md: phase4: in-progress.

4.1 Output context

This skill produces a full-viewport scroll-snap presentation, not a fixed-pixel screenshot card.

Sizing uses vw/vh units and clamp() — not fixed px dimensions. The layout must be

usable at any screen size. Do not apply fixed-width card constraints from other skills.

4.2 Global setup

Single .html file. All CSS and JS inline.

External resources: Google Fonts for the roles actually used + libraries from references/materials.md only when content requires them.

If the output uses CDN fonts or libraries, the presentation must still preserve readable core text and structure when those resources fail to load.

• Define CSS custom properties from 03-visual-direction.md in :root
• Load Display and Body fonts, plus Mono only if the chosen direction uses it (see font loading notes in references/materials.md)
• Apply atmosphere effects per visual direction
• Set up navigation and reveal system — see references/materials.md for correct implementation patterns

CSS discipline: Only define CSS classes that you will actually use in the HTML of this presentation. Do not pre-define component classes speculatively. If you define a class and then decide not to use it, remove it before moving to the next slide. Every class in