English · Русский
An agent skill that walks you from an idea to a finished bespoke HTML presentation (a deck): slide text, a design brief, the build, a spoken run-through and trimming to the time budget.
Designed for Codex, Claude Code and other agents that can read instructions, work with files and run commands. The shared pipeline does not depend on a model provider. Codex and Claude Code have installation and UI adapters; preview and connector capabilities in other clients need separate verification.
It is not a template filler: the agent reads your material, picks the art direction itself and designs the deck around that specific content — different talks come out as visually different decks (structure, palette, typography, background, character of motion).
The output is a self-contained HTML file: it opens offline in a browser, with no CDN and no network references.
There are two paths, and the user picks one when the skill starts: short — a one-page presentation as a single file, with no presenter window, in one go; full — a talk that the skill leads through the stages "Context → Design → Build → Voice", stopping wherever it needs a step from you.
The skill leads you through this pipeline itself: you call /present, and it walks the stages with you. Where it needs a step from you — record a run-through, pick a style — it says what to do and waits. Below is the pipeline itself: what happens at each stage and why.
The core idea: three files instead of one. It all used to live in a single PowerPoint — text, design and speech together; pull one thread and everything unravels. Here it is three separate jobs with three artefacts. And there is exactly one rule: first get slides.md by any means, and only then deal with design.
The first step is called "context", not "words", on purpose: it does not matter where the material came from — what matters is that slides.md comes out the other end. Two main entry points, both spoken out loud:
- Talk the idea through. Open party mode in BMAD on an empty folder and dictate your idea as a free-form monologue: what I want to say, what has to be in there, what to pay attention to. It works the idea over and asks concrete questions — it turns into a session. Out comes
slides.md: which slides there will be and what I say on each. No design. - Straight to the recorder. If the talk is already in your head — hit record and say the whole thing as it comes. Transcribe it (OpenSuperWhisper locally, model
large-v3— fast and accurate on an M-chip, punctuation and English loanwords included) and hand the transcript to BMAD: "here is the whole talk, break it into slides". - Existing material. Context can be anything: articles on the topic, an entire repository (then the numbers on your slides come from a real
git log), internal docs, someone else's presentation. You drop it into BMAD exactly the same way: "here is the material, lay it out as slides".
The difference between the first two: in the first case the talk is invented together with the model, in the second the model lays out a talk it already has in full. All paths converge on the same point.
In the skill this is the "Context" stage. It runs all three entry points itself, no BMAD needed: an interview about the idea, laying out dictation, text or material, transcribing a recording (if whisper is on the machine). It asks for the time budget up front and estimates the running time from the word count. If the talk runs long, it tells you by how much.
A piece of advice bigger than this pipeline: talk to the model with your voice. Not just for talks — for any task. You say everything you have on the problem, dump your thoughts as they come, and it extracts the substance. When you speak, the flow is freer: you don't edit yourself mid-sentence, you don't hunt for the phrasing.
We are in the AI era — you don't need PowerPoint, generate HTML: models write it well and fast, and it gives you animation, motion and interactivity.
- A reference. You don't have to do the layout yourself — you have to find a style. For example styles.refero.design: you look at how it actually appears, and every style ships with a ready
design.md— copy it into your folder. Design done.design.mdis by now practically a standard, likeREADME.md: a file describing how everything should look (fonts, colours, shapes, spacing). You can go the other way too: write it by hand or put it together with BMAD. - The build.
/present <folder>— the skill needs exactly two files,slides.mdanddesign.md. It will ask a question or two if it has to, and build the deck. That is the baseline, and a baseline is usually not what you want — but it cost you little time and it is already in your hands. - The revision loop. You look at the deck and fix it with words: what you don't like, what to change where, where to add motion. You can keep polishing forever. Use the current client's review surface, described next.
- Design and review in the current client. Codex uses HTML preview and available artifacts; Claude Code can use Claude Design when its connector is available. The skill routes by actual session capabilities. The offline deck works independently of services.
design.md here is the main file, not decoration: the same material under three different briefs gives three completely different decks.
In the skill these are the Design and Build stages. Codex opens style options and the finished HTML deck in a local preview; additional artifact routes are optional choices. Claude Code retains canvas options and HTML transfer when Claude Design is available. In together mode you choose the style; in do-it-yourself mode the agent chooses one. A ready refero brief, an interview and a URL reference remain shared ways to obtain design.md, followed by the build, available browser checks and revisions.
The deck is ready — and this is where most people stop, while the most valuable part is still ahead.
- A run-through on the recorder. Start the deck, start recording (on the computer itself) and walk your slides out loud, in your own words, as if the room were already seated. Spot a mistake — say it out loud right there, it all gets recorded. You immediately learn two things: how long the talk actually runs and where you flounder — where you started mumbling, the slide is bad, not you.
- Transcription. OpenSuperWhisper locally → raw text with all the filler and every "uhh". Free, and nothing leaves your machine.
- The model as an editor. Back into BMAD: read this, cut what needs cutting, tell me where I'm wrong. And the key trick — give it the time budget: "I have twenty minutes, here are the per-slide timings, squeeze it". It trims exactly what you won't miss. What comes out is your words, just tidied up — not something the model made up on its own.
- Back into
slides.mdand rebuild. Now the deck holds what you actually say — the slides followed the live speech, not the other way round.
That arrow back is the whole reason for splitting into three files: every lap the talk gets shorter and sharper, and nothing has to be rebuilt from scratch.
In the skill this is the "Voice" stage. After the build the skill briefly offers three ways to do the run-through: dictate straight into the chat (Handy, macOS dictation), record it and drop the file into the folder — the skill transcribes it itself, it only needs whisper or a similar tool on the machine (if there is none, the skill tells you what to install) — or transcribe the recording yourself and send the text in the chat or as a file. From there it works on its own: transcribes the recording (if needed), compares the length with the budget, trims the speech in your own words, shows a diff of slides.md and rebuilds the deck. Every lap is logged in DECK.md: date, length, what changed.
At the start of the full path the skill asks how to work. Together — every stage goes through questions. Do it yourself — the skill runs the stage without questions and shows the result: it lays out the material, picks the style and trims the speech on its own. It stops only at your steps and at the end. Switch modes on the fly by saying "carry on yourself" or "let's do it together".
The state of the path lives in the «Конвейер» (pipeline) section of DECK.md: which stages are done, what is waiting on you, the budget and the run-through laps. Closed the session, recorded the run-through a day later — call /present <folder>, and the skill continues from the same spot without asking again.
| Loop | What it changes | How |
|---|---|---|
| Big | what I say — structure, order, design | edit slides.md → rebuild the deck |
| Small | in which words — the phrasing | edit the note right in the presenter window → export notes.js → drop it next to the deck. No editor, no rebuild |
The small loop turns as many times as you run the talk out loud.
| Step | Tool | What for | Required? |
|---|---|---|---|
| Context | BMAD METHOD | party mode and sub-agents for presentations and storytelling: work the idea up, break a transcript into slides, then tighten the text to the time budget | no — the skill runs the "Context" stage itself |
| Context / Voice | OpenSuperWhisper, model large-v3 |
local transcription of your recordings: a whisper.cpp wrapper for macOS — a global dictation hotkey, drag & drop for recordings, models downloaded from inside the app. Fast on an M-chip, punctuation and loanwords included, free and offline | no — the skill transcribes the recording itself if whisper is on the machine; otherwise anything that puts text into an input field works (macOS has built-in dictation too) |
| Design | styles.refero.design | a gallery of clean references, each style shipping a ready design.md — copy it into your folder |
no — the skill builds a brief from questions or from a reference URL |
| All stages | this skill | leads from idea to deck: slides.md → design.md → one offline HTML with a presenter window and PDF export → run-through and trimming |
— |
| Design and edits | Current host preview / chosen service | style options and revisions | hosted services optional; verify capabilities in-session |
- Navigate with
←→, the mouse wheel or a swipe; the position lives in the#hash— F5 doesn't lose your slide. P— the presenter window (the short path has none unless you ask): notes, next slide, timer, and slide switching from there too. Ideally two monitors: one you share, one in front of you. Share the deck to the screen, not this window.- Notes are edited right in that window: double-click the text → fix it → apply. Mumbled during rehearsal — rephrase it on the spot, while the thought is fresh.
B— black screen,F— fullscreen.S— export to PDF: the kernel freezes every slide in its final frame (counters counted up, animations played out), the page is 16:9 with no margins, one slide per page, text stays text. Blurred shadows are deliberately printed flat — Chrome writes them as a raster mask that Preview paints as a grey rectangle over your content — and the deck looks the same as ever on screen. When someone asks you to "send the slides" — you have something to send.?checkin the address bar — highlights slides whose content is taller than the screen.- Slides you can poke at. HTML does things PDF cannot, and the skill uses that sparingly: it goes through the slides, looks for places where the audience would understand more if they switched something themselves, and offers options — the user decides. The engine yields to widgets: a click on a button or a caption doesn't flip the slide, typing in an input doesn't trigger hotkeys, a scrollable area scrolls on its own. One or two such slides per deck is the norm, and each one reads fine even if nobody clicks it.
- Live notes in a
<slug>-notes.jsfile next to the deck: edit them in the presenter window or in an external editor — they are picked up on the fly, no rebuild. A copy is embedded in the HTML as a fallback, so the deck can still be sent as a single file.
The deck runs as a local file, and a browser cannot write to disk from one — so note edits live as a draft in the browser (they survive F5) and reach the disk via the "⤓ notes.js" button: download it, drop it next to the deck over the old one. The file wins over the draft; unsaved edits are not lost — the presenter offers to bring them back.
As a Claude Code plugin. Run in Claude Code:
/plugin marketplace add StasPotapov/sp-tools
/plugin install present@sp-tools
The skill is then called /present:present. To get a new version: /plugin marketplace update sp-tools,
then claude plugin update present@sp-tools (in the shell).
From a clone, with the Codex or Claude Code installer. Keep the complete repository outside the skills directory, then run from it:
python3 -B scripts/present.py doctor
python3 -B scripts/present.py setup --client codex --install-skills
# For Claude Code use claude-code instead of codex.Setup links present and present-setup into the selected client's skills directory. Repeat runs preserve those links; foreign files and links stop writes before any changes. If an environment manager owns delivery, update through that owner. AI Workspace is not a runtime dependency. Do not combine clone and plugin installation in one client.
No models or roles are configured: the current session performs the stages. Setup does not launch an AI CLI, install software or modify the other client's settings. After reload verify both skills are discovered; use $present in Codex or /present in Claude Code (/present:present for the plugin).
Other agents. Keep the whole repository and give the agent the absolute path to SKILL.md with your task. The agent reads HOST.md and follows the shared pipeline using its available tools. If the client has a native skills directory, connect the complete tree using that client's documented procedure. The bundled installer accepts only codex and claude-code; installation commands for other clients are not assumed.
- Codex: the default is design options and the actual HTML deck in a browser panel. Feedback comes through chat with slide numbers. Optional routes use Presentations/Spaces, Pages with HTML and comments, or Sites hosting. Discover tools in the current session; an artifact editor alone does not guarantee saved presentation creation.
- Claude Code: retain the original Claude Design canvas/review workflow when its connector is available. Local files and browser preview remain available without it.
- Other agents: the shared local pipeline uses available file, shell and browser tools. Unverified integrations are reported separately.
- Boundaries: native slides do not automatically carry the HTML kernel, animations or live notes. Page comments do not guarantee slide-element anchors. Ordinary
presentuse does not publish; uploading/hosting requires the person's choice of that route.
See the host contract, design router and Codex route. Browser, image, PDF and connector checks are separate; skipped verification is not a pass. Live Claude and remote connector behavior require a separate check in that host session.
/present <idea | folder | file | recording | deck | reference URL>
The skill works out where to start on its own:
| What you give it | What happens |
|---|---|
| an idea or topic in chat | a question about the path; full — the "Context" stage with an interview |
| text, a transcript, articles, a repository | the "Context" stage: laid out as slides |
| an audio recording of the talk | transcription, then layout |
a folder with slides.md |
the "Design" stage |
a folder with slides.md and design.md |
straight to the build |
a folder with DECK.md |
continues from the step where it stopped |
| a new run-through recording next to the deck | the "Voice" stage |
a finished deck (*.html) |
polishing, or growing it into a talk |
| the folder and "I left comments" | the skill reads the comments on the canvas or the review page, edits the deck and replies in the threads |
The first thing the agent asks about is the path. Short — for when you just need to show an idea in
pictures: no slides.md, no brief, no interview, no plan to approve; exactly one <slug>.html lands on
disk, with no presenter window. At the end the skill offers to add one in a single line. Need it right
away — say so: "with notes". Full — everything described above and below. A short deck is not wasted
if you later grow it into a full talk: hand the finished HTML back to the skill and say what to add —
the deck is its own context (text in the slides, art direction in its own styles).
For the full path, the input that works best is a context folder:
my-talk/
├── slides.md # slide text + speaker notes
├── design.md # design brief (art direction)
└── *.png/jpg # media to embed
The two files are a hard requirement for the build. Without them the skill first runs the "Context" and "Design" stages:
slides.md— what gets said: a breakdown into slides (---,## Slide Nor headings), pairs of "slide point → speaker note".design.md— how it looks: the design brief. An export from styles.refero.design (palette tokens, type scale, components, Do/Don't, a ready:root) is applied precisely.
Every stage ends with a check, and the next one does not start until it passes. If both files already exist, the skill goes straight to the build.
It also works without a folder: raw talk text, a transcript, bullet points, a single topic, a path to a repository (then the numbers on your evidence slides come from a real git log), a reference URL to extract design DNA from.
The skill does not invent content — numbers and facts come from your material or are confirmed with a question.
Short path — one file and nothing else:
wherever you asked/
└── <slug>.html engine, styles, slides and base64 media — all inside
Full path. Your working folder stays yours: material, raw sources and build inputs stay where they are. Everything the deck needs in order to be presented goes into a separate deck/ subfolder — you can zip that one folder and carry it to any laptop without picking files by hand.
talk/
├── slides.md input: slide text
├── design.md input: design brief
├── transcript.md · *.jpg raw material — untouched
├── src/ · build.py build sources (if the deck was built by script)
├── rehearsal-1.m4a · .md run-through recordings and their transcripts
├── DECK.md manifest: pipeline status, slide map, decisions with their "why", how to edit
└── deck/ ← the self-contained presentation folder
├── <slug>-<date>.html the deck itself
├── <slug>-<date>-notes.js live notes (source of truth after the first generation)
└── deck-assets/ only if the media didn't fit into base64
DECK.md exists so that the next session doesn't have to read a monolithic HTML file end to end: it holds the pipeline status, the slide map and the decisions with their rationale. If the deck was built by script, you edit the sources in src/ and rebuild — never the finished HTML.
example/ holds a real deck built by this skill and run through the whole pipeline above — the talk "Context. Design. Voice.", 16 slides. Its inputs (slides.md, design.md), the DECK.md manifest with the pipeline status and the build script with its sources are all there, so you can see both the folder layout and the "script" build mode. The talk itself is in Russian — it is there as a sample of format and layout, not as text to reuse.
example-quick/ shows the short path: one 6-slide page with no presenter window, plus the request that produced it (in Russian too).
git clone https://github.com/StasPotapov/present.git
open present/example/deck/kontekst-dizayn-golos-2026-07-28.html
open present/example-quick/present-korotkiy-put.html| File | What it is |
|---|---|
SKILL.md |
the router: ingest → path and working mode → which stage to start from → gates between stages → your manual steps → status in DECK.md |
stages/context.md |
the "Context" stage: an idea, dictation, material or a recording → slides.md with a running-time estimate |
stages/design.md |
the Design stage: available preview, refero, interview or reference URL → design.md |
stages/canvas.md |
host design/review routing and the local path without connectors |
stages/build.md |
the "Build" stage: art direction → plan → build → check in Chrome and PDF → polish |
stages/rehearse.md |
the "Voice" stage: recorded run-through → transcript → trimming to the budget → rebuild |
stages/quick.md |
the short path: one page in one go, presenter window on request |
stages/transcribe.md |
transcribing recordings for "Context" and "Voice": a transcription skill, whisper-cli or text from you |
assets/kernel.html |
the deck engine (KERNEL v8): navigation, animators, presenter window and its off switch, PDF export, guards for interactive slides. Copied verbatim; all the visual design goes into its <style id="design"> and the slides into #deck |
assets/design-axes.md |
9 axes of design decisions — a list of questions, not a catalogue of answers: composition, margins, typography, colour, background, motion, detail, chrome, interactivity |
assets/art-direction.md |
how to design the visuals around the content; how to apply design.md; where to get briefs |
assets/cookbook.md |
the kernel class contract (.count, .chain, .clist, .pipeline, [data-type]…), the interactivity contract (where your own JS goes and how it coexists with navigation and printing), offline fonts, media, checks. There are deliberately no ready-made components or art-direction samples in there — otherwise every deck comes out a recoloured copy of them |
assets/deck-template.md |
the skeleton of DECK.md |
assets/validate.py |
the validator for a finished deck |
python3 assets/validate.py <deck>.htmlIt checks kernel integrity (the KERNEL v8 marker, base and print styles, chrome, presenter, note editing, PDF export), leftover {{…}}, network references and local links to missing files, JS syntax (node --check on every script block and on notes.js), stray script blocks and the order of the interactive block relative to the kernel, interactivity on an engine older than v6, a click bound by attribute to a non-interactive tag, section sync between notes.js and the slides, and the presence of slides.md / design.md / DECK.md.
A short-path deck is recognised by the validator on its own — a single file with no companion set — and it doesn't ask for the set. A deck with data-presenter="off" needs no notes; such a deck next to a full-path set is an error.
- An agent with instruction, file and shell access, such as Codex or Claude Code; no AI CLI dependency.
- Python 3.9+ (stdlib), Node for JS syntax checks. Without Node that portion is reported as skipped.
- The current host's browser tool and image viewing for visual checks. Claude in Chrome is adapter-specific, not required in Codex.
- Chrome/Chromium for headless PDF;
qlmanageon macOS for Quartz verification, optionally poppler. Missing checks are explicitly reported. - Optional design/artifact connectors,
defuddleor a permitted web tool for references, local transcription or an existing transcript.
Dependencies and service logins are never installed automatically. Network actions are limited to requested references, approved fonts and explicitly chosen hosting/artifacts. The finished HTML deck remains offline.
MIT — take it, change it, ship it, only keep the copyright notice. That covers the skill: SKILL.md, stages/, the assets, the deck engine, the validator, the build script and the example-quick/ sample.
The talk content in example/ is not covered: slide text, speaker notes, deck screenshots and the QR code are the author's personal talk, © 2026 Stas Potapov, all rights reserved. Read it as a sample of format and layout, take the techniques — but don't reuse the text as your own. Details in example/NOTICE.md.
The skill itself is written in English: SKILL.md, the stages and the assets. It talks to you in your language — the one you use when you call it. The deck is written in the same language by default: slide text, speaker notes, slides.md and DECK.md. Need another language — say so, and the skill writes the deck in it or translates an existing one.
The kernel UI — the presenter window, hints — follows the deck's lang attribute: Russian for ru, English for any other language. Talk folders with the old Russian headings (## Конвейер, «На экране») keep working.
This README has a Russian version: README.ru.md.
Use it. But using this skill is not the point: write your own. Once you build something like it yourself and realise you can make anything you want for yourself — that is when you see what these models are actually for.