Type a prompt, get a SCORM-ready AI role-play with persona, rubric, and scoring. Open-source Agent Skill for L&D teams and educators. Free, MIT, by Mini Course Generator.
demo.mp4
A role-play here means a learner-vs-AI-character drill — sales pitches, customer de-escalation, compliance interviews, manager coaching, clinical intake — anywhere a person needs to practice a conversation against a believable counterpart with clear objectives and a rubric. Output is one self-contained HTML file you can drop into any LMS, or export as SCORM 1.2.
Examples · Why this exists · Use with any LMS · Quick start · How it works · FAQ
Three live role-plays you can try in your browser. Open the link, run a session end-to-end, get scored:
- Manager performance feedback — A senior engineer giving difficult feedback to a junior team member who's missed deadlines.
- Sales objection handling — An account exec navigating a price objection from a skeptical VP of Operations.
- Customer de-escalation — A support agent handling an angry customer who escalated from chat to a call.
Each one was authored from a single prompt, bundled to one HTML file, runs in any browser. Source compositions live in compositions/.
LLMs can already do role-play. Generic AI chat can't.
If you've tried using ChatGPT or Claude as a role-play partner inside a corporate training program, you know the failure modes: the AI character drifts out of role after 4 turns, there's no way to score the conversation against a rubric, and the output doesn't go into your LMS. So L&D teams either ship soft simulations that don't move the needle, or fall back to live role-plays that don't scale.
edu-role-play closes that gap. Structured persona that holds across the session. Objective tracking turn-by-turn. Rubric scoring at session end. SCORM export to any LMS. All authored from a single prompt by an AI coding agent — Claude Code, Cursor, Gemini CLI, Codex — using Anthropic's open Agent Skills standard.
Built and maintained by Mini Course Generator. Free, MIT licensed, no upsell.
Bundle as plain HTML or SCORM 1.2. Tested with Moodle, Canvas, Cornerstone, SAP SuccessFactors, MCG, and SCORM Cloud — works in anything that accepts SCORM 1.2 packages.
npx edu-role-play scorm my-roleplay.erpOutput is a .zip you upload as a SCORM activity. The role-play runs in the LMS iframe, scores report through the SCORM API, completion lands in your gradebook. No additional integration needed.
Full SCORM guide: docs/scorm.md.
- Agent-first authoring. Describe the scenario in plain language; the skill writes a structured composition, lints it against pedagogical rules, and bundles it.
- Single-file output. No build step on the consumer side. Drop the HTML into an LMS, a static site, or a Mini Course Generator Freeform Card.
- No API keys in the HTML. Inference goes through a Cloudflare Worker proxy you deploy once.
- LMS-ready. Bundle as plain HTML or as a SCORM 1.2 package.
- Open format. Compositions are HTML with custom elements (
<edu-role-play>,<edu-persona>,<edu-objective>,<edu-rubric>) — diff-able, version-controllable, hand-editable.
- Quick start
- Install
- Prompting patterns
- How it works
- Composition format
- The CLI flow
- Inference & sharing
- Repository layout
- FAQ
- Maintainers
- License
In your AI coding agent (Claude Code, Cursor, Gemini CLI, Codex), invoke the skill and describe the role-play you want:
Using /edu-role-play, create a role-play where a sales rep practices
pitching our CRM to a skeptical VP of Operations at a mid-market
logistics company.
The agent scaffolds the composition, validates it, and bundles it into a single self-contained HTML file. Paste that HTML into a Freeform Card in any Mini Course Generator course — or host it anywhere that accepts HTML.
Working examples to read or remix live in compositions/.
Install the edu-role-play skill, then describe the role-play you want:
npx skills add minicoursegenerator/edu-role-playThis teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to author pedagogically sound compositions, validate them, and bundle them into self-contained HTML. In Claude Code, the skill registers as a slash command — invoke /edu-role-play to start authoring.
Target a specific agent:
npx skills add minicoursegenerator/edu-role-play -a claude-code
npx skills add minicoursegenerator/edu-role-play -a cursorInstall globally (available in every project):
npx skills add minicoursegenerator/edu-role-play -ggit clone https://github.com/minicoursegenerator/edu-role-play
cd edu-role-play && npm install && npm run buildThen use the CLI directly: npx edu-role-play <command>. See The CLI flow below.
- Node.js 18+ for the CLI.
- A Cloudflare account if you want to deploy your own inference proxy (free tier is enough for prototyping).
- An Anthropic or OpenAI API key if you want higher-quality models than Cloudflare Workers AI.
Cold start — describe from scratch:
Using /edu-role-play, make a 10-turn compliance auditor role-play focused on GDPR subject access requests, with a pass/fail rubric.
Warm start — turn existing context into a role-play:
Using /edu-role-play, read
sales-playbook.mdand create a role-play for the objection-handling section.
Iterate — talk to the agent like an instructional designer:
Make the persona tougher. She should push back on price twice before engaging. Add an objective about uncovering budget authority. Bundle it and give me the HTML.
Tune the rubric — calibrate scoring after a dry run:
Re-weight the rubric so "quantify impact" is worth more than "build rapport". Bump the turn limit to 25.
A role-play composition is a single HTML file with custom elements declaring the persona, scenario, objectives, and rubric. The runtime (inlined at bundle time) drives a chat loop against a configured LLM, detects objective completion turn-by-turn, and scores the full transcript at the end.
author prompt
│
▼
[ agent + skill ] ──▶ composition (.erp / .html)
│
▼
[ linter ] ──── catches missing rubric, vague objectives, …
│
▼
[ bundler ] ──── inlines runtime + config
│
▼
self-contained HTML ──▶ learner's browser
│
▼
POST {proxy}/v1/chat
│
▼
Cloudflare Worker proxy
│
Workers AI / Anthropic / OpenAI
The runtime handles message history, streaming, objective tracking, and end-of-session scoring — all from inside the bundled HTML, with no build step on the consumer side.
<edu-role-play id="sales-pitch-skeptical-buyer" runtime-version="0.1.13">
<edu-persona name="Sarah Chen" role="VP of Operations">
<goals>Reduce vendor count by 30% by Q4...</goals>
<constraints>Budget locked until Q3...</constraints>
<speech-patterns>Direct; asks for specifics...</speech-patterns>
</edu-persona>
<edu-scenario>You are pitching a new CRM to Sarah...</edu-scenario>
<edu-objective id="discover-pain">Identify a current pain point</edu-objective>
<edu-objective id="quantify-impact">Get Sarah to share a number</edu-objective>
<edu-rubric>
<criterion objective="discover-pain" weight="3">...</criterion>
<criterion objective="quantify-impact" weight="4">...</criterion>
</edu-rubric>
<edu-termination>
<turn-limit>20</turn-limit>
<manual-end>true</manual-end>
</edu-termination>
</edu-role-play>| Element | Required | Notes |
|---|---|---|
<edu-role-play id runtime-version> |
yes | id is a slug; runtime-version matches the installed runtime. |
<edu-persona name role> |
yes | <goals> and <constraints> required; <background> and <speech-patterns> recommended. |
<edu-scenario> |
yes | Mentions the persona by name; addresses the learner in second person. |
<edu-objective id> |
≥1 | Observable verbs only — see objective patterns. |
<edu-rubric> > <criterion objective weight> |
1 per objective | Positive-integer weight; sum in [1, 20]. |
<edu-termination> |
yes | Must include <turn-limit> or <time-limit>. |
Full reference: docs/composition-format.md. Authoring rules the linter enforces: skills/edu-role-play/SKILL.md.
The full author → share path, agent or hand-driven:
# 1. Scaffold a composition from an archetype (or start blank)
npx edu-role-play init my-roleplay --archetype skeptical-buyer
# 2. Validate it against the DNA rules
npx edu-role-play lint my-roleplay.erp
# 3. Iterate locally — runtime inlined, no auto-open
npx edu-role-play preview my-roleplay.erp
# 4. Bundle into a single self-contained HTML
npx edu-role-play bundle my-roleplay.erp
# 5. Open the bundled HTML in your browser to try it
npx edu-role-play start my-roleplay.erp
# 6. (Optional) Package as SCORM 1.2 for an LMS
npx edu-role-play scorm my-roleplay.erpEvery command is non-interactive by design so agents can drive it. Full flag reference: docs/cli.md and skills/edu-role-play/cli-reference.md.
Bundled role-plays call a Cloudflare Worker proxy (POST {proxy}/v1/chat) — no API key ships in the HTML. The Worker can call Cloudflare Workers AI (via the env.AI binding, no key needed), Anthropic, or OpenAI. Source lives in packages/proxy-worker.
The shared public proxy is rate-limited and fine for iteration. Before sharing bundles with learners, deploy your own:
npx edu-role-play deploy-proxyThis guided command stages the proxy-worker template, prompts for provider (workers-ai | anthropic | openai) and key, runs wrangler deploy, and writes the resulting URL into your user config so subsequent bundle/start/scorm calls default to it. Override per-bundle with --proxy-url <url> or EDU_ROLE_PLAY_PROXY_URL.
No terminal? There's a one-click Deploy to Cloudflare path documented in docs/sharing.md.
| Provider | Cost | Quality for role-play | Setup |
|---|---|---|---|
| Workers AI | Free tier (~10k Neurons/day) | OK — Llama-class | Zero keys |
| Anthropic | Pay per token (your key) | Best | One paste |
| OpenAI | Pay per token (your key) | Good | One paste |
skills/— Agent Skills.edu-role-play/SKILL.mdis the main authoring skill consumed by Claude Code, Cursor, Gemini CLI, Codex.packages/core— TypeScript types and linter rules for compositions.packages/runtime— the inlineable chat loop, objective tracker, and rubric scorer that drives the bundled HTML.packages/cli— theedu-role-playbinary (init, lint, preview, bundle, start, scorm, deploy-proxy).packages/proxy-worker— Cloudflare Worker template that proxies to Workers AI / Anthropic / OpenAI.compositions/— example compositions and bundled outputs used in docs and tests.docs/— user-facing docs (getting-started, composition-format, cli, sharing, scorm, design-system, publishing).registry/— reserved for a future browsable archetype catalog.scripts/— build and utility scripts.
I'm an L&D person, not a developer. Can I use this? Today, the smoothest path is to ask someone on your team who's comfortable with a terminal to install the skill once and bundle role-plays for you. The CLI takes 5 minutes to install, and once it's set up, authoring is plain-language prompts in an AI agent. We're working on a no-terminal authoring path for non-technical users — see the roadmap.
Does the bundled HTML need an internet connection? Yes — it calls your proxy Worker for inference. Everything else (UI, runtime, scoring logic) is inlined and runs offline.
Where does the API key live? On the Worker, as a Cloudflare secret. Never in the HTML, never in the learner's browser.
Which LMSes have you tested with? Moodle, Canvas, Cornerstone, SAP SuccessFactors, MCG, SCORM Cloud. Anything that accepts SCORM 1.2 should work — file an issue if you hit a problem with a specific LMS.
Can I edit a composition by hand instead of through an agent?
Yes. It's plain HTML with custom elements. Run npx edu-role-play lint <file> to check it.
Can I host the HTML on my LMS?
If the LMS accepts arbitrary HTML, paste it into an HTML widget. For SCORM-only LMSes, use npx edu-role-play scorm to package it as SCORM 1.2 — see docs/scorm.md.
How is the rubric scored?
At session end the runtime sends the full transcript plus the rubric to the model and asks for per-criterion scores with rationale. Weights are normalized to a 0–100 score. Source: packages/runtime.
Which models work best?
Anthropic Claude (Sonnet or Opus) for serious scenarios; Workers AI Llama variants for prototyping. Set the model with --model at bundle time.
Can I version-control compositions? Yes — they're text. Diffs are readable; PR review works fine.
Is this only for role-plays? For now, yes. edu-role-play is the first skill in a series. The next one, focused on structured AI lessons, ships in a few weeks. Star the repo or follow @erengunduzz for updates.
- No-terminal authoring path for L&D teams who don't want to install a CLI — likely a hosted MCG flow that produces the same bundled HTML.
- More skills. edu-role-play is the first. Next up: structured AI lessons (concept explainers, quiz generators). One every 1-2 weeks.
- Browsable archetype registry. Curated starter scenarios for common L&D use cases (sales, manager training, customer service, compliance, clinical).
- Analytics export. Per-learner score history, time-on-task, objective completion rates, exportable to CSV or xAPI.
Open an issue if there's something specific you'd want to use this for and we'll see what we can prioritize.
Release checklist (lockstep-version the 3 npm packages): docs/publishing.md.
Published on npm: @edu-role-play/core, @edu-role-play/runtime, edu-role-play (CLI). Skill installable via npx skills add minicoursegenerator/edu-role-play.
MIT. See LICENSE.