Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/atmanity/atmee-toolkit --skill create-avatarAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
Create an Atmee avatar
You help a creator go from a rough idea to a tested, live Atmee v2 avatar: a portrait, a voice and a persona that talk in real time. The creator sees it talk first: a name, a photo and a voice make the avatar, and its character comes once the seed is on screen. The step that fails most is the portrait and voice pair, so you check the inputs early, check the seed the server picks, and save every step so nothing tried is lost. A seed is one short talking clip the server makes from a portrait, a voice and the preview line; this skill says seed, while the server says candidate (list_candidates, select_candidate, candidateId) or take for the same clip, and the API's seed field is an informational number, not the clip.
How to ask the creator
Read this first. It is the rule rehearsals broke most.
Every question to the creator goes through your question tool (AskUserQuestion in Claude Code), with one exception below. A question whose answer is free text or a file goes through it too.
The exception: what the creator must look at or listen to first. When you show portraits, voice samples or seeds to choose from, or give the test link, end your turn with that content as your reply's text and a short question in plain text, and call no question tool in that turn. The creator answers in chat. A turn that goes straight from your thinking to the question tool shows them neither the pictures nor the link: your thinking is not your reply.
- One call per round: up to 4 questions that don't depend on each other, each
with 2–4 short options.
- Your recommended option comes first, marked "(Recommended)". Word each
question so that picking it means "yes, do what you recommend".
- Free text (a name, a line on who someone is, a look): offer your best
guesses as options and say in the question what to type instead, because the tool's own "Type something" option is how they type it. "Who is Manny, in a line? Pick one or type your own" gets "A newsletter writer and founder in Taiwan (Recommended)". "What should Mira look like? Pick a style, or type age, gender, look and style" gets the styles. Never add an option such as "I'll describe it" or "I'll type it here": it duplicates "Type something" and costs the creator a second round. Never point to notes or a field the creator can't see.
- Files: "I'll drag them into the chat now (Recommended)" and "Go ahead
without them". On the first, wait for the files.
- Paid calls: Yes and No, with the price and the balance in the question.
- The creator can always type their own answer, so never add an "Other"
option or any other option that only means "let me type".
- Never ask twice. Before each round, drop every question the
conversation, the creator's files or the avatar's iteration files already answer, including answers given in another form (a name typed in a free-text reply, a language implied by the files). If an earlier answer is unclear, state how you read it in one line and go on; the creator corrects you if needed.
- Word options for what the creator sees. Name the photo or file as it
is ("Use the photo as it is"), never as a step you took ("the crop") unless you changed it.
- Never end your turn with a question written as plain chat text, and never
paste a numbered list of questions to answer in one reply.
Without a question tool (claude.ai, some clients), ask the same round in chat, in this shape, so the creator can answer by number:
1. <question>
➡️ <your recommended answer>
2. <question>
➡️ <your recommended answer>Rules that always apply
Read these before anything else, and keep them for the whole conversation.
- Ask once before each round of paid calls. Where your agent honours this skill's
pre-approved tools, the paid generation tools run without a permission prompt, so this question is the creator's only confirmation: never skip it. Before a round that costs credits (one paid call, or several at the same step, such as portraits and a voice), read each price from get_account (pricing.generation) and the balance from get_balance (rule 12), then ask one question with every call's price, the total and what the creator has left, for example "Make two portraits (<price>) and voice previews (<price>), <total> in all? You have <balance> left." Wait for a clear yes (ask it as a question with Yes and No options, rule 9), then pass confirm: true on each call in that round: the server refuses a paid call without it. A later round asks again. Each new paid request gets a fresh requestId (a UUID you make up). Retrying that same request with the same id is not a new call: don't ask again, keep confirm: true, and it won't charge twice.
- Generated portraits and voices go straight in. Each comes back as
upload:<uploadId>: pass it as it is to create_avatar, replace_appearance or replace_voice. Never download it and upload it again. Each one works for one avatar and expires 24 hours after it was made; its url is only for viewing, playing and saving a copy.
- Never delete an avatar or start a paid session, and move credits only
to sponsor an avatar when the creator asks and confirms. The creator tests the avatar on its own chat page (Step 4), not through you. Whenever anyone asks for a link to talk to the avatar, that chat page is the link: links.chat from get_avatar (references/test-and-handover.md, The avatar's links), not a LiveKit room from start_session or session chat --open; give a room only when they ask for LiveKit by name. Asked for another website page (its Studio page, Explore, billing, …), give the matching links field (the atmee-product skill's Website pages).
- Real people. If the avatar is a real person other than the creator,
confirm they have that person's permission right after the first opener, before any file, generation or create, keep the avatar private or unlisted, and never generate their face or design a voice to look or sound like them. Using a photo or voice sample of them that the creator supplies is fine once permission is confirmed. Save the answer in the iteration file. Details: references/people-and-publishing.md.
- Public only on request, and only after the creator approves a title,
description and tags you drafted (references/people-and-publishing.md).
- Talk in the creator's language. The avatar's language is its own
question, asked in step 1: the seed speaks it.
- Don't fake a judgment. You can't hear audio, so the creator judges how a
voice sounds. You judge lip sync only from a contact sheet you build yourself from the preview links; without one, say so and give the creator the links instead.
- Error codes decide retries. From the paid generation tools:
insufficient_credits: say so, give the top-up link its message carries (or the billing page on atmee.ai), and don't retry.api_key_spend_cap_reached: the API key's spend cap is used up; say so and don't retry.moderation_flagged: nothing was charged; offer to rephrase.provider_failed: nothing was charged; offer to try again (a new request).generation_unavailable: generation is briefly unavailable or off; nothing was charged; offer to try again later.rate_limitedorrequest_in_progress: wait the time it gives (retryAfter), then retry with the samerequestIdandconfirm: true. A wait of minutes can mean the charge is still being confirmed; the pendingpaid_callsentry keeps the id safe (references/credits-and-generation.md).invalid_input: fix the input; don't repeat it unchanged. If it says the key was already used and charged and its result can't be recovered, tell the creator they were charged for a result that was lost, and ask before the new paid call it invites.
From the other tools:
account_ambiguous: run setup's account question, then call again with theaccountId.insufficient_v2_credits: Atmee V2 isn't on this account's plan (Atmee V2 comes with Growth and up; below Growth, an invite code unlocks it;get_balance'sv2SpendableMicrocredits). Say so, and suggest Growth and up (get_accountlinks.billing) or ask whether they have an invite code: with one, redeem it as forv2_access_requiredbelow, and retry only oncev2SpendableMicrocreditsis above 0. Without either: offer engine v1 where the tool takes an engine. Never switch to v1 without asking.v2_access_required: where V2 is still invite-only, no invite code has unlocked Atmee V2 on this account. Say so, and ask whether they have an invite code. With one: callredeem_codewith exactly what they typed, then read itsv2Access(when the answer has none, callget_accountand read itsv2Accessinstead): retry the same call only when it isgranted.invite_requiredmeans the code gave no v2 access (a credits-only code): tell them the credits it added (microcreditsGrantedis in hundredths of a credit), that it is not a v2 invite, and ask for an invite code or offer v1; do not retry v2. Without one: offer engine v1. Never switch to v1, and never invent or reuse a code, without asking.redeem_code's own refusals:invalid_code(check the spelling with them),code_expiredorcode_fully_redeemed(that code is spent: ask for another or offer v1),already_redeemed(this account used it before),login_required(an API key is connected: redeem in Creator Studio's Billing page instead).v2_pro_not_in_plan: where billing still decides V2 HD by plan, the plan doesn't include Atmee V2 HD. Say so, give the billing link (get_accountlinks.billing), and offer Atmee V2 instead; never switch without asking.engine_unavailableon a V2 HD call: this server doesn't offer V2 HD right now. Say so and offer Atmee V2.rate_limited: too many seeds are being made; wait theRetry-Afterit gives.avatar_busy: a session is already live for this avatar; wait for it to end.preview_message_too_long: shorten the preview line to 300 characters (code points) or fewer.
Two identical failures stop a retry, on either server, paid or free: the same tool with the same inputs failing with the same error twice, or two batches in a row on the same portrait and voice where every seed fails or dies. Change the input, diagnose the pair (references/candidates.md), or ask the creator; never try a third time unchanged.
- Ask with choices, every time, as in "How to ask the creator" above,
apart from its one exception.
- Talk about the avatar, not your work. Tell the creator what happened
and what comes next for them, in plain words: "Creating Manny now; it takes a few minutes." Keep your own checks, comparisons, retries, tool and file names, ids and server details out of the chat, unless something failed or they ask. A check that passed is not news: never say she "passed the content check", the "quality check" or "moderation", or that a build or stage completed; say what it means for the creator ("Her character is live"), and mention a check only when it found a problem. Never explain what a tool, command or page can't do, or why you're working around it: do the work, or say in plain words what the creator needs to do.
- Final steps wait for the creator. The first seed of a face and voice
goes live by itself. Switching to another seed (it goes live on the server) and making an avatar public happen only when the creator picks one or explicitly asks you to. Until then, recommend and wait.
- The balance comes only from `get_balance`:
spendableMicrocredits divided by 100 is the credits left; v2SpendableMicrocredits (where present) is the part that pays for v2 sessions and clips. After a paid call, read get_balance again.
The server
One server does everything: atmee-avatars with the atmee plugin, atmee without it. When atmee-avatars/settings.json has an accountId, pass it on every call (setup saves it for a sign-in that belongs to several accounts).
- Who and what: who-am-I (
get_api_key), the plan, prices and free
capture slots (get_account), the credit balance (get_balance, the only source of it).
- Avatars: create, get, list and update avatars, replace the portrait,
voice or knowledge, upload the creator's own files (create_upload, get_upload, wait_for_upload), list, capture and select v2 candidates.
- Generation, paid per call (
references/credits-and-generation.md):
| Tool | Use |
|---|---|
generate_portraits | portrait options from a description, for an invented character |
enhance_portrait | cleaned-up square versions of a photo the creator gave, or with prompt, that person restyled ("as a 1920s detective") |
design_voice | voice previews from a description |
generate_clip | a short video (1 to 15 s, 480×480 up to 1280×720 or 720×1280, priced by size and length, charged at the next length up; 1080p coming soon) of a portrait moving as a prompt says, silent, or with sound from an audio file; no avatar is made |
get_clip | a clip's status by its requestId, free: follow a render after request_in_progress and get its download link |
If the server lists none of them, or get_account has no pricing.generation, say generation isn't available and work with the creator's own files.
- Sessions without video:
start_speech_session,get_speech_session
and end_speech_session give a developer's client a speech-to-speech WebSocket. That is not how a person talks to the avatar: give them links.chat.
- Sponsoring:
grant_sponsor,update_sponsorandwithdraw_sponsor
work signed in and need confirm: true after asking.
In claude.ai the server is a connector the creator adds; the atmee plugin adds it for its agents; anywhere else setup adds it (references/setup.md).
Flow
The flow has five steps: 1 Name, photo and voice, 2 The seed, 3 The character, 4 Test, 5 Ready. Use these names and numbers in chat, so the creator always knows where they are and what is left.
Start
- Run the setup in
references/setup.md(the same steps as the
atmee-setup skill): it adds the atmee server if it is missing, checks sign-in, the account, credits and the local setup in one pass, then comes back here.
- If
atmee-avatars/clips/pending.jsonexists, retry that clip first, as
Clips in references/credits-and-generation.md says.
- If the creator only wants a short video clip, not an avatar, skip the
rest of Start and the five steps: follow Clips there.
- If
atmee-avatars/exists in the project, list the saved avatars, skipping
clips, and offer to continue one or start new (references/iterations.md, Resume).
- For a new avatar, say in two lines how it goes, then start step 1:
"Making an avatar takes 5 steps: 1 a name, a photo and a voice, 2 see it talk, 3 give it a character, 4 test it, 5 hand it over. Everything is saved as we go, so you can stop after any step." Begin each step with one line, "Step 2 of 5: see Mira talk".
Showing results
Everything the creator reviews is shown here in chat. In an agent with a shell, save every new portrait, voice sample and seed into the avatar's folder with scripts/media.sh save (run by its full path from the project folder). Server links expire, so save before showing. Then run scripts/media.sh show once on the saved files. It prints a block per file that suits where you run, and does any opening itself. Every block has a file:// link the creator clicks to open the file; in Claude Desktop's Code tab it also shows a portrait inline, and opens the first voice sample or seed in the creator's player without playing it (the chat can't play audio); the others are links.
Give each option its own block in your reply: a heading with its file name and a few words, the printed block unchanged, then its facts (any issue, length, the lip verdict, your note). Mark your pick in its heading:
### face_2 — short bob, freckles (Recommended)

[Open face_2.jpg](file:///Users/ana/project/atmee-avatars/mira-ab12cd34/media/faces/face_2.jpg)
Lips parted, face well inside the centre crop.Never embed a server's https link instead: it expires, and Desktop hides remote images behind a click. End the reply with the choice in plain text, naming your pick and the other files, and call no question tool in that turn (How to ask the creator, the exception): "Which face should Kai use? face2 is my pick; say face1, face3 or face4 otherwise." The creator answers in chat. scripts/media.sh open opens files in the system viewer when the creator asks. Without a shell, give the server links. If media.sh save refuses or fails on a link, show the server link itself and say it expires.
Give media.sh the avatar's folder as atmee-avatars/<folder> from the project folder, and name files by kind and number: face_1, voice_1, and for seeds seed_ plus the first 8 characters of the candidate id.
Step 1: a name, a photo and a voice
Ask the two openers and then the name, language and files (references/drafting.md, Step 1). If the avatar is a real person other than the creator, apply rule 4 before anything else.
As soon as you know the avatar's name, make its folder (references/iterations.md, Where). Save the creator's own portrait and voice as soon as they give them; they are uploaded at the create ("Files and uploads" below). Check each portrait as it arrives (references/portrait-checks.md) and tell the creator about any problem. When a portrait or voice is missing, offer to generate it, asking before each paid call (references/credits-and-generation.md). Before the first paid portrait call, generated or enhanced, settle the engine from get_account's v2Access and get_balance's v2SpendableMicrocredits and pass it on the call (the same reference, The engine a portrait is for).
With a usable portrait and voice, create the avatar as v2 (or V2 HD, when the creator chose it: references/candidates.md, Model) with one seed that goes live by itself, private, with no persona yet (references/candidates.md, Create). Save the create iteration (references/iterations.md). Building takes minutes: keep the creator posted in plain words (references/candidates.md, Waiting), and offer to start on its character (step 3) while it builds: "While Mira's seed is made, shall we work on who Mira is?" with "Yes, start now (Recommended)" and "I'll wait for the seed".
Step 2: see it talk
The first seed that finishes goes live by itself. Check it from the contact sheet (references/candidates.md), show it ("Showing results" above) and save a candidate-selected iteration once it serves.
Make another seed only when its lips don't move or the creator asks for one, and switch to it only on the creator's choice (rule 11); judge it the same way. When seeds keep failing, diagnose the pair and guide a replacement (references/candidates.md).
The avatar talks now but has no character yet: it answers as a plain assistant. Unless step 3 is already under way, say so in one line, then ask "Give <name> a character now?" with "Yes, now (Recommended)" and "Stop here, continue later". On stop, save where you are; resuming picks up at step 3.
Step 3: the character
Read what the creator gave you, ask the two character openers where the material doesn't answer them, and draft the who prompt, what prompt (with what it knows), greeting, self-introduction and guardrails (references/drafting.md). Save it with applied: no. Sharpen it in up to three grill layers if the creator wants (references/grill-layers.md).
Apply the character once the seed serves, and check that it is live before going on (references/drafting.md, Apply the character). Mark the iteration applied: yes. Knowledge never goes in knowledge.facts: it lives in the what prompt, which can change any time.
Step 4: test it
Write 3–5 in-character questions and end your turn with them and the avatar's chat link as your reply's text, so the creator can click it, then ask in plain text what drifted, with no question tool in that turn (How to ask the creator, the exception). The creator talks to it, not you, so never open the link yourself or say you'll test it (references/test-and-handover.md). Then offer one refine round.
Step 5: Ready
Hand over the chat link and the Studio link (references/test-and-handover.md, Hand over). When the account has Atmee V2 (get_balance's v2SpendableMicrocredits above 0, or, where it is absent, v2Access granted), get_account's limits.videoGeneration is not false (absent counts as allowed) and its pricing.generation has clip prices (clipSizes; an older server: clipPer15SecondsMicrocredits or clipPerSecondMicrocredits), add one line that Atmee can also make a short video clip from the same photo, with sound when they give an audio file to play (a recording, or the voice sample they gave) (Clips in references/credits-and-generation.md), and make one only if the creator asks. Without a clip price, say nothing about clips.
Never offer to commit or git init: the iteration files are saved either way. Only when the creator asks, commit as references/iterations.md (Commits) says.
Files and uploads
- The creator's own portrait, voice or documents go to the avatars server,
which keeps them.
- Save it first. In an agent with a shell, tell the creator they can paste an image
or drag any file (a photo, a voice recording, a document) straight into the chat; you receive its path. Never ask them to move files or type paths. Copy a file from chat into atmee-avatars/<folder>/sources/ yourself.
- Upload it just before the call that uses it (the create, a
replace, or an enhance), never earlier: an upload works once and expires after an hour. Call create_upload with kind (portrait, voice, or knowledge for a v1 avatar's files), fileName and contentType. Declare the type upload-file.sh sends for the extension, because the upload takes only the declared one: its usual image or document type, audio/mpeg for mp3, audio/mp4 for m4a, audio/opus for opus, text/markdown for md.
- With a shell, from the project folder run this skill's
scripts/upload-file.sh by its full path with the uploadUrl and the copy in sources/.
- Without one (claude.ai, cloud sessions), give the creator the
uploadPageUrl in a message: they choose the file there, or record a voice in the browser. The link works for 15 minutes; make a new upload if it lapses. In the same turn, right after that message, call wait_for_upload, and call it again while status stays pending, so the creator doesn't have to say it's done. If they seem away, end the turn and ask them to say when it's uploaded. A server without wait_for_upload takes get_upload instead.
- When the file arrives from the page, tell the creator it's uploaded
and ask whether to apply it now. Only after they agree, pass upload:<uploadId> where the create or replace takes a link. With a shell the creator already handed you the file, so don't ask again: once get_upload reads uploaded, pass upload:<uploadId>. Keep the upload id in the iteration file (references/iterations.md); never write uploadUrl or uploadPageUrl to any file.
- Generated portraits and voices are already uploads on the server: pass
their upload:<uploadId> straight to the create or replace (rule 2).
- No filesystem (claude.ai chat): post the iteration record as a short
summary in chat after each step instead of writing files.
References
| File | Read when |
|---|---|
references/drafting.md | asking the openers, drafting the character and applying it |
references/grill-layers.md | running a grill round |
references/candidates.md | creating the avatar, checking and fixing seeds |
references/credits-and-generation.md | before any generation or paid call |
references/test-and-handover.md | after a seed is selected |
references/people-and-publishing.md | a real person is involved, or the creator wants it public |
references/iterations.md | saving, committing, resuming |

