🤖 Writing AI Prompts

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

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

Slide’s layout is a different set. List’s variant is

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.