What I learned building a slide-deck skill for AI agents

A developer built a skill for AI agents that generates slide decks with unique visual designs per topic, avoiding fixed templates. The skill produces a single self-contained HTML file using reveal.js, and the developer learned key lessons about agent skill design, including the importance of precise descriptions and incremental generation to avoid wasted builds.

I wanted slides that didn't look like everyone else's slides. Most AI deck tools take your text and pour it into one fixed template, so every output has the same fonts and the same layout. I built a skill to do the opposite: design a fresh look per topic. Along the way I hit a few problems that were more interesting than the feature itself, so this is mostly about those. A skill is a directory with a SKILL.md inside. The frontmatter has a name and a description, and the description is what the agent reads to decide whether to load the thing. That's most of the design work right there. If your description is vague, the skill never fires at the right moment. If it's too eager, it fires when nobody asked. The other surprise: the format is close to portable. Claude Code, Codex, OpenCode, and a couple of Google's tools all want the same name/SKILL.md folder. They only disagree on which directory to drop it in. So "support five agents" turned out to mean "write one install table." The first version generated a whole deck in one shot. That was a mistake. If you don't like the visual direction, you've wasted a full build and a lot of tokens, and you're stuck reading ten slides to find the two design choices you hate. So now it generates a theme and exactly two slides, opens them, and stops. You look, you say yes or "try something darker," and only then does it build the rest. Rejecting a direction costs almost nothing. This one change made the whole thing feel usable instead of like a slot machine. The output is a single self-contained HTML file built on reveal.js. No build step, no assets folder, no install. You open it in a browser and it runs, including PDF export and a speaker view. I like artifacts you can email to someone and they just work, with nothing for them to set up. The catch with "one file" is discipline. The theme lives in inline CSS variables, the slides are hand-written HTML, and there's no stock reveal theme loaded, because the stock themes are exactly the generic look I was trying to avoid. reveal.js can highlight code line by line as you click, lighting up a few lines at a time. Under the hood it does this by cloning the whole code block once per step and stacking the clones on top of each other. That detail matters, and I learned it the hard way. When I restyled the code block to match a deck's theme, the steps started ghosting, stair-stepping, and in one case the heading vanished the moment you advanced a slide. Four separate visual bugs, all from the same root: I was styling an element that reveal quietly turns into a pile of absolutely positioned copies. Spend real time on the description field. It's the whole trigger, and most skills that misfire misfire there. Write down the rules you learn the hard way, right in the skill, so the agent can't repeat the same mistake on the next run. A skill that carries its own hard-won constraints beats one that hopes the model remembers. And test it on cases you didn't design for. The skill behaves on the example you built it around. What tells you it's real is whether it holds up on the messy input a stranger throws at it. The skill is on GitHub if you want to poke at it: https://github.com/arifszn/slide-wright-skill . Happy to hear where it falls over.