bopomofo-rescue Skill Review: 8,800 Bytes That Call a Script the ok-skills Copy Doesn't Ship

The bopomofo-rescue SKILL.md inside mxyhi/ok-skills is 8,800 bytes, and its core rule is "還原這一步一定要用 scripts/decode_bopomofo.py，不要自己心算" (always use the script for the restore step, don't work it out in your head). The folder it sits in holds four files: SKILL.md, a LICENSE and two reference pages. There is no scripts/ directory.

The skill rescues Traditional Chinese typed on a Taiwanese Bopomofo (注音) keyboard while the input method was stuck in English mode, so 你好嗎 arrives as su3cl3a8. The author is OliLin (Oliviaiii), MIT licensed. ok-skills, an Apache-2.0 collection with 508 stars, vendors a copy. I read the vendored folder in full, plus the original repo's hook, plugin files and installer, and grep-scanned its decoder. I ran none of it. Token figures are file bytes ÷ 4, arithmetic you can redo.

What the skill actually says

The problem is narrow and real: the IME is in English mode, a Taiwanese developer types a Chinese request, and the agent receives literal keystrokes on the standard Dachen (大千) layout. The workflow: run the decoder with --brief on the whole message, let it skip technical strings, then check its best-guess Chinese against context.

Behavior hangs on a confidence tier: high (0.90 or above) restores silently, medium (0.65 to 0.89) gets a one-sentence note, and low is ignored unless context makes it obvious. Letters-only tokens like npm and git are capped at 0.60, so they never trigger silently. Two lines show the tone:

That's a sound split: key to symbol is a lookup table, and picking among homophones is judgment the model is good at. I rebuilt the 41-key map from the layout table in references/keyboard-layout.md and decoded its nine validation rows plus the transposition example. dj94 gives ㄎㄨㄞˋ (快); gji gives ㄕㄨㄛ (說). All matched. That checks the file against its own table, not an independent source.

Security gate: the vendored folder is markdown only, and I read all of it. The frontmatter pre-approves one command: allowed-tools: Bash(python "${CLAUDE_SKILL_DIR}/scripts/decode_bopomofo.py" *). My grep of the decoder found no subprocess, socket, urllib, requests, eval or exec; it reads a local dictionary (path overridable via BOPOMOFO_DICT). I did not read it line by line.

What it costs you in context

File-size arithmetic, not a session measurement: bytes ÷ 4.

Two caveats. ÷4 is tuned for English and CJK text usually costs more tokens per byte, so treat 2,200 as a floor. And everyone pays for the description: about 349 estimated tokens per session, even if you never type Zhuyin.

What the community reports

Public discussion is close to nonexistent. Hacker News (Algolia, stories and comments) had nothing for "bopomofo-rescue", "bopomofo claude code", "mxyhi ok-skills" or "zhuyin keyboard garbled". Web search surfaced only the repo's own pages and standalone decoders; I found no user write-up. What exists:

No real dissent exists. PR #19 is the only critical signal; its author has a stake in audit tooling, but I counted 1,349 characters myself and the spec page says "Max 1024 characters".

How to install it

From the original README (line 58) and the ok-skills README. I did not run either.

# full skill: SKILL.md + decoder + dictionary + hook (original repo)
git clone https://github.com/Oliviaiii/bopomofo-rescue.git ~/.claude/skills/bopomofo-rescue

# SKILL.md only, as part of the collection (ok-skills README)
mkdir -p ~/.agents/skills
cd ~/.agents/skills
git clone https://github.com/mxyhi/ok-skills.git ok-skills

You need Python 3 with python on PATH; with only python3, the README says to edit hooks/hooks.json. Deleting .claude-plugin/ drops the automatic hook. The skills.sh page's npx skills add mxyhi/ok-skills gives you the copy without the decoder.

Where it earns its keep, and where it doesn't

It earns its keep for one person: a Taiwanese developer who prompts in Traditional Chinese on a Zhuyin IME and sometimes forgets to switch. The decoder-plus-judgment design is right, and the exclusion rules skip uppercase, URLs, paths, flags, versions and filenames. The README says 27 of its 72 tests guard against false positives; tests/cases.tsv has 72 non-comment lines (not run). It earns nothing if you don't type Zhuyin, and the README's related-projects table lists a Windows hotkey tool that needs no model. The criticisms:

• The ok-skills copy can't do its main job. SKILL.md says to always use scripts/decode_bopomofo.py, and the folder has no scripts/. The file and the commit message disclose it, but one install becomes two.
• The description breaks the spec limit in both copies: 1,349 characters against 1,024, identical frontmatter in both repos.
• The headline example is generous. By the layout table a neutral-tone 嗎 is ㄇㄚ˙, typed a87. The example a8 has no tone key, and the repo's own table lists it as 媽／嗎／麻. In the dictionary, 嗎 tops the toneless key (frequency 26,437 against 26,436 for 嘛), so it probably works through frequency ranking. I didn't run the decoder to confirm.
• Shell quoting is a risk I couldn't test. SKILL.md puts the raw user message in double quotes inside a wildcard-approved Bash command. POSIX double quotes still expand backticks and $(...), and coding prompts contain backticks. The script reads stdin, but SKILL.md never says to use it. A design concern, not a demonstrated exploit.
• Narrow and untested. Dachen layout only, a PowerShell-only health check and installer, no accuracy figure on real typing, and I didn't verify the README's claim that a plugin.json folder under ~/.claude/skills registers its hook automatically.

FAQ

What does bopomofo-rescue do?

It recovers Traditional Chinese typed on a Bopomofo (Zhuyin) keyboard while the input method was in English mode, such as su3cl3a8 for 你好嗎. A Python decoder maps keystrokes to symbols and proposes Chinese, and the agent confirms from context. SKILL.md is 8,800 bytes; only the Dachen layout is supported.

Does the ok-skills copy work on its own?

No. It has 4 files and omits the 32,442-byte decoder and 4,953,956-byte dictionary that SKILL.md tells the agent to use. Its prerequisite section says to clone Oliviaiii/bopomofo-rescue.

How much context does bopomofo-rescue use?

By file-size arithmetic (bytes ÷ 4, an estimate, not a measured session cost): about 2,200 tokens for SKILL.md, 3,442 with both references, and 349 for the always-loaded description. The text is mostly Chinese, so ÷4 likely understates.

Does the description meet the Agent Skills spec?

Not by my count: 1,349 characters against a 1,024 maximum. PR #19 on mxyhi/ok-skills proposes a 951-character version and had no replies after 7 days. I did not test whether a loader rejects it.

Skill by OliLin (@Oliviaiii), MIT licensed (LICENSE file: "Copyright (c) 2026 OliLin (@Oliviaiii)"). Source: github.com/Oliviaiii/bopomofo-rescue, commit 2ac7d52 (2026-07-24). The reviewed copy comes from github.com/mxyhi/ok-skills (Apache-2.0 collection), commit 91108cf (2026-10-29). Review date October 31, 2026. Quoted lines are short excerpts for review purposes. Star counts, install counts and pull request states are as of this date, and community reception shifts over time. Token figures are estimates from file size.