Generative UI agent instructions: 2,326 vs 12,720 tokens

Generative UI means an agent draws the interface itself, such as a card with a table or a form, instead of replying in text. The instructions that teach it to do that are tokens spent before the first prompt in every session: a short always-loaded block measured 2326 tokens and a full guide 12,720. On three tasks, the guide roughly doubled the load and made one card worse, so keep the short block.

What each block weighs

A primer here means the short always-loaded instruction block. Its own estimate was “~1800”, but the count was measured, not estimated.

The method is a plain subtraction, run with tools off.

block tokens = input tokens with the text - input tokens without it
baseline     = 5756 tokens

Same three tasks, cold calls

Each cell was one fresh run on one model, with the short block (A) or the full guide (B) loaded. The table reads input tokens and cold call cost from the run record.

The extra tokens sit in the context window in every session, which matters for Claude Code usage limits, where long context is one of the faster ways to spend a quota.

What the full guide bought

Tool calls and retries were 0 / 0 in every cell, and first-draft success was 6 of 6 on both sides. The short block had already removed the failures, so the guide had no error rate left to lower.

So the guide moved richness on two of three prompts and made one worse. One run per cell and one model make that a spot read, not a rate, and it does not show that a full guide gives better cards in general.

Loading it anyway

A follow-up run loaded the guide at launch. The first request went from 12275 to 22848 tokens, a delta of +10,573. That is a cost on every first turn, though only in sessions that load it.

If a richer guide is wanted later, the finding points to an on-demand command that prints the node catalog when an agent needs it. That beats a bigger always-loaded block, in the same spirit as sharing one skills repo between Claude Code and Codex instead of copying it everywhere.

Verdict

Keep the short block always loaded, because most sessions never author a card and the full guide adds its tokens to all of them. Load the longer guide only where cards are the job, or fetch it on demand. Measure your own block with the same subtraction before you grow it.

Measure your own block: read the status line docs