encoding-fixer

Encoding Fixer

IRON LAW: Every write_text() and text-mode open() in skill scripts MUST have encoding="utf-8". On Chinese Windows, Python defaults to GBK — emoji and Unicode characters crash. Fix immediately, don't wait for the error.

When to Run

• •After installing ANY new skill via npx skills add or manual download
• •When user reports encoding errors (GBK codec, UnicodeEncodeError, chcp)
• •Proactively after find-skills installs something

Workflow

Step 1: Run Auto-Fix

python3 .claude/skills/encoding-fixer/scripts/encoding-fix.py

This does two things automatically:

1. Scans ALL .py files under .claude/skills/
2. Adds encoding="utf-8" to every write_text() and text-mode open() that's missing it
3. Skips binary mode ("rb", "wb") — those don't need encoding
4. Skips webbrowser.open() — not a file operation

Step 2: Read the Report

The script outputs a two-part report:

`[FIXED]` — files that were auto-patched. These are done, no further action needed.

`[REVIEW]` — potential issues the auto-fixer couldn't handle. These are usually:

• •False positive (most common): multi-line calls like write_text(\n generate_html(...)\n) — the regex can't match across lines, but the call already has encoding="utf-8". Read the file at that line to verify.
• •Real miss (rare): the call genuinely lacks encoding, e.g. nested in a complex expression. Fix manually with Edit.

Step 3: Handle REVIEW Items

For each REVIEW item:

1. Read the file at the reported line
2. Check: does the call already have encoding="utf-8"?

- YES → mark as false positive, skip - NO → manually add , encoding="utf-8" to the call

Step 4: Verify Clean

After all fixes, re-run with --check-only to confirm zero issues:

python3 .claude/skills/encoding-fixer/scripts/encoding-fix.py --check-only

No output = all clean.

Anti-Patterns

• •NO: Installing a skill and forgetting to run the fixer
• •NO: Waiting for a GBK crash before fixing
• •NO: Assuming English Windows users don't need it — UTF-8 is correct everywhere
• •NO: Adding encoding to binary-mode open("rb") / open("wb") calls

Pre-Delivery Checklist

After fixing:

• •[ ] Auto-fix script ran successfully
• •[ ] All REVIEW items manually verified (false positive or fixed)
• •[ ] --check-only returns no issues