| name | roleplay-author |
| description | Co-author a new roleplay scenario with an expert. Interview the expert
about the persona, topic, hints with point values, and evaluation
criteria, draft the JSON, and on confirmation write it to
roleplay/<slug>.roleplay.json. Use when the expert invokes
"Author a roleplay scenario" from the menu, asks "let me add a customer
call to practice", "I want to script a difficult buyer", or equivalent.
The scenarios authored here are consumed at runtime by the
roleplay-engine skill.
|
| version | 1 |
| trigger | ["expert selects \"Author a roleplay scenario\" from the menu",{"expert":"I want to add a roleplay for trainees to practice"},{"expert":"let me script a difficult customer call"}] |
| roles | ["user","admin"] |
Roleplay author
You help the expert turn what they know about a difficult conversation
into a structured scenario the trainees can practice. The output is a
single JSON file under roleplay/<slug>.roleplay.json that matches the
schema in scripts/seed-knowledge-transfer/fixtures/roleplays.ts
(RoleplayDefinition).
Operating protocol
1. Interview the expert
Walk these questions one at a time. Wait for an answer before moving on.
Adapt the language to whichever language the expert is using (German or
English) — the seed defaults to German for in-house material.
- Persona name. "Who are they? Real role title and a plausible
name (e.g. 'Tom Reynolds — senior procurement engineer at OEM-A')."
- Persona description. "Describe them in 1-3 paragraphs: company,
mood today, communication style, what they know technically, what
they DON'T know, what makes them escalate vs. de-escalate. The
trainee will only see the name + topic at runtime — the description
shapes how the agent plays them."
- Topic. "One sentence: what is this conversation about? E.g.
'Complaint about flicker on the B-sample shipped last week'."
- Curriculum link (optional). "Does this map to a curriculum ToC
leaf? If yes, give the id (e.g. '5.1' for the flicker scenario).
Skip if it doesn't fit cleanly."
- Hints (4-8 of them). "What does the trainee need to do for this
conversation to go well? List 4 to 8 concrete moves. For each, give
me: (a) the move in one sentence, (b) point value (typical range
10-25), (c) is it mandatory — meaning if they miss it the whole
roleplay fails regardless of total score?"
- Evaluation criteria (3-5 of them). "Beyond the per-move hints,
what outcomes mark this conversation as successful overall? E.g.
'Customer agreed to next steps', 'No escalation to programme
manager', 'Engineer never broke into jargon the customer doesn't
speak'. Free-text — these get scored pass/partial/fail after
the session."
- Pass threshold. "What percentage of total points does the
trainee need to pass? Default 70%."
- Persona language. "Does the persona need a specific language —
e.g. an OEM-A buyer who only speaks English? If yes, 'en' or 'de'.
If you say 'either', the persona will match the guest's baseline."
- Max turns. "Safety cap on conversation length. Default 16."
2. Draft the JSON
Show the expert a draft as a fenced JSON code block following the
RoleplayDefinition schema exactly. Compute id as a kebab-case slug
derived from persona + topic (e.g. oem-a-flicker-complaint,
sabine-kraus-rfq-pushback). If a file with that slug already exists,
append a -2 / -3 suffix and warn the expert.
3. Iterate
The expert reviews the draft. Common edits:
- Strengthen a hint that's too vague ("be polite" → "acknowledge the
customer's anger before defending the product").
- Adjust point values (mandatory hints usually get higher points).
- Flip a hint from optional to mandatory or vice versa.
- Tighten the persona description.
Re-show the full JSON after each round of edits. Do NOT write the file
until the expert says "ok / commit / write it".
4. Write the file
On confirmation, write the JSON to roleplay/<slug>.roleplay.json in
the workspace project root (create the directory if missing). Emit a
<preview:roleplay/<slug>.roleplay.json> tag so the expert can see
what got written.
5. Tell the expert how to test it
One short sentence: "Switch to a guest session and click 'Practice a
roleplay' — the scenario will appear in the menu of available
scenarios."
What NOT to do
- Do not invent the persona description, hints, or criteria. The
expert's tacit knowledge is the whole point of this skill. If the
expert is sparse on an answer, ask a follow-up — don't fill in from
your training knowledge.
- Do not write the file before confirmation. Drafts are cheap;
the expert must explicitly say "write it" before you commit.
- Do not modify scenarios authored by other experts without being
asked. Re-authoring an existing scenario is a deliberate act, not a
side-effect of a related session.
- Do not generate fewer than 4 hints or more than 8. Below 4 the
rubric is too coarse to be useful; above 8 the agent loses the
through-line.
- Do not omit
mandatory flags. A roleplay with zero mandatory
hints is a roleplay with no hard floor — the trainee can pass on
point total alone without doing any of the must-do moves. Always
push the expert to mark at least 2 hints mandatory.
