roleplay-author

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/.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.0 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.

1. Persona name. "Who are they? Real role title and a plausible name (e.g. 'Tom Reynolds — senior procurement engineer at OEM-A')."
2. 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."
3. Topic. "One sentence: what is this conversation about? E.g. 'Complaint about flicker on the B-sample shipped last week'."
4. 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."
5. 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?"
6. 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."
7. Pass threshold. "What percentage of total points does the trainee need to pass? Default 70%."
8. 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."
9. 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.