fluent-speaking-import
Import the results of a Claude app voice speaking session back into Fluent — fetch the results JSON from a Slack channel, Google Drive, pasted text, or a raw transcript, validate and re-score it, conv
SKILL.md.claude/skills/fluent-speaking-import/SKILL.md
GitHubSpeaking Practice Import (Voice Round-Trip, Step 2 of 2)
Overview
Closes the loop opened by /fluent-speaking-export: takes the results JSON
produced by the claude.ai "Fluent Speaking" Project (schema defined in
.claude/references/voice-project-instructions.md), validates it, converts it
into one update-db.py payload, and records the session exactly like a native
/fluent-speaking session — results markdown, mistakes, SM-2 reviews, streak.
This skill is the authoritative scorer. The external chat's output is evidence, not truth: validate every field, re-derive what doesn't add up.
When to Use
Trigger on /fluent-speaking-import, or when the learner's message indicates
they just finished (or want to pull in) a voice session — e.g. "I'm done with
voice practice", "pull in my results", "import my speaking session". Don't
fire on vague mentions of speaking practice with no completion/import intent
(e.g. a question about how voice mode works).
Instructions
1. Load context
python3 "${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/hooks/read-db.py"
Need: computed.next_session_id, computed.today, mistakes_db (existing
pattern_ids), spaced_repetition (item ids), learner profile
(preferences.voice_slack_channel, preferences.voice_slack_channel_id).
2. Locate the results
In order:
- Pasted by learner — if the message invoking the skill (or the next
one) contains a
fluent_voice_resultsJSON block, use it. - Slack — if
preferences.voice_slack_channelis set: loadmcp__claude_ai_Slack__slack_read_channelvia ToolSearch (andmcp__claude_ai_Slack__slack_search_channelsonly as a fallback — see below). Preferpreferences.voice_slack_channel_idif already saved on the profile — skip the channel-name search entirely and callslack_read_channel(channel_id, limit=5)directly. If novoice_slack_channel_idis saved yet, resolve it once viaslack_search_channels(voice_slack_channel)and save the resulting ID to that preference field (a normal profile edit) so future imports skip the lookup. Scan the 5 newest messages (returned newest-first) for one containingfluent_voice_results. If none of the 5 match, fetch one more page of 5 older messages (10 total) and stop — do not paginate further. If still not found after those 10, fall through to Google Drive / ask the learner. If the JSON was split across a parent message and a threaded reply (the export skill does this for long cards, but results are always small — check anyway), useslack_read_threadto pull the reply and concatenate. - Google Drive — load
mcp__claude_ai_Google_Drive__search_filesvia ToolSearch; querytitle contains 'fluent-voice-results', take the newest match, read it withread_file_content. (The file may have been converted to a Google Doc — extract the JSON from the text representation.) - Raw transcript fallback — if the learner pastes a chat transcript with
no JSON block, reconstruct the data yourself: identify each
question/answer exchange and score it with the
fluent-speaking/voice-project-instructions.mdrubric (Communication /5, Grammar /3, Vocabulary /2). Tell the learner you're re-scoring from the transcript.
If nothing is found, ask the learner to paste the JSON block from the chat.
3. Validate (authoritative-scorer pass)
fluent_voice_resultsmust betrue;session_refmust match an existing/results/fluent-voice-card-{session_ref}.md(warn and continue if the card is missing; abort ifsession_refis absent entirely).- Multi-language guard: if
<data_dir>/languages.jsonexists (multi-language mode active) and the results JSON has alanguagefield, compare it (case-insensitive) against the active language's label. On a mismatch — e.g. the learner practiced Swedish by voice but English is currently active — stop and ask: "This session was in {results_language}, but {active_language} is your active language. Run/fluent-language switch {results_language}first, then re-import?" Importing into the wrong language's databases silently corrupts that language's streak/mastery, so never import across a mismatch without confirmation. - Duplicate guard:
grep -l "{session_ref}" results/fluent-speaking-session-*.md— if any hit, this session was already imported. Stop and tell the learner (re-import would double-count streak/session stats). - Per question: each of communication (0-5), grammar (0-3), vocabulary (0-2)
clamped to range; recompute
scoreas their sum (ignore the reportedscoreif it disagrees). - Per error:
categorymust be one ofgrammar,formal_informal,vocabulary,spelling,prepositions,articles,missing— relabel to the closest canonical category if not;severitymust becritical/moderate/minor(defaultmoderate). date: validYYYY-MM-DD, not in the future — else usecomputed.today.duration_minutes: integer 1-120 — else estimate 2 min per question.
4. Convert to the update-db payload
| Payload field | Derivation |
|---|---|
session_id |
computed.next_session_id (NEVER from the JSON) |
date |
validated results date |
duration_minutes |
validated duration |
command_used |
"/fluent-speaking-import" |
skills_practiced |
["speaking"] |
skill_scores.speaking |
{exercises: len(questions), correct: count(communication >= 4), time_minutes: duration_minutes} |
errors[] |
flatten questions[].errors; collapse duplicates by pattern; pattern_id = existing mistakes_db id when category+context match one, else {category}_{context_in_snake_case}; carry category, severity, your_answer, correct_answer, context |
review_results[] |
for each card "Tutor focus" line whose pattern_id exists in spaced_repetition items: {item_id: pattern_id, quality: floor(score_of_probing_question / 2)} |
new_vocabulary[] |
one entry per new_words[] item: item_id = snake_case content (article stripped), item_type: "vocabulary", content/answer from the entry, category: "voice_session", difficulty = learner CEFR level, initial_quality: 3, priority: "medium" |
topics_covered, breakthroughs, focus_next_session |
pass through |
session_notes |
"Voice session via Claude app ({session_ref}). " + results session_notes |
5. Write the session results markdown
/results/fluent-speaking-session-{NNN}.md (NNN from session_id),
following .claude/references/session-file-template.md exactly — same
headings and parsing markers (❌, ✅, **Score:** X/10,
**Accuracy:** N%, **Focus Areas:**). Set:
**Skill:** speaking**Command:** /fluent-speaking-import- Add one line under the header:
**Modality:** voice (Claude app) — {session_ref} - One
### Question Nblock per results question, with the learner's spoken answer, corrections, and the recomputed score.
6. Update all databases
Use the fluent-db-updater skill: pipe the Step-4 payload to
python3 "${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.claude/hooks/update-db.py"
Exit 1 = fix payload and retry; exit 2 = report I/O error, nothing written.
7. Show the summary
Normal Fluent session summary: questions answered, accuracy, streak status, new words added to the review queue, focus for next session. Celebrate — this was REAL speaking practice. 🎉
Example — score recomputation
Results JSON says {"communication": 4, "grammar": 2, "vocabulary": 2, "score": 9}. 4+2+2 = 8 ≠ 9 → use 8. Review quality for a pattern probed by
this question: floor(8/2) = 4.
Critical Rules
- Never trust external data blindly. Clamp, recompute, relabel — the canonical rules live in this repo, not in the chat.
session_idcomes fromread-db.pyat import time. The voice chat must never pick it — another session may have happened in between.- One
update-db.pycall, at the end — same rule as every other session. - Duplicate imports are blocked, not merged.
update-db.pyrejects a reusedsession_idoutright (exit 1, nothing written); the Step-3session_refduplicate guard exists to catch it before that — re-running this skill on an already-imported session must not look like new progress. - Transcript fallback always exists. A voice session without a JSON block is still importable — you re-score it yourself.
- Slack is read-only here. This skill only reads from the channel; it
never posts.
/fluent-speaking-exportowns the one-timevoice_slack_channelpreference (this skill may still cachevoice_slack_channel_idas a read-side optimization if export hasn't yet). - Auto-invocable, but only on clear completion/import intent — the
duplicate-guard in Step 3 makes accidental re-firing harmless (it stops and
tells the learner rather than double-importing), so err toward firing when
the learner sounds done, not toward re-asking
/fluent-speaking-import.