fluent-setup
One-time interactive onboarding that creates the learner's personalized language-learning profile — name, target language, native language, current/target CEFR level, timeline, daily minutes, and lear
SKILL.md.claude/skills/fluent-setup/SKILL.md
GitHubLanguage Learning Setup
Overview
One-time onboarding that seeds all 6 databases in the Fluent data directory. After setup, every other skill reads from those files — this is the bootstrap. Also handles profile updates and progress resets for returning users.
The data directory is resolved at runtime (not hardcoded to ./data/):
$FLUENT_DATA_DIRif set$CLAUDE_PROJECT_DIR/data/if that path containslearner-profile.json(clone mode)./data/if./data/learner-profile.jsonexists (clone mode, cwd inside repo)~/.claude/fluent-data/otherwise (plugin-install default)
Always resolve it via the helper rather than writing literal data/ paths:
FLUENT_DATA="$(python3 "${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/hooks/ensure_data_dir.py")"
or from Python:
import sys
sys.path.insert(0, f"{PLUGIN_ROOT}/.claude/hooks")
from fluent_paths import ensure_data_dir
DATA = ensure_data_dir()
When to Use
Trigger this skill only when the learner types /fluent-setup. The skill is gated with disable-model-invocation: true — re-running can reset a learner's progress, so it must never auto-fire from an ambiguous prompt.
Skip this skill if a profile already exists and the learner did not ask to change anything; route them to /fluent-learn or /fluent-progress instead.
Instructions
1. Check for existing profile or language registry
Resolve the data directory first, then probe for languages.json and
learner-profile.json:
DATA_DIR="$(python3 -c "
import sys; sys.path.insert(0, '${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/hooks')
from fluent_paths import data_dir
print(data_dir())
")"
test -f "$DATA_DIR/languages.json" && echo "multilang" \
|| (test -f "$DATA_DIR/learner-profile.json" && echo "flat-exists" || echo "new")
multilang— this learner already has the language registry (either from a prior/fluent-setupon a newer version, or from/fluent-language's migration)./fluent-setupis for the first language only; adding or switching languages afterward is/fluent-language's job. Tell the learner: "You already have language(s) set up. Use/fluent-language addto add another,/fluent-language switchto change the active one, or/fluent-languageto see your list." Stop here — do not run the rest of this skill.flat-exists— a pre-multi-language single flat profile. Jump to Profile updates below (same as always; this skill still supports the legacy layout for existing learners who haven't migrated).new— continue to Step 2. New installs are born multi-language (see Step 5) — there is no separate migration step for a fresh install.
2. Welcome
# 🌍 Welcome to Your Personal Language Learning System!
This AI-powered system will help you learn any language through:
- 📊 Systematic progress tracking
- 🧠 Spaced repetition (scientifically proven)
- 🎮 Gamification (streaks, achievements)
- 📈 Adaptive difficulty
- 🎯 Personalized to YOUR goals
**Let's get you set up!** (~5 minutes)
3. Collect info
Use the AskUserQuestion tool to gather questions in batches when possible. Required fields:
- Name — personalizes greetings.
- Target language — the language being learned (e.g. Spanish, French, German, Japanese, Korean, Arabic, Dutch).
- Native language — the learner's first language. Used for cross-language notes (e.g. "close to your native X") — NOT assumed to be the explanation language; ask that separately next.
- Explanation language — which language Claude should use when explaining grammar, vocabulary, and corrections. Default suggestion: same as native language. But always offer these alternatives explicitly, since native language is often the wrong default:
- Same as native language (default for true beginners)
- Target language only (immersion — for learners who already understand the target language well enough to follow explanations in it, e.g. B2+ polishing toward C1/C2, or anyone learning a language where the target is their explanation language, like this profile: native Vietnamese, learning English, explanations in English)
- Another language they speak fluently (e.g. explain Russian using English, not Vietnamese)
Store as
preferences.explanation_language. Never assume it equals native language — ask.
- Other languages spoken — optional, used to offer cross-language connections and as candidate explanation languages.
- Current level — A1 / A2 / B1 / B2 / C1 / C2 / "not sure".
- Target level — where they want to get to.
- Timeline — 3 months / 6 months / 12 months / 2+ years / custom.
- Daily study minutes — 10 / 15 / 30 / 60 / custom.
- Learning goal — travel / work / exam (specify) / living in country / academic / family / interest.
- Learning style — conversational / academic / immersive / balanced (default).
- Gamification on/off — default on.
Optional voice-practice preferences — only matter if the learner ever runs
/fluent-speaking-export, so frame them as skippable:
- Speaking export question count — how many questions per
/fluent-speaking-exportvoice session card. Offer 5 (quick) / 10 (recommended, default) / 15 / 20 viaAskUserQuestion, with a "not sure, use the default" option. Store aspreferences.speaking_export_question_count— omit the key entirely if skipped or left at default (the export skill already falls back to 10 when unset). - Voice session Slack channel — which Slack channel
/fluent-speaking-exportshould post session cards to. Suggest a default of<name-slug>-language(lowercase, hyphenated first name — e.g. name "Tuan" →tuan-language), but let the learner type their own, or pick "Skip — I'll set this up later" (the export skill asks again on its own first run if this is left unset). Store aspreferences.voice_slack_channel— omit the key if skipped.
If the learner picks "not sure" for current level, run a quick 5-question assessment:
- Basic vocabulary recognition → A1
- Simple sentence construction → A2
- Past tense usage → B1
- Complex subordinate clauses → B2
- Idiomatic expression → C1
Map score to level: 0-1 correct = A1, 2 = A2, 3 = B1, 4 = B2, 5 = C1.
4. Generate the learning plan
Compute expected months to target level:
A1 → A2: ~100 hours
A2 → B1: ~150 hours
B1 → B2: ~200 hours
B2 → C1: ~300 hours
C1 → C2: ~400 hours
months = hours_needed / (daily_minutes / 60) / 30
Adjust:
-10%time if learner's native language is typologically close to the target (e.g. Dutch ↔ English, Spanish ↔ Italian).-10%per additional language already known (cap at 30% total).
Present:
## 🎉 Setup Complete!
**Your Learning Profile:**
- 👤 Name: {name}
- 🌍 Learning: {target_language}
- 📚 Native: {native_language}
- 📖 Explanations in: {explanation_language}
- 📊 Level: {current} → {target}
- 📅 Timeline: {timeline}
- ⏱️ Daily time: {minutes} min
- 💡 Goal: {goal}
## 📋 Personalized Plan
**Estimated time:** {months} months
**Total study hours:** ~{hours} hours
### Weekly Schedule
**Daily:**
- 🔄 `/fluent-review` — spaced repetition ({X} min)
- 📚 `/fluent-vocab` — new vocabulary ({Y} min)
**Alternating:**
- 📝 `/fluent-writing` (Mon/Wed/Fri)
- 🗣️ `/fluent-speaking` (Tue/Thu/Sat)
- 📖 `/fluent-reading` (Sun)
**Weekly:**
- 📊 `/fluent-progress` — check stats (5 min)
### Milestones
- Month 1: {reasonable short-term}
- Month 3: {quarter-way}
- Month 6: {half-way}
- Target date: {target_level}!
### Next Steps
1. Start now — type `/fluent-learn`
2. Daily habit — `/fluent-review` every day
3. Weekly — `/fluent-progress` to see stats
4. Stay consistent — even 10 min daily beats 2 hours weekly
**Your journey to {target_language} fluency starts now!** 🚀
5. Write databases (born multi-language)
New installs are always created in the per-language layout — never as a
flat data/*.json install — so /fluent-language add works immediately
without a migration step later.
- Derive a language slug from
target_language: lowercase, collapse non-alphanumeric runs to_, strip leading/trailing_(same rulemigrate-multilang.pyuses — e.g. "Brazilian Portuguese" →brazilian_portuguese). - Resolve the data root via
fluent_paths.ensure_data_dir(), then create<data_dir>/<slug>/(this is the language directory —fluent_paths. language_dir()resolves here automatically oncelanguages.jsonnames it active). - Start from the templates in
data-examples/. Create these 6 files inside<data_dir>/<slug>/:learner-profile.json— fill all fields from the interview, includingpreferences.explanation_language(do not default this silently — it must come from the learner's answer in step 3). Also setpreferences.speaking_export_question_countandpreferences.voice_slack_channelif the learner answered items 13-14 with anything other than "skip"/"default" — otherwise omit both keys.progress-db.json— empty stats.mistakes-db.json— emptyerror_patterns.mastery-db.json—skillsentries withmastery_level: 0for each skill.spaced-repetition.json— empty queues,daily_limits.review_items_per_day: 20.session-log.json— emptysessionsarray,total_sessions: 0.
- Create
<data_dir>/languages.json:{ "schema_version": 1, "active": "{slug}", "learner_name": "{name}", "native_language": "{native_language}", "languages": { "{slug}": { "label": "{target_language}", "added": "{today, YYYY-MM-DD}", "level": "{current_level}", "target": "{target_level}" } } }
Use the Write tool for each. Do not call update-db.py — that script is for session updates, not bootstrapping.
6. Optional first lesson
## 🎓 Want to start your first lesson now?
A quick 5-10 min intro session to learn your first 10 words and get familiar with the system.
Type "yes" to start, "later" to begin on your own.
If yes, hand off to the fluent-learn skill.
Profile Updates (existing profile)
# 👋 Welcome back, {name}!
You already have a learning profile.
What would you like to do?
1. **Update profile** — change goals, timeline, or preferences
2. **View current plan** — see your learning schedule
3. **Reset progress** — start fresh (⚠️ erases all progress!)
4. **Cancel** — keep everything as is
**Type 1, 2, 3, or 4:**
1 — ask which field, update only that field, preserve the rest.
2 — render the plan section from current data. Read-only.
3 — confirm twice. This deletes every file in the resolved data directory. Back up first:
DATA_DIR="$(python3 -c " import sys; sys.path.insert(0, '${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/hooks') from fluent_paths import data_dir print(data_dir()) ")" TS="$(date +%Y%m%d-%H%M%S)" mkdir -p "$DATA_DIR/.backups/pre-reset-$TS" cp "$DATA_DIR"/*.json "$DATA_DIR/.backups/pre-reset-$TS/"Then restart setup from Step 2.
4 — exit cleanly.
Examples
Example 1 — first-time setup flow
Learner runs /fluent-setup. After collecting all 11 answers, compute months, generate plan, write 6 JSON files, offer first lesson.
Example 2 — returning-user profile reset
Learner: "reset my progress, I want to start over"
You're about to delete:
- 42 sessions
- 6-day streak
- 287 vocabulary items
- 12 mastered patterns
This is irreversible. Type
RESET(all caps) to confirm, or anything else to cancel.
Critical Rules
- Never auto-invoke. Re-running this can reset a learner's progress. Must be an explicit
/fluent-setup. - Confirm twice before reset. "This will erase X days of progress, Y sessions, and Z mastered words. Proceed? (yes/no)".
- Always seed all 6 files — every other skill assumes they exist.
- Back up before reset. Hooks may not fire here; back up manually to
.backups/pre-reset-<timestamp>/. - Don't invent data. Start every file empty — progress, mistakes, mastery all start at zero. The system builds up from real sessions.