select-vocab-items

name	select-vocab-items
description	Select appropriate vocabulary items from data/vocab.json based on the learner's level, topic preference, and recent mistake patterns.

select-vocab-items

When to Use

Invoke this skill when building a daily vocabulary task or when the learner runs /jp-vocab. It filters and ranks vocabulary items from the data layer to ensure the learner gets the most relevant items.

Inputs

Parameter	Type	Required	Description
level	string	yes	Learner's current JLPT level: "N5", "N4", "N3"
topic	string	no	Topic filter (e.g., "greetings", "travel"). Omit for mixed selection.
count	integer	yes	Number of vocab items to return
recent_mistakes	string[]	no	Vocabulary words or patterns the learner recently struggled with
exclude_mastered	boolean	no	If true, exclude vocab IDs in mastered_vocab_ids. Default: true.

Outputs

An ordered array of vocab items from data/vocab.json:

Each item includes all original fields: id, kana, kanji, romaji, meaning_zh, level, topic, example_jp, example_zh.

Additionally, each item includes:

Field	Type	Description
selection_reason	string	Why this item was selected (e.g., "matches recent mistake", "high frequency N5")
drill_mode	string	Suggested drill mode: "recognition", "production", "usage"

Logic

Selection Priority

Items are ranked and selected in this order:

1. Mistake overlap (highest priority): Items whose kana, kanji, or related concept appears in recent_mistakes[]. These go first regardless of topic.
2. Topic match: Items matching the requested topic field.
3. Level match: Items at exactly the learner's level (e.g., N5 items for N5 learner).
4. Active items first: Items in active_vocab_ids (in progress but not mastered) before entirely new items.
5. New items: Items not yet seen, sorted by frequency (higher-frequency items first).

Drill Mode Assignment

• Items matching recent_mistakes: assigned "production" mode (active recall)
• Items in active_vocab_ids with prior exposure: assigned "usage" mode (use in sentences)
• Brand new items: assigned "recognition" mode (show and explain first)

Count Handling

If fewer items exist than count requests (e.g., only 3 N5 travel vocab items but count=5), return all available and note the shortfall.

Example

Input:

{
  "level": "N5",
  "topic": "greetings",
  "count": 3,
  "recent_mistakes": ["すみません"],
  "exclude_mastered": true
}

Output:

[
  {
    "id": "vocab_003",
    "kana": "すみません",
    "kanji": "済みません",
    "romaji": "sumimasen",
    "meaning_zh": "對不起／打擾一下／不好意思",
    "level": "N5",
    "topic": "greetings",
    "example_jp": "すみません、駅はどこですか？",
    "example_zh": "不好意思，請問車站在哪裡？",
    "selection_reason": "matches recent mistake",
    "drill_mode": "production"
  }
]