ppt-agent-skills: a state-machine pipeline that turns one prompt into a PPTX

The failure modes this pipeline is built to prevent

Ask a language model for a fifteen-slide deck and you get three recurring defects: content that was never in your source material, text boxes that overlap once rendered, and a layout that drifts between page four and page eleven. PPT Agent's README names these directly, describing the framework as solving hallucination, overlap and layout disorder "from the root". The claim is a positioning statement, not a measurement, but the architecture that follows is consistent with it. The intended user is someone who already works inside an agent environment that supports Skills and wants presentation output without hand-placing shapes in PowerPoint. The README's own example prompt asks for a fifteen-page pitch deck on embodied AI trends in a dark technology style, which tells you the target is a full deck, not a single slide. Anyone who needs one diagram, or who needs to edit an existing corporate template, is outside the intended path.

Seven stages, four isolated subagents and a gate after every artifact

The workflow runs P0 interview, P1 branch confirmation, then a fork: P2A does web search while P2B compresses local source material. P3 produces the narrative outline, P3.5 locks global style, P4 runs per-page production in parallel through Planning, HTML and Visual QA, and P5 handles preview plus dual PPTX export. Two mechanisms carry the weight. First, stage isolation: Research, Outline, Style and Planning each run their own subagent, and the README states that context does not cross between them and that every subagent is created with a mandatory SUBAGENT_MODEL parameter, with no fallback to a default. That is a deliberate refusal to let one long conversation accumulate drift. Second, the artifact chain is the state. The README lists it as interview-qa.txt to requirements-interview.txt, then search.txt plus search-brief.txt or source-brief.txt, then outline.txt, style.json, planningN.json, slide-N.html, slide-N.png, preview.html, the two PPTX files and delivery-manifest.json. Each stage's output is written to disk and checked by a Gate before the next stage proceeds; a failure rolls back only the current step. Recovery is stateless: after an interruption the system scans for existing artifacts such as outline.txt, style.json or slide-N.png and infers where to resume. There is no progress file to corrupt, which is a cleaner design than a job database, though it does mean an artifact that exists but is stale will be trusted.

The JSON contract between data and rendering, and what visual_qa.py actually asserts

Per-page production separates data from rendering. A planningN.json contract is generated first and must pass planning_validator.py before any HTML is written. The v4.1 release notes add density_bias at Step 3 and a density_label / density_contract pair at Step 4, which turns page density from a stylistic hope into a declared, checkable budget. Once the contract passes, HTML rendering follows, and a static structure probe at the html level rejects non-conforming skeletons. Then the visual loop: every page is screenshotted and audited by a model. When layout overflow is detected, the README says the subagent rewrites DOM and CSS structure rather than adjusting spacing. That distinction matters. Nudging margins produces a page that fits by accident; rewriting the structure produces one that fits by construction. The v4.1 notes also state that visual_qa.py gained a two-layer assertion covering planning plus html, so it checks structure and decoration budget in addition to looking at the picture. A separate subagent_logger.py records stage commands and run logs for PageAgent and PagePatchAgent, which is what makes partial rework auditable rather than guesswork. The README does not state which model performs the visual audit, what tolerance counts as overflow, or what happens when the rewrite loop fails to converge. Treat those as open questions to answer from the scripts.

Installing it as a Skill, and the artifacts it leaves on disk

There is no server to deploy and no Python package to install. The README gives one command: npx skills add sunbigfly/ppt-agent-skills. After that you invoke the pipeline by describing the deck you want in a Skill-capable agent environment. Output lands in ppt-output/runs/<RUN_ID>/, which contains the web preview and both PPTX formats. The repository separates concerns into SKILL.md as the main console holding the state machine, gates and recovery rules, scripts/ for the validator, harness and exporter executables, and references/ for Markdown knowledge sources mounted on demand: playbooks/ for per-stage subagent manuals, styles/ for theme specifications, layouts/, charts/ and blocks/. The README advertises eight theme styles, ten layout types, thirteen chart templates, eight component classes and fifteen script tools. Those counts are from the project's own badges and I have not verified them against the tree. The one configuration key named in the material is SUBAGENT_MODEL, which the README says is mandatory on every subagent with no default fallback, so an environment that cannot supply it will fail at subagent creation rather than degrade quietly.

Where the design constrains you, and when to use something else

The gate model is the main cost. Every stage must pass before the next begins, and the density contract in planningN.json means the page budget is fixed before rendering starts. If your content genuinely needs a dense appendix slide, you are working against the validator rather than with it. The visual QA loop is also the slowest part of the pipeline by construction, since each page is rendered, screenshotted and audited, and overflow triggers a structural rewrite. For a five-page internal summary that trade is hard to justify. The stateless recovery has a matching weakness: because resume points are inferred from files on disk, editing outline.txt by hand mid-run can desynchronise the pipeline from its own artifacts. And the Skill-only distribution is a real boundary. If your environment does not support Skills, npx skills add gives you nothing to run. A conventional alternative is python-pptx, which drives PowerPoint files directly through an object model: you write explicit code for each shape, text run and position, and you get deterministic output with no model in the loop. The difference in approach is total. python-pptx asks you to specify every element and gives you exact control; PPT Agent asks you to specify intent and gives you a contract, a rendered page and an audit trail. If your deck is a fixed template filled with data, python-pptx is the shorter path. If your deck is prose that has to become a layout, the contract-and-audit model is doing work that hand-written shape code cannot.

Maintenance, licensing and the gaps in the record

The repository is not archived and the last push is dated 2026-06-08, with the most recent changelog entry at v4.1 on 2026-04-09. No releases were retrieved, so versioning appears to live in the README changelog rather than in tagged releases, which makes pinning a specific version harder than it would be otherwise. Upgrading means pulling the Skill again and re-reading the changelog for contract changes; the v4.1 notes are a good example of why, since adding density_bias and density_label changes what planning_validator.py will accept, and a deck produced under the previous contract may not validate under the new one. The install line advertises MIT and the repository contains a LICENSE file, but the licence identifier returned for the project is NOASSERTION, meaning the metadata does not confirm MIT. Read the LICENSE file itself before you depend on the terms. The README's design-philosophy section, which describes sealing physical safety walls and baseline coordinates while releasing typography, overlap depth and whitespace privileges to the model, is the least concrete part of the document; it names an intent without specifying the coordinate system or the wall positions, so the actual constraints have to be read out of the layout references and the validator. That is where I would start.

Editorial conclusion

Adopt it if you already run a Skill-capable agent environment and want deck generation with a checkable intermediate state: the planningN.json contracts and the visual_qa.py assertions are the parts worth evaluating first. Do not adopt it if you need a standalone CLI, a documented Python API, or a pip-installable package, because none of those appear in the repository. Before committing, run one deck end to end and inspect ppt-output/runs/<RUN_ID>/delivery-manifest.json alongside the planningN.json files to see whether the gate failures land where you can fix them.

Official sources

1. Issues
2. README
3. sunbigfly/ppt-agent-skills on GitHub