Rich Text Responses

When the rich responses toggle in the prompt toolbar is on, Braide tells the agent it may answer with a self-contained HTML document inside a fenced code block tagged braide. The session view renders that block as an inline iframe — a small interactive surface (interactive comparison, multi-question form, custom editor, decision tree) instead of plain prose. Buttons inside the artifact can prefill or auto-submit the next prompt for you, so the agent can offer a structured set of follow-up actions rather than asking you to type them.

The feature is opt-in per project and disabled by default. Toggling it does not change the agent or the conversation history — it only prepends a marker to the next prompt that asks the agent to consider replying with a braide block.

Turning It On

The toggle lives in the prompt toolbar to the left of the send button, next to the action buttons and other config controls. It carries an </> glyph and a tooltip that flips between "Rich responses: on" and "Rich responses: off".

  • Off (default) — the agent replies as normal prose / markdown.
  • On — every prompt you send carries a hidden marker block that signals the agent should consider a braide HTML response when the question benefits from spatial layout, multi-choice input, or interactivity.

The toggle state is stored per project in project preferences, so each project remembers your choice independently. Switching projects, restarting the app, and reopening sessions all preserve the setting.

The toggle is disabled while the agent is sending — changes take effect on the next prompt you submit, not retroactively.

What You See in the Session

When the agent decides to answer with a rich response, the message stream renders the artifact inline as an iframe instead of showing the raw HTML source. The artifact:

  • Tracks the host theme — the iframe receives the same --color-bg, --color-text, --color-accent, --font-body, etc. custom properties as the rest of the app, and switches instantly when you flip light/dark mode. Well-authored artifacts pick up the change without needing to re-render.
  • Auto-resizes vertically to fit its content, so there is no inner vertical scrollbar competing with the session-history scroll. Wide content overflows horizontally with a local scrollbar inside the artifact.
  • Sits in a sandboxed iframe with allow-scripts allow-popups, opaque origin. Clipboard write is delegated (so a copy-to-clipboard button works on a user gesture), but clipboard read, network requests to arbitrary URLs, and storage are denied by design — agent-generated HTML cannot read your clipboard, your other tabs, or persistent state.
  • Has a side toolbar with Copy HTML source (copies the raw braide document to the clipboard) and Enter fullscreen / Exit fullscreen (pops the artifact out to a full-viewport overlay; press Escape to collapse).

Buttons That Drive the Next Prompt

Rich responses are most useful when they ask you to make a decision. The agent's HTML can render buttons, forms, sliders, multi-step wizards — any familiar UI control — and use postMessage to push a composed prompt back into the chat input:

  • Auto-submit buttons send the composed prompt immediately, queueing it if the agent is still running. Used when the label makes intent unambiguous ("Proceed", "Apply patch").
  • Prefill buttons drop the composed prompt into the input for you to edit or extend before sending. Used when the user is expected to add detail.

The composed text is always human-readable (bullets, key: value, full sentences) — never opaque JSON or IDs — so you can review and amend it before it is sent. If the artifact requires you to add a final note, the prefill flow keeps you in control.

Saving a Standalone Copy

The Copy HTML source button copies the artifact's source as a self-contained HTML document with the active theme tokens baked in. Paste it into a .html file and open it in a browser to view the artifact standalone — var(--color-bg) etc. still resolve because the palette travels with the file.

The Rich Text Responses Skill

Agents need to know how to compose well-formed braide artifacts: which CSS tokens to reference, where libraries can be loaded from, how to wire the postMessage channel, how to escape user-supplied text inside <script> blocks, how to lay out for an unknown column width, and so on. These rules live in a Claude agent skill called rich-text-responses.

Installing the skill is the recommended way to give an agent the authoring playbook. Without it, an agent can still emit braide blocks (the toggle is independent of the skill), but the output is more likely to break the iframe's sandbox or theming because the agent is guessing at the contract.

Download

<a href="/api/skill-archive/rich-text-responses" download="rich-text-responses.zip">Download rich-text-responses.zip</a>

The archive is generated on demand from the canonical source under apps/docs/content/skills/rich-text-responses/, so each download reflects the version of the skill currently shipped with the docs. It contains:

rich-text-responses/
  SKILL.md
  references/
    code-review.md
    custom-editing.md
    decks.md
    design.md
    exploration-planning.md
    illustrations-diagrams.md
    prototyping.md
    reports.md
    research-learning.md

SKILL.md is the router and mechanics reference (theme tokens, layout, CDN allowlist, postMessage protocol, escape contexts, templates). The references/ directory contains one file per artifact category — the agent reads only the file that matches the task at hand.

Installation

Global (all projects)

A global skill is available to every Claude agent on the machine. Install it under your home directory:

mkdir -p ~/.claude/skills
unzip -d ~/.claude/skills rich-text-responses.zip

Confirm the layout:

~/.claude/skills/rich-text-responses/SKILL.md
~/.claude/skills/rich-text-responses/references/...

If your agent uses the ~/.agents/skills/ convention instead of ~/.claude/skills/, unzip there:

mkdir -p ~/.agents/skills
unzip -d ~/.agents/skills rich-text-responses.zip

Project-local

A project-local skill ships with the repository and is available only to agents started in that project. Install it under the project's .claude/skills/ directory:

mkdir -p .claude/skills
unzip -d .claude/skills rich-text-responses.zip

Commit the unpacked files so collaborators and CI agents pick up the same skill:

git add .claude/skills/rich-text-responses
git commit -m "chore: add rich-text-responses skill"

Verifying

The agent must discover the skill at startup. Restart the session (or re-prompt with the toggle on) and ask the agent something that warrants a rich response — for example, "give me three deployment options to compare side-by-side". A well-prepared agent should reply with a braide block. If you only see prose, check that:

  • The toggle in the prompt toolbar is on (</> glyph filled in accent colour).
  • The skill is in one of the agent's known skill directories. Different agents look in different places — check the agent's documentation for the exact path.
  • The agent's permissions allow it to read skill files at session start.

When to Use It

Rich responses pay for themselves when the answer benefits from layout, comparison, or interactive input. They do not improve answers that are fundamentally prose — a short fact or a single bullet list is better in plain markdown, and a rich-text artifact for that would just be heavier without adding value.

Good fits:

  • Decisions among options — A/B/C cards, each with its own submit button that names the choice.
  • Multi-question forms — several sub-questions feeding one downstream action, rendered as a single form with one submit.
  • Code review — diffs with annotations, module maps, PR explainers.
  • Design surfaces — token palettes, type scales, component variants.
  • Prototypes — small motion or interaction flows you can poke at.
  • Diagrams and reports — system overviews, dashboards, status panels.
  • Custom editors — tweakable configs, sliders, boards — the agent's HTML composes the resulting prompt when you click submit.

Poor fits:

  • Single-fact answers ("the function is at src/foo.ts:42").
  • A bulleted list that would read the same as markdown.
  • Acknowledgements and short prose.

Agents using the skill are expected to pick the lighter medium when it fits. If you find yourself getting rich responses for trivial questions, turn the toggle off for the next prompt — the marker is per-turn, not sticky beyond the toggle state itself.

Related