HSK Learning Skill for OpenClaw

Purpose: Provide a comprehensive HSK Chinese learning system with spaced repetition mastery tracking, vocabulary analysis, and adaptive quiz generation.

Version: 1.2.0 Author: Claw Date: 2026-02-18

Features

• Spaced Repetition Mastery System: Tracks mastery state (unknown/learning/mastered) for all 2,211 HSK 3.0 words using SM‑2 inspired algorithm.
• Vocabulary Exposure Analysis: Scans conversation logs, categorizes CJK tokens by HSK level, generates progress reports.
• Quiz Log Parsing: Automatically extracts vocabulary and correctness from quiz‑performance logs.
• Adaptive Quiz Generation: Creates quizzes prioritizing words due for review based on mastery.
• Comprehensive Toolset: Six tools for updating, querying, and managing the HSK learning system.

Tools

1. hsk_update_vocab_tracker

Parameters:

• force (boolean): Force update even if recent scan exists (default: false)

2. hsk_update_mastery_from_quiz

Parameters:

• date (string): Specific date (YYYY‑MM‑DD) or "all" for all logs (default: "all")

3. hsk_get_mastery_stats

Parameters:

• format (string): Output format: "text", "json", or "markdown" (default: "text")

4. hsk_get_due_words

Parameters:

• limit (number): Maximum words to return (default: 20)
• level (number): Filter by HSK level (1‑6), 0 for all (default: 0)

5. hsk_generate_quiz

Parameters:

• difficulty (string): "review", "learning", "new", or "mixed" (default: "mixed")
• format (string): "simple", "listening", "reading", "writing", or "full" (default: "simple")

• simple/full: Multiple choice, fill-in-blank, true/false, translation
• listening: Picture matching with audio sentences (use TTS for actual audio)
• reading: Passage comprehension with questions
• writing: Sentence and paragraph writing practice

6. hsk_parse_quiz_log

Parameters:

• filePath (string): Path to quiz log file (required)

Data Files

The skill maintains these data files in its data/ directory:

Setup & Installation

For New Users (First-Time Setup)

• Install the skill via ClawHub:

clawhub install hsk-learning

• Initialize your personal mastery database (required for each user):

cd skills/hsk-learning
   node scripts/init-mastery-db.js

• Optional: Configure user settings:

cp data/user-config.template.json data/user-config.json
   # Edit user-config.json with your preferences

• Restart OpenClaw gateway to load the skill:

openclaw gateway restart

Data Files Structure

Git Repository Setup

When publishing or contributing to this skill:

• User-specific files are automatically ignored via .gitignore
• Shared data files (HSK database) are included
• Initialization script creates user data on first run
• No personal data is committed to the repository

Testing the Skill

After restart, test basic functionality:

// In an OpenClaw session
hsk_get_mastery_stats({ format: 'text' });
hsk_update_mastery_from_quiz({ date: 'all' });
hsk_get_due_words({ limit: 5 });

Maintenance

• Mastery database updates automatically when quiz logs are processed.
• Vocabulary report updates via cron job or manual trigger.
• System health: Consider adding a weekly health‑check cron job.

Next Steps

• Update all HSK‑related cron jobs to use skill tools.
• Enhance quiz generation with GPT‑based passage creation.
• Add listening practice with audio generation.
• Implement HSK mock exams (full test simulation).

References

• HSK 3.0 word lists: mandarinbean.com
• Spaced repetition algorithm: SM‑2 (SuperMemo)
• OpenClaw skill documentation: https://docs.openclaw.ai