Writing AI prompts

What do I tell an AI so the deck it writes actually builds?

3 min readView as markdown7 chunks · 1.3k tokens in docspack

Narro is text, so an AI can write a deck directly. What separates a usable result from a broken one is mostly the setup, not the prose of the prompt.

Give the model the dialect first

The single biggest failure mode is a model writing markdown in a syntax Narro does not speak — usually one it half-remembers from Marp or reveal.js. Point it at the reference before asking for slides:

Read https://getnarro.com/docs/markdown-mode.md, then write a deck about …

Better still, paste the dialect contract from Rules for AI agents into your project’s AGENTS.md — a link is read once, a contract in the repository is read every session.

For offline or sandboxed agents, install the docs instead:

npm install --save-dev @getnarro/docs

node_modules/@getnarro/docs/generated/llms-full.txt is every page in one file, catalog.json is every name a deck may use, and components.json is the component API generated from the TypeScript source — none of the three can be out of date with the version installed.

Prefer markdown mode

Ask for a .md deck unless you specifically need React. It is one file, the failure modes are visible, and npx @getnarro/cli build deck.md gives a pass/fail signal the model can act on.

Make the model verify

A deck that “looks right” can still be broken, so close the loop:

Write the deck to deck.md, run npx @getnarro/cli check deck.md after each edit, and npx @getnarro/cli build deck.md at the end. Fix anything either reports.

check validates names — layouts, slots, themes — in about a second, and names the valid options when one is wrong. build is the slower, complete answer. In React mode the equivalent is npm run build. Without these nothing catches a mistyped prop, a layout that does not exist, or a component imported from the wrong package.

Be specific about the deck, not the styling

Narro’s themes handle styling. What a model cannot guess:

  • Audience and level — “staff engineers who have not used Kafka”
  • Length — “8 slides”
  • Arc — “problem, why the obvious fix fails, our approach, results, ask”
  • Content it cannot invent — real numbers, names, the actual results

A prompt that works

Read https://getnarro.com/docs/markdown-mode.md. Write an 8-slide deck at deck.md introducing our migration from REST to gRPC, for backend engineers who have not used gRPC. Arc: what hurt about REST at our scale, why we did not just add caching, what gRPC changed, the migration path, the p99 numbers (340ms → 95ms), what we would do differently. Confident but not salesy. Use layout: section between chapters. Then run npx @getnarro/cli build deck.md and fix any errors.

A prompt that does not

Make a presentation about gRPC.

You get ten slides of generic bullets, in whatever dialect the model guessed.

Two things models get wrong

Which package a component comes from. @getnarro/core exports the presentation runtime and the motion and canvas primitives — exactly AnimatePresence, Canvas, CanvasElement, CanvasShape, ErrorBoundary, ErrorOverlay, MarqueeRow, MasonryBackground, Motion, MotionContainer, MotionList, MotionNumber, MotionPresence, MotionSpotlight, MotionStep, MotionSteps, MotionText, MotionTransform, NebulaBackground, Notes, OverviewGrid, Presentation, PresenterNotes, Slide, SlideContent, TransformSlide, TrustedByMarquee. Everything else, Heading and Text and List and the rest, is in @getnarro/shared-ui. Importing Heading from core is the most common broken deck.

Prop values that sound plausible. SlideContent’s layout is “default” | “centered” | “top” | “bottom” | “fill” | “between”. Slide’s layout is a different set. List’s variant is “disc” | “decimal” | “check” | “arrow” | “none” — not "bullet" or "number". The component reference is generated from the types, so it is the authority.

The MCP server

@getnarro/mcp-server gives an assistant Narro-specific tools — scaffolding, listing and editing slides, exporting — and serves this documentation as MCP resources. Useful for assistants without their own shell access; a coding agent that already has a terminal can just use the CLI.

IntroductionWhat is Narro, and should I be writing markdown or React?
InstallationWhat do I install, and what does the project look like afterwards?
First deckWhat does a working React deck look like, end to end?
Markdown modeHow do I split a slide, style one word, or reveal a line — without leaving the markdown file?
Writing AI promptsWhat do I tell an AI so the deck it writes actually builds?
Rules for AI agentsWhat do I paste into my repo so an agent stops writing decks that build wrong?
React APIWhich component or hook do I import, and what does it take?
CLIWhich command do I run, and what are its flags?
Markdown APIHow do I read, edit, or validate a deck file from my own code instead of by hand?
Component referenceWhat props does this component take, and which package do I import it from?
Verifying a deckHow do I know my deck is actually correct?
AnimationHow do I reveal a list one line at a time, or move between slides with something other than a cut?
NavigationHow does the audience move through the deck, and how do I present it?
Canvas & positioningHow do I put something at an exact position instead of in the flow?
Images & mediaHow do I use an image as a background, tint it, or embed a video?
ArchitectureWhich package owns what, and why is the seam where it is?
Zooming canvasHow do I zoom and pan across one big canvas instead of cutting between slides?
Transform modeHow do I zoom and pan across one big canvas instead of cutting between slides?
Import & exportHow do I get this deck out as PPTX, PDF, or one file I can email?
VideoHow do I turn a story into a video, and keep it right when the words, the product or the source changes?
Recording a web appHow do I put a demo of my product in a deck or on a landing page without shipping a video of it?
Embedding a replayHow do I embed a recorded demo of my app in my React app, my Astro site, or any other page?
TerminalHow do I put a terminal demo in a deck, a README or a video, and find out when the tool it demonstrates stops saying what the demo says?
AI integrationHow do I wire an AI assistant up to Narro so it can write and build decks?
ThemingHow do I change the colours, fonts, and overall look of a deck?
Deck templatesHow do I define one house style with named layouts my slides can reference, like a PowerPoint master?
TroubleshootingSomething is wrong with my deck. What is it, and how do I fix it?
LimitationsWhat can't Narro do, and what do I do instead?