# Writing AI Prompts

> How to brief an AI assistant so the deck it produces actually builds

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](/docs/agent-rules) 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:

```bash
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
<!-- generated:components:core -->`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`<!-- /generated:components:core -->.
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
<!-- generated:type:SlideContent.layout -->"default" | "centered" | "top" | "bottom" | "fill" | "between"<!-- /generated:type:SlideContent.layout -->.
`Slide`'s `layout` is a different set. `List`'s `variant` is
<!-- generated:type:List.variant -->"disc" | "decimal" | "check" | "arrow" | "none"<!-- /generated:type:List.variant --> —
not `"bullet"` or `"number"`. The [component reference](/docs/components) is
generated from the types, so it is the authority.

## The MCP server

[`@getnarro/mcp-server`](/docs/ai-integration) 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.