generate-listening-drill

generate-listening-drill

When to Use

Invoke this skill when a learner runs /jp-listen or when generate-daily-tasks assigns a listening task. It structures a listening item into an interactive drill format with clear stages.

Inputs

Parameter	Type	Required	Description
level	string	yes	Learner's JLPT level: "N5", "N4", "N3"
topic	string	no	Topic filter (e.g., "greetings", "travel"). Omit for any topic.
duration_target	integer	no	Max drill duration in seconds. Used to filter items by duration_seconds.
item_id	string	no	Specific listening item ID to use. If omitted, one is selected by level and topic.

Outputs

A structured drill object:

Field	Type	Description
item_id	string	The listening item used
title	string	Title of the listening passage
pre_vocab	object[]	3–5 key vocabulary items to preview before listening
transcript_segments	string[]	Transcript split into logical chunks for staged listening
comprehension_questions	object[]	Questions from the item's questions field
summary_task	string	Free-production task: learner summarizes the passage in Japanese
full_transcript_jp	string	Full transcript revealed after drill completion
full_transcript_zh	string	Full Chinese translation for self-check

Logic

Item Selection

If item_id is not provided:

1. Filter data/listening.json by level and topic (if given).
2. Filter by duration_seconds <= duration_target (if given).
3. Prefer items not recently used (check storage/daily_state.json completed tasks).
4. Return the first match.

Drill Structure (5-stage format)

Stage 1 — Preview vocabulary: Show pre_vocab items (3–5 key words from key_vocab). Give kana, meaning_zh, and one example sentence.

Stage 2 — First listen: Present the transcript in 2–3 segments. Instruct the learner to read (or listen) without translation and note what they understand.

Stage 3 — Comprehension questions: Ask all questions from questions[]. Learner answers in Japanese. No peeking at transcript yet.

Stage 4 — Second listen with review: Reveal the transcript segments again. Learner compares their understanding to the text.

Stage 5 — Summary task: Learner writes or speaks a 2–3 sentence summary in Japanese. This summary can be fed to review-answer for correction.

Segment Splitting

For dialogue transcripts, split by speaker turn. For monologue transcripts, split by sentence groups of 2–3 sentences.

Example

Input:

{ "level": "N5", "topic": "greetings", "duration_target": 60 }

Output (abbreviated):

{
  "item_id": "listen_001",
  "title": "自己紹介 — Self-Introduction at Work",
  "pre_vocab": [
    { "kana": "はじめまして", "meaning_zh": "初次見面", "example_jp": "はじめまして、よろしくお願いします。" }
  ],
  "transcript_segments": [
    "はじめまして。わたしはリンと申します。台湾から来ました。",
    "今日からよろしくお願いします。日本語はまだ勉強中ですが、頑張ります。"
  ],
  "comprehension_questions": [
    { "q": "この人はどこから来ましたか？", "a": "台湾から来ました。" }
  ],
  "summary_task": "このスピーチについて、日本語で2〜3文でまとめてください。"
}