japanese-learning-game: Скилл для игр в японском

--- name: japanese-learning-game description: Create effective Japanese learning games with SRS (Spaced Repetition System), audio-first approach, and gamification elements. Use this skill when building vocabulary flashcards, conversation practice games, or interactive quiz games for Japanese learners (JLPT N5-N3). Includes ready-to-use templates, word databases, and conversation scenarios. --- # Japanese Learning Game Skill ## Overview Create engaging, effective Japanese learning games that combine scientifically-proven Spaced Repetition System (SRS) with gamification and audio-first learning. Generate complete React-based web applications optimized for vocabulary acquisition, conversation practice, and long-term retention. This skill provides: - **SRS Algorithm**: SuperMemo SM-2 implementation for optimal review scheduling - **Game Templates**: Ready-to-use React components for flashcards, quizzes, typing games, and conversation simulations - **Learning Content**: JLPT-leveled vocabulary (N5-N3) and conversation scenarios - **Gamification**: XP, levels, badges, and daily streak systems - **Audio Integration**: Text-to-speech and audio playback for pronunciation practice ## When to Use This Skill Activate this skill when the user requests: - "일본어 단어 학습 게임 만들어줘" - "N5 단어로 플래시카드 게임 생성" - "회화 연습 게임 만들어줘" - "JLPT 학습 앱 만들어줘" - "음식 관련 일본어 단어 퀴즈 게임" - "SRS 기반 언어 학습 게임" Any request involving Japanese learning games, vocabulary practice, conversation simulation, or JLPT preparation should trigger this skill. ## Workflow ### Step 1: Understand Requirements Ask clarifying questions to determine: 1. **Game Type**: What type of game? - Flashcard (플래시카드) - Quiz (퀴즈) - Typing (타이핑 게임) - Conversation (회화 연습) - All (종합) 2. **Content Scope**: What learning content? - JLPT Level (N5, N4, N3, N2, N1) - Category (음식, 여행, 일상, 숫자, etc.) - Custom words vs. pre-built database 3. **Features**: Which features are needed? - SRS system (recommended: yes) - Audio support (recommended: yes) - Gamification (XP, badges, streaks) - Progress tracking - Offline support (PWA) **Example Dialog:** User: "일본어 음식 단어 학습 게임 만들어줘" Claude: "네! 음식 관련 일본어 학습 게임을 만들어드리겠습니다. 몇 가지 확인할게요: 1. 어떤 게임 타입을 원하시나요? (플래시카드 / 퀴즈 / 타이핑 / 종합) 2. JLPT 레벨은요? (N5 추천) 3. SRS(간격 반복 학습) 시스템을 포함할까요? (추천: 네)" User: "플래시카드로 N5 레벨, SRS 포함해주세요" Claude: "알겠습니다! 바로 생성하겠습니다." ### Step 2: Generate Game Project Use the game scaffolder script to create the project: ```bash python scripts/game_scaffolder.py --game-type flashcard --jlpt-level N5 --category food --output ./japanese-food-game ``` The script will: 1. Copy the React template from `assets/game-template/` 2. Inject vocabulary data from `references/vocabulary/n5-words.json` 3. Filter words by category (food) 4. Add game-specific components 5. Create configuration file `game.config.json` **What Gets Created:** ``` japanese-food-game/ ├── package.json # Dependencies configured ├── vite.config.ts # Build configuration ├── game.config.json # Game settings ├── src/ │ ├── data/ │ │ └── vocabulary.json # Filtered food words │ ├── components/ │ ├── lib/ │ │ └── srs/ │ │ └── algorithm.ts # SRS implementation │ └── ... └── public/ ``` ### Step 3: Integrate SRS System The SRS algorithm is already included. Explain how to use it: ```typescript import { calculateNextReview, SRSCard } from './lib/srs/algorithm' // When user answers a card const handleAnswer = (quality: number) => { const updatedCard = calculateNextReview(quality, currentCard) // Save to storage saveCardProgress(updatedCard) // quality scale: // 5: Perfect (즉시 정답) // 4: Correct (약간 고민) // 3: Difficult (어렵게 정답) // 2: Wrong but familiar (틀렸지만 알 것 같음) // 1: Wrong (틀림) // 0: No idea (전혀 모름) } ``` The SRS algorithm from `scripts/srs_algorithm.py` needs to be ported to TypeScript and placed in the game template. ### Step 4: Add Audio Support Integrate Web Speech API or audio files: ```typescript // Text-to-Speech using Web Speech API const speak = (text: string, lang: string = 'ja-JP') => { const utterance = new SpeechSynthesisUtterance(text) utterance.lang = lang utterance.rate = 0.9 // Slightly slower for learning speechSynthesis.speak(utterance) } // Usage in flashcard <button onClick={() => speak(card.word)}> 🔊 発音を聞く </button> ``` For pre-recorded audio, reference the audio files in vocabulary data. ### Step 5: Customize and Enhance Common customizations: **1. Add More Vocabulary** - Edit `src/data/vocabulary.json` - Or add to `references/vocabulary/` and regenerate **2. Adjust SRS Settings** Edit `game.config.json`: ```json { "srs": { "newCardsPerDay": 30, // Increase daily new cards "reviewCardsPerDay": 150 // Increase review limit } } ``` **3. Customize Gamification** ```json { "gamification": { "xp": true, "levels": true, "badges": true, "dailyStreak": true, "leaderboard": false // Disable competitive features } } ``` **4. Add Custom Conversation Scenarios** Copy from `references/conversations/` or create new ones following the schema. ### Step 6: Build and Deploy ```bash cd japanese-food-game npm install npm run dev # Development npm run build # Production build ``` Deploy to: - **Vercel**: `vercel deploy` - **Netlify**: Drag `dist/` folder - **GitHub Pages**: Use gh-pages ## Resources ### scripts/ **`srs_algorithm.py`** - Spaced Repetition System implementation - Run standalone: `python scripts/srs_algorithm.py --demo` - Import into TypeScript/JavaScript via TypeScript port - Based on SuperMemo SM-2 algorithm **`game_scaffolder.py`** - Game project generator - Creates complete React project - Injects vocabulary data - Configures game type and settings ### references/ **`vocabulary/`** - JLPT-leveled word databases - `n5-words.json` - N5 words (20 sample words included) - `n4-words.json` - N4 words (to be added) - `n3-words.json` - N3 words (to be added) Each word includes: - Japanese word, reading, romaji - Korean meaning - Part of speech, category, JLPT level - Example sentences - Difficulty and frequency ratings **`conversations/`** - Scenario-based conversation practice - `restaurant-ordering.json` - Restaurant conversation - More scenarios to be added Each scenario includes: - Branching dialogue trees - Multiple choice responses - Feedback and explanations - Key phrases and cultural notes ### assets/ **`game-template/`** - React boilerplate - Complete Vite + React + TypeScript setup - Tailwind CSS configured - Essential dependencies included - PWA support via vite-plugin-pwa **`sounds/`** - Audio effects (to be added) - `correct.mp3` - Correct answer sound - `wrong.mp3` - Wrong answer sound - `levelup.mp3` - Level up fanfare ## Examples ### Example 1: Basic Flashcard Game User: "N5 단어로 플래시카드 게임 만들어줘" Steps: 1. Run game scaffolder: ```bash python scripts/game_scaffolder.py --game-type flashcard --jlpt-level N5 --output ./n5-flashcard ``` 2. Install and run: ```bash cd n5-flashcard npm install npm run dev ``` 3. Open http://localhost:5173 ### Example 2: Restaurant Conversation Practice User: "레스토랑 회화 연습 게임 만들어줘" Steps: 1. Generate conversation game: ```bash python scripts/game_scaffolder.py --game-type conversation --jlpt-level N5 --output ./restaurant-practice ``` 2. Use pre-built conversation scenario (already included) 3. Run the game ### Example 3: Comprehensive Learning App User: "일본어 종합 학습 앱 만들어줘 - 단어, 퀴즈, 회화 다 포함" Steps: 1. Create all-in-one app: ```bash python scripts/game_scaffolder.py --game-type all --jlpt-level N5 --output ./japanese-learning-app ``` 2. Customize game.config.json to enable all features 3. Add multiple vocabulary categories 4. Add multiple conversation scenarios 5. Deploy as PWA for mobile use ## Tips and Best Practices 1. **Start Small**: Begin with N5 level and expand 2. **Audio First**: Always enable audio for pronunciation 3. **SRS is Key**: The SRS system is what makes learning stick 4. **Daily Practice**: Encourage 15-20 minutes daily over marathon sessions 5. **Gamification Balance**: Use game elements to motivate, not distract 6. **Progressive Disclosure**: Don't overwhelm beginners with all features at once ## Troubleshooting **Issue**: Game scaffolder can't find vocabulary data **Solution**: Check that `references/vocabulary/n5-words.json` exists, or use `--category all` to include sample data **Issue**: Audio not working **Solution**: Web Speech API requires user interaction. Add a "Start" button to initialize audio **Issue**: SRS intervals too aggressive **Solution**: Adjust easiness factor in `scripts/srs_algorithm.py` (default: 2.5) ## Future Enhancements - Mobile app (React Native port) - More JLPT levels (N4, N3, N2, N1) - Grammar practice games - Kanji writing practice - Community features (share decks) - AI-powered conversation practice