18trees-ppt-maker

What it is

18trees-ppt-maker is a cross-tool AI skill that takes raw material all the way to an HTML deck and PDF you can send to other people as-is. It works with Claude Code, Codex, and any AI tool that can read and write files and run Node scripts, and it serves decks that have to go out to others: investor material, pitch decks, project reviews, industry talks.

What it sets out to overturn is the default premise behind most decks — that a deck is support material for a script, with whitespace waiting for the speaker to fill in and small print waiting for the speaker to explain. Sent straight to someone with no speaker beside it, such a deck falls apart at once. So the skill holds one test: can a person who knows nothing about the background, looking only at this page, understand by themselves what it is trying to say? Anything that answers “no” is either made clear or deleted — there is no third option.

How it is structured

The project has three layers: the rule source, the workflow, and the upstream engine it depends on.

Rule source. skills/ppt-maker/ is the single source of truth: SKILL.md defines the six-phase workflow and the 10 P0 rules; references/ holds the taste profile, the sub-agent review spec, and the layout details; scripts/ holds two scripts built only on the Node standard library — independent-reading static checks, and PDF export plus packaging — along with a real-name blacklist template that ships empty. Distribution goes through the plugin manifests, one for Claude Code and one for Codex.

Workflow. Raw material first becomes a two-part narrative outline (phase 1), then goes through style and layout choices into a single-file HTML deck (phases 2–3); next come the static checks and the independent review (phase 4), the two viewport checks (phase 5, desktop 1440×900 and mobile 390×844), and the PDF export with packaging (phase 6). The order cannot be shuffled: move on before the previous step is stable and everything downstream is reworked.

Upstream engine. Rendering is not this project’s job: guizang-ppt-skill (AGPL-3.0) renders the deck, and this project only reads the upstream directory installed on your machine by path at runtime. The repository contains none of upstream’s code, templates, or documentation assets, so this is a plugin relationship, not a merged distribution.

Design decisions worth noting

A generator cannot review its own work, so the review is mandatory and external. Every finished version of the deck requires a sub-agent that plays the client and reviews it independently, and it receives only three inputs: the produced HTML, the taste profile, and the narrative outline — never the background, never the design rationale. It must answer 14 checks one by one and produce a list with page numbers and quotes from the source, and it is required to find at least 5 problems; once fixed, it runs again until the list is empty. The spec and the full prompt template live in reviewer-persona.md.

Taste grows out of rework, not design. taste.md is the real heart of the skill: every hazard keeps the client’s original wording and date and spells out the trigger and the fix, and it is continuously appended. The whole rule set came out of six rounds of real feedback on one 14-page commercial deck; new feedback follows a fixed order — into taste.md first, then a decision on whether to promote it into SKILL.md as a P0 rule, then into the validator if a machine can judge it.

Machines judge what they can; review judges the rest. The two scripts have zero npm dependencies: validate-ppt.mjs blocks page-number continuity, font-size floors, and stray small print at the bottom; export-pdf.mjs drives a local Edge or Chrome to export the PDF and package the bundle. Neither can replace the sub-agent review — whether a page can be understood is not something a machine can decide.

The boundary with upstream is deliberate. Copying none of upstream’s assets and reading them by path at runtime is exactly what lets this project choose MIT on its own; bundle the two together and the whole thing must become AGPL-3.0 with attribution preserved.

What problems it solves

• “Can this deck be sent without a speaker?” now has one shared test instead of scattered layout preferences.
• Page-number continuity, font-size floors, stray small print at the bottom, English labels, unexplained abbreviations, placeholders, body text hidden behind display:none on mobile, and real names — all machine-checkable, and all stopped by a script before the deck reaches anyone.
• PDF export works around horizontally paged decks, where printing directly yields only one page, and produces a page-by-page result.
• Delivery is always a three-file bundle with a shared prefix in one folder: the outline Markdown, the HTML, and the PDF.
• Unsettled numbers are written qualitatively and credits use roles rather than real names, so the material is safe to hand out.