Open beta. Rin Chat is under active development. Expect rough edges, and please tell us what breaks.

Skip to content

Creator guide

The AICC card format: a field-by-field guide

AICC (exported as AICC-Chat) is the native character card format of Rin Chat. It is also the format aicharactercards.com publishes cards in. Where a SillyTavern card keeps a character in a few large text fields, an AICC card gives each part of the character its own field: what they look like, who they are, the rules they keep, how they talk, where they come from and where the story is set.

This guide walks through every field in the order an export writes them, explains how each one reaches the model, and makes the case for writing cards this way. It ends with a complete example card, a reference table and a compatibility chart.

Using an AI to write cards? Give it card-format.md, a Markdown copy of this guide with rules for models at the top. Every file for AI models is listed under For AI Agents.

Want to know how a card is scored on aicharactercards.com and in Rin Chat? How cards are graded

What the format is, and who it is for

An AICC card is a JSON document. It saves as .aicc.json, inside a PNG as .aicc.png, or inside a bundle (.aicc or .charx) together with the card's images. Rin Chat opens every card in this shape: when you import a SillyTavern V1, V2 or V3 card, it is converted on load, and it can always be exported back out as a SillyTavern card.

  • Creators writing by hand. Each field answers one question, so you always know where a sentence belongs, and you can rewrite one part of a character without disturbing the rest.
  • People brainstorming with an AI. You can ask for one field at a time (three behavior rules, a new greeting, a tighter appearance) and paste the answer straight in, instead of asking a model to rewrite a whole description.
  • Tool builders. The structure is plain JSON with fixed names and types. A generator, a linter or an editor can read or change one field without parsing prose, and an exported card is valid input for the next tool.

Nothing here locks you in. An AICC card exports to a SillyTavern card by folding its extra fields into SillyTavern's text fields under labels, so the content still reaches any app that reads V2 or V3 cards. The compatibility section shows exactly what goes where.

The shape of a card

This is the full set of fields an export writes, empty, in export order. Optional blocks (generators, regex_scripts, image prefixes, features, assets) are covered below and appear only when a card uses them.

A blank AICC card
{
  "spec": "aicc_card",
  "spec_version": "1.0",
  "id": "<a random UUID>",
  "data": {
    "name": "",
    "general_description": "",
    "appearance": "",
    "personality": {
      "core": "",
      "behavior_rules": [],
      "speech_style": { "tone": "", "verbosity": "", "format": "", "patterns": [] }
    },
    "background_history": "",
    "world_setting_context": "",
    "dialogue": { "greetings": [], "dialogue_examples": [], "group_only_greetings": [] },
    "prompts": {
      "system_prompt": "",
      "post_history_instructions": "",
      "depth_prompt": { "text": "", "depth": 4, "role": "system" }
    },
    "world": { "worldbook_name": "", "worldbook_entries": [] },
    "metadata": {
      "card_format": "AICC-Chat",
      "char_ui_name": "", "creator": "", "notes": "", "version": "", "tags": []
    }
  }
}

You do not have to write every field. On import, any missing field is filled in with its empty default, so the smallest useful card is short:

A minimal valid card
{
  "spec": "aicc_card",
  "spec_version": "1.0",
  "id": "6b1f2d0e-93a4-4c7e-b5d8-2f1a0c9e7d42",
  "data": {
    "name": "Ines Varga",
    "general_description": "{{char}} is a 29-year-old night-ferry pilot in a flooded canal city.",
    "personality": { "core": "Wry, patient and private. Kind in practical ways." },
    "dialogue": { "greetings": ["Rain hissed on the canal. \"Last crossing, passenger.\""] },
    "metadata": { "card_format": "AICC-Chat", "tags": ["fantasy", "adult"] }
  }
}

The one mistake that breaks a card

personality must be an object with a core key, even if core is an empty string. If it is a plain string, or missing, the importer reads the whole card as flat SillyTavern data and the native fields are lost. Also avoid null anywhere: leave a key out instead.

The envelope

The top level of the file says what it is. The character itself lives under data.

specstring, required

What it is
The format tag. Always "aicc_card". This is what tells an importer the file is a native AICC card; anything else is tried as a SillyTavern card.

spec_versionstring

What it is
The version of the structured format. Write "1.0", which is what every export writes.

idstring (UUID), recommended

What it is
This card's identity in one person's library. Use a freshly generated random UUID.
Writing it well
Generate a new one for each new card and keep it when you publish an update of the same card. If it is missing, or matches a card already in the library, Rin Chat issues a new one on import.
Keep out of it
Ids that start with chat_ or wb_; they are reserved and refused.

aicc_idstring (UUID), site-issued only

What it is
The portable card ID that aicharactercards.com issues when a card is published there. It lets ratings and update checks follow the card wherever it travels. Rin Chat reads and carries it and never creates one. A site version marker, aicc_version, can sit beside it.
Keep out of it
Never invent one, and never copy one from another card. A made-up aicc_id claims a published identity the card does not have. Tools should leave both keys out.

Also leave out org, imported_from and source_url. They hold one person's local library details (folders, favorites, private notes, where a card was downloaded from), and exports strip them.

Name, description and appearance

namestring

What it is
The character's name. This is what the model receives as {{char}}.
Writing it well
The plain name the character goes by in the story. Put a tagline or a longer display title in metadata.char_ui_name instead.
Example
Ines Varga
Keep out of it
Taglines, emoji, version numbers and HTML. Whatever is here gets spoken as the character's name.
How it reaches the model
Sent on every turn as the character's name, and substituted wherever {{char}} appears.

general_descriptionstring

What it is
The concept: who the character is, their role and the premise of the card, in a few sentences.
Writing it well
Lead with the one sentence a reader needs to understand the card. Give an adult age explicitly. Name the hook that makes the character worth talking to.
Example
{{char}} is a 29-year-old night-ferry pilot in Lowmarsh, a canal city that floods every spring. She runs the last boat across the Gray Reach after midnight and takes any passenger who pays.
Keep out of it
Physical description (that is appearance), backstory (background_history), and instructions to the model.
How it reaches the model
Sent on every turn, as the Description section of the character block.

appearancestring

What it is
What the character looks like: build, face, hair, notable marks, how they move, what they usually wear.
Writing it well
Concrete, visual details a reader could picture. A few distinctive specifics (a scar, calloused hands) do more than a list of generic adjectives.
Example
Lean and weathered, with olive skin, dark curly hair tied back under a knit cap, and pale gray eyes. A thin scar splits her left eyebrow. Rope calluses on both palms.
Keep out of it
Personality traits and feelings. A model reads 'gentle eyes that hide a cruel streak' as a personality claim buried in a look.
How it reaches the model
Sent on every turn, under its own Appearance label, so the model always knows which text is about looks.

Personality, behavior rules and speech style

personality is an object with three parts. Splitting it is the biggest difference from a SillyTavern card, where all three usually share one paragraph.

personality.corestring

What it is
Inner traits and how the character treats people, including {{user}}.
Writing it well
Write traits as behavior: what the character does, and when. 'Kind in practical ways (a spare coat, a shortcut), but deflects anything personal with a joke' tells the model what to write; 'kind and guarded' only names a mood.
Example
Wry, patient and private. {{char}} is kind in practical ways but deflects anything personal with a joke. Loyal to her regulars, suspicious of the Lantern Wardens. Treats {{user}} as a regular she has not decided about yet.
Keep out of it
Looks, backstory, and rules for the model. Each has its own field.
How it reaches the model
Sent on every turn as the Personality section.

personality.behavior_ruleslist of strings

What it is
Short, firm rules the character always or never follows. Optional and empty by default.
Writing it well
One rule per item, one sentence each, phrased so it can be checked: always, never, only when. Three to six good rules beat fifteen vague ones.
Example
[
  "Never speak, act, decide or feel for {{user}}.",
  "Keep each reply to one scene beat and end on something {{user}} can respond to.",
  "{{char}} never reveals a passenger's business unless that passenger is in danger."
]
Keep out of it
Personality description ('she is shy') and long paragraphs. If it is not a rule, it belongs in core.
How it reaches the model
Sent on every turn as a bulleted Behavior rules list, one line per rule.

personality.speech_styleobject: tone, verbosity, format, patterns

What it is
How the character talks and how replies are written. tone is the voice in a few words. verbosity is one of "low", "medium", "high", or empty. format is the shape of a reply (narration person and tense, how dialogue and actions are marked). patterns is a list of recurring habits: catchphrases, verbal tics, things they always or never say.
Writing it well
Patterns are the most useful part. A concrete habit ('measures distance in bridges') gives the model something to imitate, where an adjective ('quirky') gives it nothing. Keep format consistent with your greetings, because the model copies the greeting's form.
Example
{
  "tone": "dry, low-key, warm underneath",
  "verbosity": "medium",
  "format": "third-person narration in past tense, dialogue in double quotes",
  "patterns": [
    "calls {{user}} 'passenger' until she trusts them",
    "answers personal questions with a question about the weather"
  ]
}
Keep out of it
Long quoted speeches. Show the voice in greetings and example dialogue; describe it here.
How it reaches the model
Sent on every turn as one labeled Speech style line: tone, verbosity, format, then the patterns.

Background and setting

background_historystring

What it is
Backstory: past events, relationships and motivations that explain who the character is now.
Writing it well
Keep what changes how they act today. A loss, a debt, a secret they carry. Cut the timeline that never affects a scene.
Example
Her father ran the ferry before her and drowned in the flood of her nineteenth spring. She took the tiller the next night because the regulars still needed to cross. She owes the Lantern Wardens a favor she would rather not repay.
Keep out of it
World facts that are not about the character. Those go in the setting or the lorebook.
How it reaches the model
Sent on every turn as the Background section.

world_setting_contextstring

What it is
The world, the place and the current situation the chat opens into.
Writing it well
Only what is true in every scene: the kind of world, the place, the tension. Push details that matter only sometimes (a district, a faction, a ship) into lorebook entries.
Example
Lowmarsh is a damp, lamp-lit canal city of bridges and locks. After midnight the bridges close and the only way across the Gray Reach is by ferry.
Keep out of it
A full world bible. Everything here costs tokens on every turn.
How it reaches the model
Sent on every turn as the Setting section.

Greetings and example dialogue

dialogue.greetingslist of strings

What it is
Opening messages. The first is the one a new chat opens with; the rest are alternates you can swipe to before you reply.
Writing it well
Make each greeting a different scenario: a different place, moment or stage of the relationship, not the same scene reworded. Establish the scene through the character, show their voice, and leave a clear opening for the user to answer. Write in the same form you want replies in.
Example
The Heron bumped against the Saint Ondra lock just as the bells struck two. A Warden's whistle shrilled somewhere upstream. Ines killed the lantern with one pinch. "If you're getting on," she murmured, "get on now."
Keep out of it
A Name: label at the start (the model learns to start every reply with its own name), and anything the user does, says or feels.
How it reaches the model
The greeting the chat opens with (or the one swiped to) is the first assistant message in the history. It is not repeated as part of the character block, and as a long chat fills the context it is trimmed with the oldest messages.

dialogue.dialogue_exampleslist of strings

What it is
Sample exchanges that teach the voice and the reply format. One exchange per list item.
Writing it well
Write each as a short {{user}}: line and a {{char}}: reply. Each example should show something the other fields cannot: how the character dodges a question, what they sound like annoyed, how long a reply runs.
Example
{{user}}: Do you ever get scared out here at night?
{{char}}: Ines tilted her head toward the clouds. "Looks like more rain by the third bridge. You'll want a hood."
Keep out of it
Whole scenes in one item, and examples that only repeat what core already says.
How it reaches the model
Sent under an Example dialogue label early in a chat, while the real conversation is still short; after that the chat itself shows the voice. A single string in SillyTavern's <START> form is split into items on import.

dialogue.group_only_greetingslist of strings

What it is
Openings used only when the character starts a group chat. A member with group-only greetings opens the group with one of them, picked at random.
Writing it well
Write them for a scene with several people in it. Ordinary greetings are written for one-on-one openings, so they are not used here.
How it reaches the model
Becomes that member's first message in the group chat.

Card prompts

Most cards leave all three empty. Use them when a card genuinely needs different handling, such as a narrator, a game or a strict reply format.

prompts.system_promptstring

What it is
The card's own system prompt.
Writing it well
When it is set, it replaces the user's own system prompt by default (users can change that preference). Write {{original}} inside it to include the user's system prompt as well.
Keep out of it
Character description. The system prompt is for how to run the chat, not who the character is.
How it reaches the model
Sent on every turn at the top of the character block.

prompts.post_history_instructionsstring

What it is
Instructions placed after the chat history, right before the model writes its reply.
Writing it well
One or two short sentences. This position is read last, so it is strong; a long block here crowds out the scene.
Example
Stay in {{char}}'s point of view. Write only what {{char}} and other characters do and say.
How it reaches the model
Sent on every turn as a system message after the history, followed by the user's own post-history instructions if they have any.

prompts.depth_promptobject: text, depth, role

What it is
A note inserted into the chat history a set number of messages from the end (SillyTavern calls it the Character's Note). depth counts messages back from the newest; role is "system", "user" or "assistant".
Writing it well
Use it for a reminder that should stay close to the action, like a mood or a running condition. Keep it to a sentence or two.
Example
{ "text": "Ines is tired tonight and the river is high.", "depth": 4, "role": "system" }
Keep out of it
SillyTavern's key name. The text goes in text, not prompt.
How it reaches the model
Sent on every turn, inside the history at its depth.

The character's own lorebook

world holds the card's own lorebook: worldbook_name and a list of worldbook_entries. An entry stays out of the prompt until a keyword in the recent chat triggers it, so a card can carry a lot of world detail and pay for it only when it matters. The entry shape is the same one SillyTavern uses for an embedded character book.

One lorebook entry
{
  "id": 0,
  "keys": ["Heron", "ferry", "boat"],
  "secondary_keys": [],
  "comment": "The Heron",
  "content": "The Heron is Ines's flat-bottomed ferry: room for six, a single lantern on a pole.",
  "constant": false,
  "selective": false,
  "insertion_order": 100,
  "enabled": true,
  "position": "after_char",
  "use_regex": false,
  "extensions": {
    "position": 1, "depth": 4, "probability": 100, "useProbability": true,
    "selectiveLogic": 0, "exclude_recursion": false, "prevent_recursion": false,
    "delay_until_recursion": false, "group": "", "role": 0, "match_whole_words": true
  }
}
FieldWhat it does
keysWords that trigger the entry. Any one match is enough. Matching is case-insensitive and, unless match_whole_words is on, by substring.
secondary_keys, selectiveWith selective on, the secondary keys must also match, by the rule in extensions.selectiveLogic (0 AND ANY, 1 NOT ALL, 2 NOT ANY, 3 AND ALL).
commentThe entry's title. Shown in editors; not sent to the model.
contentThe text inserted when the entry fires.
constantAlways on, keys ignored. Use sparingly: a constant entry costs tokens on every turn.
enabledOff means the entry never fires.
insertion_orderOrder within a position; lower goes in first. When lore runs over its budget, higher order is kept.
position, extensions.positionWhere it goes: 0 before the character, 1 after the character, 2 and 3 around the Author's Note when one is active, 4 at a depth in the history. Keep the string form (before_char, after_char) consistent with the number.
extensions.depth, extensions.roleFor position 4: how many messages from the end, and the role (0 system, 1 user, 2 assistant).
extensions.probabilityChance in percent that a triggered entry is used, rolled each turn.
extensions.match_whole_wordsMatch keys as whole words, so 'or' does not trigger on 'order'. Recommended for short keys.
use_regexWhen on, a key written as /pattern/flags is a regular expression.
  • Give every entry an id that is unique within the book; 0 to n-1 is simplest.
  • One topic per entry, a few sentences each. Write it as facts, not as a scene.
  • Pick keys people actually type in chat: the name, a nickname, the everyday word for the thing.

Generators, regex scripts and image prompts

generatorslist of objects, optional

What it is
The card's own randomizers. Typing [Create Night Passenger] rolls one and inserts the result. Each generator has an id, a name, fields (weighted options, or a numeric range) and an optional template with {Field} placeholders.
Writing it well
Give each generator a random UUID id and keep it across versions of the card. Optional keys add behavior: autoFireChance (0 to 1) lets it fire on its own before a reply, modelTriggerable offers it to the model as a tool on providers with tool calling, and chainedIds runs other generators after it.
Example
{
  "id": "0d7c5b3a-1e2f-4a6b-9c8d-7e6f5a4b3c2d",
  "name": "Night Passenger",
  "fields": [
    { "id": "f-who", "name": "Who", "kind": "options",
      "options": [ { "value": "a soaked courier", "weight": 2 },
                   { "value": "an off-duty Warden", "weight": 1 } ] },
    { "id": "f-age", "name": "Age", "kind": "range",
      "range": { "min": 21, "max": 70, "step": 1, "display": "number" } }
  ],
  "template": "Waiting at the dock: {Who}, about {Age}."
}
How it reaches the model
Only the rolled result reaches the model. The roll happens in the app, so the model cannot pick the outcome.

regex_scriptslist of objects, optional

What it is
Find-and-replace scripts in SillyTavern's own script shape (scriptName, findRegex, replaceString, placement, markdownOnly, promptOnly, minDepth, maxDepth and the rest). placement 1 is user messages, 2 is AI messages. markdownOnly changes only what is displayed, promptOnly only what is sent; with neither, the script rewrites the saved message once as it arrives.
Writing it well
Write flags explicitly in /pattern/flags and include g when you mean every match. In JSON every backslash is doubled. Prefer display or prompt scripts over rewriting messages.
Keep out of it
Anything a reader must allow blindly. A card's scripts run only after the user allows them for that card, so say what they do in the creator notes.
How it reaches the model
Prompt-phase scripts change what the model receives; display scripts never reach it.

metadata.image_prompt_prefixstring, optional

What it is
Fixed visual traits added to every image prompt for this character, so two pictures of the same person look like the same person. metadata.image_negative_prefix lists what this character's pictures must never contain.
Writing it well
Only what never changes: an adult age, build, face, hair, eyes, permanent marks. Comma-separated tags join most cleanly with the rest of the prompt.
Example
adult woman, 29 years old, lean build, olive skin, dark curly hair, pale gray eyes, thin scar through left eyebrow
Keep out of it
Clothing, pose, location and lighting. The prefix is added to every picture, so a jacket written here appears in the beach scene too. Leave those to the moment. Macros like {{char}} are not expanded here.
How it reaches the model
Never sent to the chat model. Used by the image generator only.

Metadata, features and assets

Nothing in metadata is sent to the chat model except through features that say so. It describes the card for people and apps.

FieldWhat it holds
card_formatWrite "AICC-Chat". Informational.
char_ui_nameThe display name in lists, search and the chat header. Can be a tagline. Never sent to the model; falls back to name.
creatorWho made the card.
notesPublic creator notes: what the card is, how to use it, which greeting to try. They travel with the card and are not sent to the model.
versionYour version label for the card, such as "1.2".
tagsShort genre and content tags. Cards have no rating field, so tags and notes are where content is signposted.
featuresApp feature flags, described below. Unknown keys are kept, so tools can store their own data under a namespaced key such as "x_yourtool".

Features

  • card_type says what the card is: "character" (the default), "user_persona" (a card that describes you; it appears in the persona picker and its name becomes {{user}}) or "adventure_gm" (a game master card; chats with it start in Adventure Mode). Two more values, "adventure_persona" and "adventure_and_user_persona", mark a persona that carries an Adventure character sheet.
  • Older readers use booleans, so the editor writes them beside card_type: "persona": true for persona types (plus "adventure_persona": true for the sheet-carrying ones) and "adventure_mode": true for a game master. Write the same pair if your tool sets a type.
  • spoiler_mode: true folds the card's sections in editors and asks before showing them, for story cards whose fields give the plot away. It never changes what the model receives.
  • image_note: true tells the model which pictures, backgrounds and expressions the card has.
  • A card with an Adventure character sheet stores it in metadata.persona_sheet (abilities, role, inventory, level, XP, HP and notes for the game master).

Assets

assets holds Character Card V3 asset objects: { "type", "uri", "name", "ext" }, with an optional description. Rin Chat uses icon (the card art), emotion (expression sprites named after a feeling, such as joy), x_gallery (pictures a reply can show; the description says what each one shows), background and x_voice (a voice reference clip).

Images you add in the app live in its own store, so they travel only inside a bundle (.aicc or .charx), which can hold up to 25 MB. A single JSON or PNG file carries text only (and the PNG carries the art). An https:// asset entry is kept in every format, and Rin Chat offers a button to save those images into the card. doc_styles, an optional list of styles for Rin Chat's document blocks, travels the same way as the rest of data. So does chat_style, an optional { css } object of up to 65,536 characters that restyles the card's chat window in Rin Chat; the fonts it uses are assets entries of type x_font, so they travel only inside a bundle.

What the model sees, and what it costs

Rin Chat assembles the card into a character block from labeled sections: the system prompt, lore placed before the character, Name, Description, Appearance, Personality, Behavior rules, Speech style, Background, Setting, example dialogue, then lore placed after the character. An empty field leaves no section behind. Users can change this template, so do not rely on a section's exact position.

Not every field costs the same. Some text is sent on every single turn for the whole chat; some only when it is relevant; some never.

When it is sentFieldsWriting rule
Every turn (permanent)name, general_description, appearance, personality (all three parts), background_history, world_setting_context, system_prompt, post_history_instructions, depth_prompt, constant lorebook entriesOnly what is always true. Every sentence here is paid for on every reply.
Early in a chatdialogue_examplesDemonstrate the voice and format; the chat takes over once it has its own history.
Once, then ages outThe greeting the chat opened withSet the scene and the reply format. It sits in the history like any message.
Only when triggeredKeyed lorebook entries, generator resultsPut situational detail here: places, factions, objects, side characters.
Never sent to the chat modelchar_ui_name, notes, tags, creator, version, image prefixes, alternates nobody swiped toWrite these for people and apps.

In a chat, Rin Chat's session info shows the exact request for every turn with its token breakdown, and the card editor's Tools menu has a prompt preview, so you can check what a card really costs.

Why separate fields help

There are no benchmark numbers on this page. What follows is the mechanism: what the model receives from a structured card, and why that tends to produce steadier roleplay than one large description.

You revise one aspect at a time

When the voice is off, you open speech_style; when the look is wrong, appearance. Nothing else moves. The same holds for tools: an AI edit, a find-and-replace or a linter can change one field and leave the rest of the card exactly as it was, which is impossible when everything shares one paragraph.

It stops the description dump

A single description that mixes looks, traits, history and rules forces the model to work out which sentence is which. Looks bleed into personality ('cold eyes' becomes a cold manner), and rules read as flavor text. With each kind of information under its own label, the model is told what each block is for.

Rules are short and scannable

A rule buried in the fifth sentence of a paragraph is easy for a model to underweight and easy for you to lose when you edit. behavior_rules is a bulleted list of one-line constraints: the model receives them as a list, and you can see at a glance whether a rule is missing or two contradict each other.

Speech patterns teach voice better than adjectives

'Sarcastic and witty' tells a model almost nothing it can imitate. 'Answers personal questions with a question about the weather' is a behavior it can reproduce. patterns asks you for exactly that kind of concrete habit, and format pins down the shape of a reply.

Greetings are scenario entry points

Several greetings, each a different situation, turn one card into several starting scenes. The user picks the opening that suits their mood by swiping before they reply, and the character stays the same.

One exchange per example teaches the format

Each item in dialogue_examples is a single, complete exchange. The model sees clean boundaries between examples, so it learns how long a reply runs and how it is laid out, instead of continuing one long transcript.

The lorebook keeps the world out of permanent tokens

A setting paragraph that describes every district and faction is sent on every turn whether the scene needs it or not. Entries in world are sent only when the chat mentions them. The model's attention goes to the scene at hand, and the card stays affordable on smaller context windows.

Token cost is visible by design

Because fields are separate, it is clear which text is permanent and which is situational (see the table above). You can trim the permanent fields without losing detail, by moving it where it is paid for only when used.

Nothing is locked in

A SillyTavern export folds the extra fields back into SillyTavern's own, under labels, so every word still reaches the model in any app that reads V2 or V3 cards.

Writing best practices

Second person or third person

Write the card fields about the character in the third person: '{{char}} is', 'she'. For greetings and replies, third-person narration from the character's side is the reliable default, and first person suits an intimate or unreliable voice. Second-person narration ('you see', 'you feel') puts the user's experience in the narrator's hands and invites the model to keep narrating it. Use it only when that is what you want. The character speaking to the user as 'you' inside dialogue is always fine.

Use the macros

{{char}} becomes the character's name and {{user}} the user's (their persona name). Always write {{user}}, never a fixed name for the user. {{char}} keeps the card right if the character is renamed; writing the name itself is fine too. Macros work in every text field the model receives, but not in the image prefixes, which are used exactly as written.

Do not write for the user

The user decides what they do, say, think and feel. The test is grammatical: is the user the subject of the sentence, acting or reacting? Then it is theirs to write. The character acting toward the user, setting the scene around them, or saying what is in front of them is fine. A greeting that writes the user's reaction teaches the model to keep doing it in every reply.

Writes for the user

You step onto the ferry and hand over two coins. Your heart races as Ines smiles at you, and you decide to trust her.

Leaves the user free

Ines held out a gloved hand, palm up. "Two coins, passenger." Behind her the lantern swung, and somewhere upstream a Warden's whistle shrilled.

Keep greetings scenario-specific

Each greeting should drop the user into a particular moment: a place, a time, something happening. 'Hi, I'm Ines, what do you want to do?' gives the model nothing to build on. Vary the scenario across greetings, not only the wording.

Stable look in the image prefix, the rest at runtime

image_prompt_prefix is added to every picture of the character, so it should hold only what is always true of their body. Clothing, pose, place and lighting change from scene to scene; leave them to the picture being made. Clothing can still live in appearance for the text model.

Adult characters

State an adult age in general_description and in image_prompt_prefix ('adult woman, 29 years old'), and keep childlike descriptors out of appearance and image tags. image_negative_prefix can list terms such as 'child, teen' to steer pictures away from them. Rin Chat does not check a character's age for you, so this is the author's responsibility, and publishing sites apply their own rules.

Checklist

  • spec is "aicc_card", spec_version is "1.0", and id is a fresh random UUID. No aicc_id unless the site issued it.
  • personality is an object with a core string. No null anywhere.
  • name is the plain name; any tagline is in char_ui_name.
  • Looks are in appearance, traits in core, rules in behavior_rules, voice in speech_style, history in background_history, the world in world_setting_context.
  • Each behavior rule is one checkable sentence.
  • speech_style.patterns lists concrete habits, not adjectives.
  • Every greeting is a distinct scenario, has no Name: label, and never writes the user's actions, words or feelings.
  • Each example dialogue item is one {{user}}: and {{char}}: exchange.
  • Situational world detail is in lorebook entries with real keywords and unique ids.
  • The image prefix holds only stable traits, including an adult age.
  • Creator notes say what the card is, what any regex scripts do, and which greeting to try.
  • Imported into Rin Chat, the card passes the editor's health check, and an export matches what you wrote.

A complete example card

An original character, written for this guide, using every major field. It is valid as written: save it as ines-varga.aicc.json and import it into Rin Chat.

ines-varga.aicc.json
{
  "spec": "aicc_card",
  "spec_version": "1.0",
  "id": "6b1f2d0e-93a4-4c7e-b5d8-2f1a0c9e7d42",
  "data": {
    "name": "Ines Varga",
    "general_description": "{{char}} is a 29-year-old night-ferry pilot in Lowmarsh, a canal city that floods every spring. She runs the last boat across the Gray Reach after midnight and takes any passenger who pays, no questions asked, which is how she ends up knowing more of the city's secrets than she wants to.",
    "appearance": "Lean and weathered, with olive skin, dark curly hair tied back under a knit cap, and pale gray eyes. A thin scar splits her left eyebrow. Rope calluses on both palms. Moves with the easy balance of someone who spends more time on water than on land.",
    "personality": {
      "core": "Wry, patient and private. {{char}} is kind in practical ways (a spare coat, a shortcut, a warning) but deflects anything personal with a joke. She is loyal to her regulars, suspicious of the Lantern Wardens, and quietly proud of never having lost a passenger. Treats {{user}} as a regular she has not decided about yet.",
      "behavior_rules": [
        "Never speak, act, decide or feel for {{user}}; describe only {{char}}, the river and other characters.",
        "Keep each reply to one scene beat and end on something {{user}} can respond to.",
        "{{char}} never reveals a passenger's business to anyone, including {{user}}, unless that passenger is in danger."
      ],
      "speech_style": {
        "tone": "dry, low-key, warm underneath",
        "verbosity": "medium",
        "format": "third-person narration in past tense, dialogue in double quotes, actions in plain prose",
        "patterns": [
          "calls {{user}} 'passenger' until she trusts them",
          "answers personal questions with a question about the weather",
          "measures distance in bridges ('three bridges down')"
        ]
      }
    },
    "background_history": "Her father ran the ferry before her and drowned in the flood of her nineteenth spring. She took the tiller the next night because the regulars still needed to cross. She owes the Lantern Wardens a favor she would rather not repay, and keeps her father's brass compass in her coat.",
    "world_setting_context": "Lowmarsh is a damp, lamp-lit canal city of bridges and locks. After midnight the bridges close and the only way across the Gray Reach is by ferry. The Lantern Wardens police the canals and tax every crossing.",
    "dialogue": {
      "greetings": [
        "Rain hissed on the canal. Ines leaned on the tiller of the Heron, lantern swinging, and watched the empty dock. \"Last crossing, passenger. Two coins, and I don't ask where you're going.\" She held out a gloved hand, palm up, and waited.",
        "The Heron bumped against the Saint Ondra lock just as the bells struck two. A Warden's whistle shrilled somewhere upstream. Ines killed the lantern with one pinch. \"If you're getting on,\" she murmured, \"get on now.\"",
        "Fog lay so thick on the Reach that the far bank was only a rumor. Ines sat on the dock steps mending a net, her boat tied below. She glanced up at the sound of footsteps. \"Nobody crosses in this. Unless you're paying double.\""
      ],
      "dialogue_examples": [
        "{{user}}: Do you ever get scared out here at night?\n{{char}}: Ines tilted her head toward the clouds. \"Looks like more rain by the third bridge. You'll want a hood.\"",
        "{{user}}: Who was the man you dropped off before me?\n{{char}}: She didn't look up from the rope. \"A passenger. Same as you.\" A pause, then the ghost of a smile. \"You'd want the same courtesy.\""
      ],
      "group_only_greetings": [
        "The Heron sat low in the water, already carrying more people than Ines liked. She counted heads twice. \"Everyone sit, nobody stands, and nobody touches the lantern.\""
      ]
    },
    "prompts": {
      "system_prompt": "",
      "post_history_instructions": "Stay in {{char}}'s point of view. Write only what {{char}} and other characters do and say.",
      "depth_prompt": {
        "text": "Ines is tired tonight and the river is high. She is more careful than usual.",
        "depth": 4,
        "role": "system"
      }
    },
    "world": {
      "worldbook_name": "Lowmarsh",
      "worldbook_entries": [
        {
          "id": 0,
          "keys": [
            "Heron",
            "ferry",
            "boat"
          ],
          "secondary_keys": [],
          "comment": "The Heron",
          "content": "The Heron is Ines's flat-bottomed ferry: room for six, a single lantern on a pole, and a tiller her father carved. It leaks at the stern in heavy rain.",
          "constant": false,
          "selective": false,
          "insertion_order": 100,
          "enabled": true,
          "position": "after_char",
          "use_regex": false,
          "extensions": {
            "position": 1,
            "depth": 4,
            "probability": 100,
            "useProbability": true,
            "selectiveLogic": 0,
            "exclude_recursion": false,
            "prevent_recursion": false,
            "delay_until_recursion": false,
            "group": "",
            "role": 0,
            "match_whole_words": true
          }
        },
        {
          "id": 1,
          "keys": [
            "Warden",
            "Wardens",
            "Lantern Wardens"
          ],
          "secondary_keys": [],
          "comment": "Lantern Wardens",
          "content": "The Lantern Wardens are Lowmarsh's canal police, recognizable by their green lamps. They tax every night crossing and look the other way for a price.",
          "constant": false,
          "selective": false,
          "insertion_order": 90,
          "enabled": true,
          "position": "after_char",
          "use_regex": false,
          "extensions": {
            "position": 1,
            "depth": 4,
            "probability": 100,
            "useProbability": true,
            "selectiveLogic": 0,
            "exclude_recursion": false,
            "prevent_recursion": false,
            "delay_until_recursion": false,
            "group": "",
            "role": 0,
            "match_whole_words": true
          }
        }
      ]
    },
    "metadata": {
      "card_format": "AICC-Chat",
      "char_ui_name": "Ines Varga, Night Ferry",
      "creator": "Rin Chat",
      "notes": "A slow-burn mystery on a canal city's last ferry. Try the second greeting for an action opening.",
      "version": "1.0",
      "tags": [
        "fantasy",
        "mystery",
        "slow burn",
        "adult"
      ],
      "image_prompt_prefix": "adult woman, 29 years old, lean build, olive skin, dark curly hair, pale gray eyes, thin scar through left eyebrow",
      "image_negative_prefix": "child, teen, extra fingers",
      "features": {
        "card_type": "character"
      }
    },
    "generators": [
      {
        "id": "0d7c5b3a-1e2f-4a6b-9c8d-7e6f5a4b3c2d",
        "name": "Night Passenger",
        "description": "Rolls a stranger waiting at the dock.",
        "fields": [
          {
            "id": "f-who",
            "name": "Who",
            "kind": "options",
            "options": [
              {
                "value": "a soaked courier",
                "weight": 2
              },
              {
                "value": "a nervous clerk",
                "weight": 2
              },
              {
                "value": "an off-duty Warden",
                "weight": 1
              }
            ]
          },
          {
            "id": "f-age",
            "name": "Age",
            "kind": "range",
            "range": {
              "min": 21,
              "max": 70,
              "step": 1,
              "display": "number"
            }
          }
        ],
        "template": "Waiting at the dock: {Who}, about {Age}."
      }
    ],
    "regex_scripts": [
      {
        "id": "3c9e1a7b-5d2f-4e8a-b6c4-1f0e9d8c7b6a",
        "scriptName": "Ferry log: show in italics",
        "findRegex": "/\\[log\\]([\\s\\S]*?)\\[\\/log\\]/g",
        "replaceString": "<em>$1</em>",
        "trimStrings": [],
        "placement": [
          2
        ],
        "disabled": false,
        "markdownOnly": true,
        "promptOnly": false,
        "runOnEdit": true,
        "substituteRegex": 0,
        "minDepth": null,
        "maxDepth": null
      }
    ]
  }
}

Field reference

Paths are relative to data unless they start with the envelope. Missing fields are filled with their empty default on import. A field marked required breaks the card if it is absent or the wrong type.

FieldTypeRequiredPurpose
specstringRequiredFormat tag, "aicc_card".
spec_versionstringRecommended"1.0".
idUUID stringRecommendedLibrary identity of this card.
aicc_idUUID stringSite onlyPortable ID issued by aicharactercards.com. Never invent.
dataobjectRequiredThe character.
namestringRecommendedThe name the model uses as {{char}}.
general_descriptionstringOptionalConcept and role.
appearancestringOptionalPhysical description.
personalityobjectRequiredMust be an object with core.
personality.corestringRequiredInner traits and how they treat people.
personality.behavior_rulesstring listOptionalOne-line always or never rules.
personality.speech_styleobjectOptionaltone, verbosity, format, patterns.
background_historystringOptionalBackstory that shapes the present.
world_setting_contextstringOptionalWorld and current situation.
dialogue.greetingsstring listRecommendedOpening message, then alternates.
dialogue.dialogue_examplesstring listOptionalOne example exchange per item.
dialogue.group_only_greetingsstring listOptionalOpenings for group chats.
prompts.system_promptstringOptionalCard system prompt; replaces the user's by default.
prompts.post_history_instructionsstringOptionalInstructions after the history.
prompts.depth_promptobjectOptionaltext, depth, role: a note inside the history.
world.worldbook_namestringOptionalThe card lorebook's name.
world.worldbook_entriesentry listOptionalKeyword-triggered lore.
metadata.card_formatstringRecommended"AICC-Chat".
metadata.char_ui_namestringOptionalDisplay name, never sent to the model.
metadata.creatorstringOptionalAuthor.
metadata.notesstringOptionalPublic creator notes.
metadata.versionstringOptionalCard version label.
metadata.tagsstring listOptionalGenre and content tags.
metadata.image_prompt_prefixstringOptionalStable visual traits for every picture.
metadata.image_negative_prefixstringOptionalWhat pictures must never contain.
metadata.featuresobjectOptionalCard type and feature flags.
metadata.persona_sheetobjectOptionalAdventure character sheet.
assetsasset listOptionalCard art, expressions, pictures, backgrounds, voice, chat style fonts.
generatorsgenerator listOptionalThe card's own [Create ...] randomizers.
regex_scriptsscript listOptionalFind-and-replace scripts, SillyTavern shape.
doc_stylesstyle listOptionalStyles for document blocks.
chat_styleobjectOptional{ css }: CSS that restyles the card's chat window.

Compatibility and export

DataNative JSONNative PNG.aicc bundle.charxSillyTavern export
Structured text fieldsYesYesYesYesFolded (see below)
char_ui_nameYesYesYesYesDropped
Greetings, examples, promptsYesYesYesYesYes
Depth promptYesYesYesYesAs extensions.depth_prompt
Lorebook (world)YesYesYesYesAs character_book
generatorsYesYesYesYesDropped
Image prefixesYesYesYesYesDropped
regex_scriptsYesYesYesYesAs extensions.regex_scripts
features, persona_sheet, doc_styles, chat_styleYesYesYesYesUnder extensions.aicc
aicc_idYesYesYesYesAs extensions.aicc.id
Card artNoYesYesYesPNG export only
Expressions, pictures, backgrounds, voice clipNoNoYesYesNo
  • Native JSON and PNG carry the whole card. The PNG holds the same JSON inside the image. A native PNG is not a SillyTavern card; for SillyTavern, use the SillyTavern export.
  • Bundles (.aicc) hold the native card plus its images and voice clip, and can include shared lorebooks the card uses.
  • .charx is a one-card bundle that also carries a Character Card V3 copy (card.json), which other apps that read CharX use. Rin Chat reads the native copy.
  • Chats, variables, private notes, folders, favorites and your settings are never part of a card export.

How the SillyTavern export folds fields

The export writes a Character Card V3 file that SillyTavern and other V2 and V3 tools read. The fields SillyTavern has no place for are merged into its text fields under a label:

AICC fieldSillyTavern field
general_description + appearancedescription, with an Appearance: section
personality.core + behavior_rules + speech_stylepersonality, with Behavior rules: and Speech style: sections
world_setting_context + background_historyscenario, with a Background: section
greetingsfirst_mes (the first) and alternate_greetings (the rest)
dialogue_examplesmes_example, each item starting with <START>
metadata.notes, creator, version, tagscreator_notes, creator, character_version, tags
The example card's personality after a SillyTavern export (shortened)
"personality": "Wry, patient and private. {{char}} is kind in practical ways ...

Behavior rules:
- Never speak, act, decide or feel for {{user}}; describe only {{char}}, the river and other characters.
- Keep each reply to one scene beat and end on something {{user}} can respond to.

Speech style:
Tone: dry, low-key, warm underneath. Verbosity: medium. Format: third-person narration ...
Patterns: calls {{user}} 'passenger' until she trusts them, ..."

Folding is one-way: importing that file back gives a card with the merged text in the flat fields, and the separate fields start empty. Rin Chat's AI Restructure can split the text back out, and the fields you never folded (generators, the display name, image prefixes) are best kept by exporting in the native format alongside the SillyTavern copy.

Want to know how a card is scored on aicharactercards.com and in Rin Chat? How cards are graded