Prerequisite
This skill requires thedecoding script and Bopomofo dictionary bundled in the upstream repo(about 5 MB) to work; this directory
only contains SKILL.md and reference materials. Please install directly from the source:
git clone https://github.com/Oliviaiii/bopomofo-rescue.git ~/.claude/skills/bopomofo-rescue
After installation, a UserPromptSubmit hook is also attached, so decoding happens automatically the moment a message is sent, with no prefix command needed.
Requires Python 3, and python must be on PATH.
This skill requires the decoder script and Bopomofo dictionary (~5 MB) bundled in the
upstream repository — only SKILL.md and references/ are vendored here. Install from
source with the command above. Requires Python 3 on PATH.
What this skill solves
Taiwanese engineers commonly use the Bopomofo input method. When you forget to switch the input method from English back to Chinese, the Chinese you meant to type
turns into a string of keypresses — for example, you meant to type "你好嗎" but typed su3cl3a8. This string is not English, nor
is it garbled text; it isthe physical keys of the Bopomofo keyboard. This skill restores it back to Chinese so you don't have to
retype it and can continue your original request.
Core principle
Always use scripts/decode_bopomofo.pyfor the restoration step; do not do it in your head.
When the LLM guesses the key mapping by itself, it often makes mistakes (for example, it will say dj94 means "是的" when it actually means "快").
This program is pure table lookup + syllable segmentation + dictionary word segmentation (IME-style maximum probability), and will directly give youBopomofoand
Chinese guesses. Your job is toconfirm or correctits guesses using context — this is your strength, because
homophones must be disambiguated by surrounding context (ㄕˋ = 是/事/世/市…), and a standard IME has no context while you do.
Workflow
When a user message may contain Bopomofo mistypes:
-
Run the script(pass the entire raw message to it; it will pick out candidates itself and skip technical strings):
python "${CLAUDE_SKILL_DIR}/scripts/decode_bopomofo.py" --brief "使用者的原始訊息"By default use
--brief: returns only the fields needed for interpretation, about 10% of the full JSON, saving a lot of context. Remove--briefwhen you need homophone candidates or debugging (full output includeschinese_alternatives、confidenceetc.;--fulladditionally includes all tokens'segments)。Key fields of the output JSON:
has_candidates: whether suspected Chinese mistypes were detected.candidates[]: for each candidate,bopomofo(Bopomofo),chinese(the dictionary's best Chinese guess),tier(confidence level), and possiblyrepair(typo remediation suggestions, see below).reconstructed: the whole-sentence version with candidates replaced byChinese(when the dictionary is available) or[注音], directly readable.
-
Decide behavior based on
tier(see below).(see below). -
Use context to confirm the
chineseguesses, substitute them back into the original sentence, and thencontinue doing the work according to the restored meaning。
Behavior by confidence level
The script has already converted confidence into three levels. Please respond according to this principle; the key point isnot to interrupt the development rhythm:
| tier | Confidence | Suggested behavior |
|---|---|---|
high |
≥ 0.90 | Silent restoration, continue directly according to the restored meaning. No need to make a big announcement. |
medium |
0.65–0.89 | Useone sentenceto note your inference (e.g., "su3cl3a8 I understand it as 'how are you'") then continue. |
low |
< 0.65 | Do nothing by default. Only adopt it when the context makes the meaning very obvious; otherwise understand it as the original text. |
low mostly pure-letter tokens that can be forcibly split into syllables but may actually be English (e.g., npm、git、
html). For these,better to let them pass, unless the whole sentence's context is clearly Chinese and this token is out of place.
Confirm the Chinese guess (your job)
The script has already used a word-frequency dictionary to give the chinese best guess (common sentences are mostly directly correct). You are responsible forchecking against the context:
- By default adopt
chinese. Likesu3cl3a8→ how are you,g42k7→ yes, usually directly correct. - When the context doesn't fit, instead look at
chinese_alternatives. The dictionary only looks at frequency, not context; if the best guess doesn't make sense in the sentence, pick a reasonable one from the homophone candidates (candidates forㄕˋcandidates: yes/try/time/ten/matter…). - If no matter how you spell it, it doesn't form reasonable Chinese, thenfall back to the original textand understand it literally; don't force it. This fallback is very important — mistakenly treating
npm run devas Chinese can cause real harm. - When the dictionary is absent (data file not installed)
chinesewill be empty, with onlybopomofo; in that case you interpret the Zhuyin based on the context.
repair: remediation suggestions for typing mistakes
Sometimes the tier is highand the Zhuyin can be split, but chinese is empty — this usually meanstwo adjacent keys were typed in reverse. For example, "說" = ㄕㄨㄛ should be typed gji, but typed quickly as jgi, which splits into ㄨ + ㄕㄛ: the syllables are valid, but Mandarin has no such word, so the dictionary naturally finds nothing.
In this case the script appends a repair array (at most 3 suggestions):
"repair": [{"kind": "transpose", "from": "jgi", "to": "gji",
"chinese": "說", "note": "相鄰兩鍵對調後詞典可完整還原"}]
How to use:
- When you see
repair, prefer itschinese, because the original interpretation doesn't yield any Chinese at all, while this suggestion can be fully restored by the dictionary — it is almost certainly closer to the user's intent than the original interpretation. - But still confirm with the context. Transposition is only one of the most common typing mistakes; it doesn't guarantee it's the user's intent.
- If the
repairsuggestion doesn't make sense in the context, fall back to the original interpretation(the originalbopomofois always retained), interpret the Zhuyin yourself, or just handle the original text. - When there are multiple suggestions, pick the one most reasonable in context; it isn't necessarily the first.
repairis only a suggestion: the scriptwill notrewritebopomofobecause of it, norwill itraiseconfidence. The final judgment is your job.
Safety boundaries (important)
- The script already excludes code blocks, inline code, URLs, paths, git hashes, CLI flags, version numbers, and identifiers containing uppercase letters. You should stilljudge once more: if a certain "candidate" is actually a filename, variable, or command in context, do not restore it.
- This skill onlyinterpretsthe input and does not change the intent of the request. After restoring, please act according to the user'soriginalmeaning.
Examples
Example 1 (high, silent)
Input:su3cl3a8 幫我看一下這個 function
Script:chinese=你好嗎 tier=high,reconstructed=你好嗎 幫我看一下這個 function
Your understanding: respond to the request directly following "你好嗎,幫我看一下這個 function" without specifically explaining the restoration process.
Example 2 (corrected with alternatives)
Input:ej94k6 這個字怎麼念(assuming chinese is guessed to not make sense in context)
Script: gives chinese and each syllable's chinese_alternatives
Your action: choose the character that makes sense in context from the candidates; if it still cannot form reasonable Chinese, fall back to the original text.
Example 3 (technical string, not triggered)
Input:run npm install then git commit -m fix in ./src/app.py
Script:has_candidates=false
Your action: handle it exactly as the original text, without any restoration.
References
When manual verification is needed or the script is unavailable, you can consult:
references/keyboard-layout.md— the complete Daqian-style Zhuyin keyboard mapping table and the list of valid finals.references/exclusion-rules.md— which strings should be skipped and why.
But under normal circumstancesalways go by the script output, and do not use the reference table to recompute the key mapping yourself.