Writing a MicroQuest as a file, and importing it

Building an eighteen-block MicroQuest one card at a time is slow. A MicroQuest is text, so you can write the whole thing as a single file — by hand, or by handing a topic to an AI tool — check it, and import it in one go.

Importing never publishes. An imported MicroQuest arrives as a draft. You preview it exactly as WhatsApp will send it, edit anything you want, and press Publish yourself. Nothing reaches a learner, and nothing goes on sale, until you do.

1. Start from the template

Open dev/learnchat-quests-src/_AUTHORING-PROMPT.md. It is written to be pasted straight into an AI tool: replace the TOPIC line with what you want the quest to teach, and it produces a complete file. EXAMPLE-phishing-first-line.md beside it is a finished quest you can hand over as a model.

The fastest way to get a template from something that already works: open any published MicroQuest in the console and press ⬇ Export .md.

2. What the file looks like

Frontmatter describes the quest; every block starts with ## at the start of a line.

---
code: SITE-INDUCTION
title: Site Induction
summary: What everyone arriving on site needs to know before their first shift.
objective: By the end you can find the assembly point and say who to report a hazard to.
category: Workplace Safety
minutes: 8
tags: induction site safety assembly reporting
price: free
credits: 0
---

## text: Welcome {#welcome}

Please read this before you start. It takes about eight minutes.

## check {#check-assembly}

Where is the assembly point?

- [ ] At the main gate
- [x] Behind the workshop

> Behind the workshop, away from the vehicle route, is where everyone gathers.

## acknowledgment {#ack}

Type *OK* to confirm you have read this.

The block words are text, check, challenge, reflection, acknowledgment, image, video, audio and document.

check teaches. challenge scores. A check is a knowledge check: a wrong answer costs nothing but shows the explanation, which is the moment the learner finds out they misunderstood. A challenge counts towards the pass mark. That one word is the most consequential thing in the file — get it wrong and a learner fails on a question you meant as practice.

- [x] marks the correct option. Exactly one per question, two to six options, and the > line underneath is the explanation shown after answering.

{#id} is a short name for the block. Always include one: it is how a question keeps its answer statistics when you re-import an improved version of the quest.

3. Paste it in

Go to MicroQuests → ⬆ Import Markdown, and paste the file or choose it from disk. It is checked as you type, and the panel beside it tells you three things:

• Problems — in red. Nothing can be imported until these are fixed. Each one names the line or the block.
• House standard — in amber. The shape every quest in the skillSYMS platform catalogue meets: at least 8 learning blocks, exactly 5 challenge questions, at least 2 checks, a reflection, an acknowledgment, and a closing recap. For your own academy’s quests this is advice, not a rule — a five-minute induction is a perfectly good MicroQuest and meets almost none of it.
• Changed for WhatsApp — in grey. WhatsApp is not the web, so **bold** becomes *bold*, headings inside a block become bold text, and - bullets become •. Everything changed is listed, so you can see it rather than discover it.

Press Import as draft. You land in the editor, on the quest you just made.

4. Check it before you publish

Two things are worth doing every time, and they matter most when an AI wrote the quest:

1. Press WhatsApp preview. That is the server’s own renderer — the messages shown are exactly what a learner receives.
2. Read every - [x] answer. A confidently mismarked answer teaches the opposite of the topic, and no software can catch it. If you are unsure about a fact, a law or a number, take it out. The template tells the AI not to invent statistics or cite legislation it is unsure of, but you are the check.

Then press Publish.

5. Improving a quest later

Export it, edit the file, and use ⬆ Replace from .md in the editor. That replaces the draft blocks only — learners who are part-way through keep the version they started on, and the published version does not change until you press Publish again.

Common problems

Related

• Building a MicroQuest in the editor — the block-by-block creator
• The format in full: dev/learnchat-quests-src/_AUTHORING-PROMPT.md