fluent-language
List, switch, and add languages for multi-language learners — each language gets its own isolated set of the 6 databases under data/<slug>/, tracked in data/languages.json. Triggered only when the lea
Файлы1
Открыть в GitHubSKILL.md.claude/skills/fluent-language/SKILL.md
GitHubLanguage Switcher
Overview
Lets one learner study several target languages without any language's
progress overwriting another's. Each language lives in its own
data/<slug>/ directory holding the same 6 databases every other skill
already knows how to read and write; data/languages.json is a small
registry that tracks which language is active and shared learner identity
(name, native language) so adding a language never re-asks those.
See docs/plans/2026-07-10-multi-language-support.md for the full design.
This skill implements steps 3-4 of that plan (list/switch/add + first-run
migration trigger); fluent-setup implements the rest (new-install bootstrap,
per-language onboarding questions this skill reuses).
When to Use
Trigger only when the learner types /fluent-language, /fluent-language list, /fluent-language switch <language>, or /fluent-language add.
Gated with disable-model-invocation: true — switching changes which
database directory every other skill reads from on the next command; it
must never happen from an ambiguous chat message.
Instructions
0. Resolve the data root and check for the registry
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())
"
Then check for <data_dir>/languages.json:
- Missing, but
<data_dir>/learner-profile.jsonexists (flat single-language layout, never migrated): run the migration first —python3 "${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/hooks/migrate-multilang.py". It derives a slug fromlearner.target_language, moves the six databases and.backups/into<data_dir>/<slug>/, and writeslanguages.json. Confirm success (exit 0) before continuing — tell the learner what happened ("Your English progress now lives under its own language slot"). - Missing, and no
learner-profile.jsoneither (brand-new install): tell the learner to run/fluent-setupfirst — there's no language to list yet. - Exists: continue below with no migration needed.
1. /fluent-language or /fluent-language list — show all languages
Read <data_dir>/languages.json for the registry, then read-db.py with
FLUENT_LANGUAGE=<slug> set per language (or just read each
<data_dir>/<slug>/learner-profile.json + spaced-repetition.json directly)
to get level, streak, and due-review count for each.
## 🌍 Your Languages
| | Language | Level | Streak | Due Today |
|---|----------|-------|--------|-----------|
| ▶ | **English** (active) | B2 → C1 | 🔥 6 days | 3 items |
| | Swedish | A0 → B1 | — | 0 items |
**Switch:** `/fluent-language switch swedish`
**Add another:** `/fluent-language add`
If there's only one language, still show the table (so the learner discovers
add), but skip the switch hint.
2. /fluent-language switch <language> — change the active language
- Match
<language>againstlanguages.json.languageskeys/labels (case-insensitive, partial match ok if unambiguous). If no match, list available languages and ask again. - If the current active language has due reviews (check its
spaced-repetition.jsonreview_queue.today), warn once: "You have {N} items due in {current_language} today — they'll wait for you. Switch anyway?" Proceed on confirmation. - Update
languages.json: set"active"to the matched slug. This is a normal JSON edit (small registry file, not one of the six databases —update-db.pydoesn't touch it). - Confirm: "Switched to {language}. Level {current} → {target}, streak {N}
days." Every skill's next
read-db.py/update-db.pycall now resolves to this language's directory automatically — nothing else to do.
3. /fluent-language add — onboard a new language
Ask the learner which language, current level, target level, timeline, and daily goal minutes — the same fields
fluent-setupStep 3 collects, except name, native language, and explanation-language default (pulled fromlanguages.json.learner_name/native_languageinstead of re-asking). Still ask for this language's explanation-language preference explicitly — it can differ per language (e.g. immersion for a near-fluent language, native-language explanations for a brand-new one).Derive the slug the same way
migrate-multilang.pydoes: lowercase, non-alphanumeric runs collapsed to_. Refuse if<data_dir>/<slug>/already exists and is non-empty — that language is already set up; route to/fluent-language switchinstead.Create
<data_dir>/<slug>/and seed all 6 files fromdata-examples/templates, exactly likefluent-setupStep 5 — empty progress, empty mistakes, empty mastery, empty spaced-repetition queues, empty session log. Filllearner-profile.json'slearner.name/native_languagefrom the registry,target_language/ levels / timeline / daily_goal_minutes from this interview, andpreferences.explanation_languagefrom step 1.Add an entry to
languages.json.languages.<slug>(label, added date, level, target) but do not changeactive— let the learner decide whether to switch now:## 🎉 {language} added! Your English progress is untouched. Ready to start {language} now? 1. **Switch to {language} now** 2. **Stay on {current_language}, switch later** — `/fluent-language switch {language}`Never touch any other language's directory or files during this flow.
Critical Rules
- Never auto-invoke. Switching changes which data every other skill
reads/writes next — must be an explicit
/fluent-languagecommand. - Migration is offered, never silent, and happens at most once. If
languages.jsonalready exists, never re-runmigrate-multilang.py. languages.jsonis not one of the 6 databases. Edit it directly (Read + Write) —update-db.pyandread-db.pydon't touch it.- Adding a language never touches another language's directory. Only create files under the new slug's own directory.
- Ask this language's
explanation_languageexplicitly — never copy it from another language in the registry; immersion-appropriateness is language-specific (e.g. immersion for a near-fluent language, but native-language explanations for a brand-new one). - Don't force a switch after
add. The learner may want to finish today's session in the current language first.