How to write AI character cards, calibrated against what actually charts

In July 2026 we sampled the 30 top-starred SFW character cards on chub.ai — star-rank leaders, genre buckets, plus two cards from the current trending list — and measured everything measurable: first-message length, definition format, field usage, endings, slop phrases. Then we cross-read the community guide canon, from Ali:Chat and Trappu's PLists to pixi and Sukino, against those numbers.

The point of the exercise: most card-writing advice is experience talking, and experience disagrees with itself. The numbers settle a surprising amount of it. This guide is the settled version — what to write in each field, how long, in what format, and which rules are load-bearing versus folklore. The measurements come from our research corpus (Foreverse research, 2026-07); the full discipline, a scorer that enforces it, and six example cards are open source in character-card-skills.

What actually makes a card work?

A working card is a scene already in progress, not a persona document. The top cards open mid-event: a girl crashes into a library doorway, a professor reassigns seats, a ship AI reads a suspicious contract aloud. The character is doing something that proves their personality, and the last line leaves the next move entirely to the user. Cards that open with a wiki paragraph about the character do not chart.

Everything below serves that one shape. The description feeds the model facts it can act on. The greeting sets the scene and the voice. Example dialogues lock the voice against drift. The lorebook, if any, holds what should surface later. And the prose discipline keeps all of it from reading like it fell out of a language model — which is a real ranking force now, because readers have gotten very good at spotting it.

How long should the first message be?

The median across our 30-card sample is 178.5 words. The middle half of the distribution sits between 123 and 219 words; the longest is 529; a 40-word first-person self-intro holds a top-15 star rank. So the honest answer is a band, not a number: 150–350 words for a dialogue card, up to ~550 for an RPG or scenario card that has a world to establish.

The mechanism matters more than the band. SillyTavern's docs state it plainly: the model picks up style and length from the first message more than from anything else. A 700-word greeting trains 700-word replies. Write the opener at the length you want to read every single turn.

Formats are two, and you pick one: novel prose (narration plus quoted dialogue) or asterisk style (*She looks up.*). In the sample, 70% use asterisk actions and 30% pure prose. Rich HTML — status panels, collapsible sections, styled divs — appears in exactly zero of thirty. If you came from Chinese-language card communities, where beautification panels are an art form, this is the single biggest convention gap. RPG cards get one plain-text bracketed status line ([Day 3 · Supplies: low]) and that is the whole allowance.

What goes in the description, and in what format?

Facts, in prose. 67% of the sampled cards write the main definition as plain paragraphs; 13% use key-value attribute lines; 7% mix. Strict bracketed PLists, JSON, and interview-format definitions: zero. W++ shows up only in cards dated 2023, and the community verdict on it is brutal — Sukino calls it "an inferior PList" with "no redeeming qualities," and oaicards traces the real disease to parameter-pile habits, not the syntax itself.

The hybrid that works: labeled sections with prose values. A block per topic — identity, appearance, voice, habits, temperament, history — where each label is followed by full sentences, not semicolon inventories. Personality and history must be prose, because the model needs causal chains ("why did this person get like this") to extrapolate behavior in new scenes. Only enumerable facts — clothing, gear, skills — earn list form.

One rule from oaicards worth tattooing somewhere: the description carries facts; the prose flair goes in the greeting and the examples. Fancy adjectives in the description cost tokens twice — once to send, once in the style they teach.

What's the token budget?

Description + personality + scenario are permanent tokens: they ride along with every message and never scroll out. Target 800–1,500; treat 2,000 as a red line. That's the convergence point of JanitorAI's official tutorials (2,000–2,500 hard caps), the pixi guide (500–1,000 for a single character), and the live data — the sampled top cards' full-card median is 1,085 tokens, and only one card in thirty exceeds 5,000.

"Less is more" used to be about small context windows. The windows grew; the advice survived because the reason changed — it's now about attention. A concise definition keeps the model focused on what matters instead of averaging over forty traits. Greetings and example dialogues are temporary tokens (they get squeezed out as chat grows), so length spent there is much cheaper.

What is the no-user-actions rule?

Never write the user's actions, dialogue, or thoughts. Not in the greeting, not anywhere. JanitorAI's official help calls speaking-for-the-user the most common and most hated problem users report, and the top cards enforce the rule at 25 of 30 — with the five exceptions all being RPG openers doing a passive hand-off ("You open your eyes"), which moves the camera but never the character.

The fix is mechanical once you know it. Three guides teach the same move under different names; pixi calls it subject inversion. "You are surprised to see him here" becomes "The sight of him here doesn't fit." "You pick up the letter" becomes "The letter sits where anyone could pick it up." The character observing the user stays legal — "She clocks the mud on your boots" is her action, not yours. When you proofread, point at the verb in every sentence containing "you" and name its subject.

Two adjacent rules ride along. First, don't write {{char}} should not speak for {{user}} inside the card — common_botmaking_mistakes points out the macro expands to "Osaka should not speak for Anon," which means nothing to the model; that constraint belongs in the system prompt, phrased positively ("Speak and act only for <Name>"). Second, if the card is AnyPOV — and AnyPOV is default politeness now — keep he/she out of every permanent field when referring to the user, and avoid singular they too, because it sticks. Write around the pronoun: "a regular now; gets the corner booth without asking."

How do you end the greeting?

Not with a question, usually. Only 23% of the sampled cards end the first message on a direct question. The mainstream close is a social-pressure action: the character does something the user cannot not respond to — sits down next to you and fumbles their own introduction, moves your placemat one seat down, announces the interrogation has begun. A question hands the user a microphone; a social-pressure action hands them a situation. The second one starts better conversations.

The endings to ban outright: "He waits for your answer." "What will you do?" "The night is still young." These are fishing lines, and they show up on every slop list for a reason — see the 95-phrase lexicon for the full family.

Do you need example dialogues?

For most cards, yes — they are the voice weapon. 70% of the top cards carry them, and 19 of those 21 use <START> as the group delimiter. The pattern that separates light users from heavy users is verbal-tic intensity: a card with a mild voice ships 2–4 short exchanges; cards built around a heavy accent or a silence-heavy register run double digits, including char-only monologue groups with no user turns at all — pure voice-locking.

Two failure modes to avoid. All-Q&A examples train an interview bot that interrogates the user (Moth's guide documents this one). And pasting model-generated examples imports that model's biases into the card permanently — hand-write them, including at least one refusal or cold-shoulder turn, because a character who never says no has no edges.

When does a lorebook earn its place?

When the card has something to reveal on condition, not by default. Only 20% of the sampled top cards embed a lorebook, and 5 of those 6 are RPG or scenario cards with real world-state to manage. The old motive — saving permanent tokens — died with big context windows; what survives is conditional reveal (secrets keyed to names and topics, released a layer at a time) and organization for multi-NPC casts.

If you do build one: trigger keys are proper nouns plus synonym clusters ("money, cost, debt, coin, gold"), entries are self-contained (the key text is not injected with the content, so an entry that starts "She also…" dangles), and every keyed entry needs keys — an entry with no keys and no constant flag simply never fires. Deeper mechanics live in our lorebook triggering guide.

How do you keep the prose from sounding like AI?

Two layers: a phrase layer and a structure layer. The phrase layer is the famous one — "barely above a whisper," "eyes sparkling with mischief," "shivers down her spine" — and we maintain a 95-phrase lexicon with sources and counts in its own reference post. Two findings from building it are worth previewing. Star counts don't filter slop: the top human cards themselves average a few hits ("you feel a mixture of…" appears in four of the thirty). And the em dash, which everyone treats as an AI fingerprint, does not separate human from machine in English roleplay prose at all — we counted.

The structure layer is harder and matters more: uniform sentence lengths, a clever line capping every fact, zero idle details, every paragraph the same shape. Fixing it is mostly deletion. Vary sentence length until some are four words. Keep one detail per card that serves no plot function. Read the card aloud and flatten whichever sentence makes you proudest. Uniform cleverness is the fingerprint no word list catches — our LLM-judge experiment is the long version of why automated detectors (including LLMs) miss exactly this.

The parts people skip: alternates, scenario, creator notes

Alternate greetings are optional in the wild — 40% of cards carry them, mean 1.9 — but the cards that have them market them ("20 Greetings!" in the tagline), because each alternate is a different entry situation, not a reworded copy. Either skip them or ship 2–4 production-grade different scenes.

The scenario field holds only what is permanently true. "{{user}} is on a date with {{char}}" in scenario means the model drifts back to that date weeks after the breakup — temporary situations belong in the first message. One sentence, always true: "Runs the only diner open past midnight on Halsey Street."

Creator notes are a social contract, not ad copy: POV declaration first line, content notes, art attribution (say so if it's AI-generated), a one-line model recommendation, two suggested opening moves for the user, and a version line — cards with version numbers read as maintained, and readers notice. Write it like a person; the author's note is also in character.

If you want to see the whole procedure executed, the character-card-skills repo ships the English-native authoring skill this guide distills, the scorer, and six English cards — three written under these rules (they gate at 94/100), and three older ones kept deliberately unfixed as a contrast group, because the difference between the two batches teaches faster than any checklist. The cards import straight into SillyTavern, or into Foreverse if you'd rather chat on your phone.