Skip to content
Skills Library
Programming · Building & coding

encoding-roundtrip

/encoding-roundtrip

Edits text files that are not plain UTF-8 with LF (CP949, EUC-KR, Shift_JIS, GBK, Windows-1250/1251/1252, UTF-8 with BOM, CRLF or mixed line endings) byte-exactly. A bundled script applies a find/replace or line change in one call and writes the file back in its original encoding, BOM, per-line line endings and final newline, copies untouched lines as the original bytes, refuses characters the encoding cannot hold with the exact line, column and code point, and reports which files or lines use another encoding. Use when the user asks to change, add to or inspect a legacy-encoded, CRLF or BOM s

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/roundtrip.py

What it does and when to use it

Edits text files that are not plain UTF-8 with LF (CP949, EUC-KR, Shift_JIS, GBK, Windows-1250/1251/1252, UTF-8 with BOM, CRLF or mixed line endings) byte-exactly. A bundled script applies a find/replace or line change in one call and writes the file back in its original encoding, BOM, per-line line endings and final newline, copies untouched lines as the original bytes, refuses characters the encoding cannot hold with the exact line, column and code point, and reports which files or lines use another encoding. Use when the user asks to change, add to or inspect a legacy-encoded, CRLF or BOM s

Original author description

Edits text files that are not plain UTF-8 with LF (CP949, EUC-KR, Shift_JIS, GBK, Windows-1250/1251/1252, UTF-8 with BOM, CRLF or mixed line endings) byte-exactly. A bundled script applies a find/replace or line change in one call and writes the file back in its original encoding, BOM, per-line line endings and final newline, copies untouched lines as the original bytes, refuses characters the encoding cannot hold with the exact line, column and code point, and reports which files or lines use another encoding. Use when the user asks to change, add to or inspect a legacy-encoded, CRLF or BOM s

How it works

  1. Rules
  2. Change a file: one command
  3. Only look, do not change
  4. When the script says no
Original SKILL.md headings · 60 lines, 644 words
SKILL.md preview
---
name: encoding-roundtrip
description: Edits text files that are not plain UTF-8 with LF (CP949, EUC-KR, Shift_JIS, GBK, Windows-1250/1251/1252, UTF-8 with BOM, CRLF or mixed line endings) byte-exactly. A bundled script applies a find/replace or line change in one call and writes the file back in its original encoding, BOM, per-line line endings and final newline, copies untouched lines as the original bytes, refuses characters the encoding cannot hold with the exact line, column and code point, and reports which files or lines use another encoding. Use when the user asks to change, add to or inspect a legacy-encoded, CRLF or BOM source, config or text file, when an edit is refused as not valid UTF-8, when a file shows replacement characters or garbled Korean, Japanese, Chinese or accented text, when a diff suddenly covers a whole file, or to list which files in a folder or repository are not plain UTF-8 or use CRLF or a BOM. Not for converting files to UTF-8 permanently or normalizing line endings.
license: MIT
compatibility: Python 3.10+ (standard library only). No network access.
---

# Edit legacy-encoded files without changing their bytes

Agents read and write UTF-8 with LF. On a CP949, Shift_JIS, BOM or CRLF file that corrupts text or rewrites every
line. The bundled script does the byte work. `scripts/roundtrip.py` below is relative to this skill's folder: use
its full path and run it from the user's folder with the file path as the user gave it. `--lang ko` or `--lang en`
picks the message language.

## Rules

- Only the script writes such a file. Never change it with Edit, Write, MultiEdit, `sed -i`, `perl -i`, `iconv`,
  `unix2dos` or `dos2unix`, and do not Read or `cat` it to see the text (that shows garbled bytes).
- Stop early: one `edit` call normally finishes the task. After it succeeds do not run `verify`, `status`,
  `inspect` or `git diff`, and do not explore other files. If the named file or folder does not exist, say so and stop.
- End your answer with the `ER-SUMMARY` line printed by the command that wrote the file or refused to, copied
  exactly as one line, then one or two plain sentences.

## Change a file: one command

```
python3 scripts/roundtrip.py edit FILE --old 'exact old text' --new 'new text'
python3 scripts/roundtrip.py edit FILE --append-line 'new last line'
python3 scripts/roundtrip.py edit FILE --set-line '12:the whole new text of line 12'
python3 scripts/roundtrip.py edit FILE --insert-after '3:a new line after line 3'
python3 scripts/roundtrip.py edit FILE --delete-line 7
```

- `edit` detects the encoding, applies the change and writes the file once. BOM, the line ending of every unchanged
  line and the final newline stay as they were; new lines get the file's usual ending.
- `--old` must match exactly once (add `--all` to change every match). Options may repeat and combine. Write
  `--old='-text'` when the text starts with `-`. `--insert-after '0:...'` inserts before line 1.
- Need to see the text first (a line number, a typo): run `inspect --text FILE` once, then `edit`.
- Many scattered changes: `open FILE` (the file becomes a UTF-8/LF working copy), change it with your normal tools,
  then `close FILE`, and paste the `close` summary line. A file left open stays UTF-8: finish with `close` or `abort FILE`.

## Only look, do not change

- One file ("which encoding", "which lines are garbled", "do not modify"): run `inspect FILE` once. Name the
  encoding and the line numbers in `mixed_encoding_lines` (joined by `+`), then stop.
- A folder or the repository ("which files are not UTF-8, have CRLF or a BOM"): run `scan FOLDER` once (`scan .`
  when no folder is named or the named one does not exist). Answer from its table; do not inspect files one by one.

## When the script says no

A non-zero exit means nothing was written. Show the error line and the `ER-SUMMARY` line as printed, then:

- `E_UNENCODABLE`: list every `U+XXXX at line:column` exactly as printed and propose replacements (`-` for an em
  dash, `[OK]` for a check mark). Do not remove, replace or escape the character yourself; use
  `--replace xmlcharref` or `--replace question` only after the user agrees. Reason `euc_kr_filler` in a file the
  user calls CP949: run the same command with `--encoding cp949`. Reason `ascii_only`: ask which encoding to use.
- `E_AMBIGUOUS`: do not guess; ask for the encoding, then repeat the command with `--encoding NAME`.
- `E_MIXED_ENCODING`: list the lines from the output and ask how to proceed.
- `E_NO_MATCH`, `E_MANY_MATCHES`: run `inspect --text FILE` once and retry with the exact or a longer `--old`.
- `E_BINARY`, `E_UNSUPPORTED`: do not edit the file as text.
- `E_ALREADY_OPEN`, `E_NOT_OPEN`, `E_STATE_MISMATCH`: a session from `open` is involved; follow the message. Use
  `--force` only when the message offers it and the user agrees.

`verify FILE` compares a result with the original later if the user asks. Codec pitfalls (CP949 versus EUC-KR,
Shift_JIS versus CP932, Windows-125x) are in references/encodings.md.
Files in this package (3)
  • SKILL.md 5 KB
  • references/encodings.md 3 KB
  • scripts/roundtrip.py 104 KB

Versions

The database has no other skills named encoding-roundtrip.

Database snapshot: 13.11.2026 · package version e82961f16069 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100fixing-text-encodings
    Diagnoses garbled text and audits or bulk-converts non-UTF-8 files using the file-tools MCP server. Use when text looks like mojibake (Cyrillic rendering as Íàñòðîéêè, Ð/Ñ sequences, ????, or � characters), when surveying or migrating a legacy codebase's encodings…
  • 100windows-agent-shell
    A coding agent on Windows: Git Bash path rewriting, PowerShell quoting and encoding, CRLF. Use when output comes back garbled, or it works here and breaks there.
  • 100safe-text-editing
    改文件与传参的字符安全 playbook。当"内容写出来不对"时用:引号/反斜杠/反引号/`$` 被 shell 先解释、中文进 .cmd 变乱码、CRLF 与 GBK 被改写、整文件覆盖丢内容、替换串手抄失配、管道吞掉退出码、命令成功但改错地方。触发词:编辑出错、字符被吃掉、内容不对、乱码、转义、引号问题、sed 替换没生效、写进去的不是我要的、编码、GBK、CRLF、退出码不对。不用于:纯文本内容校对(走文档类技能)、.cmd 工具的整套改/验/发链(走 verify-windows-cmd-tool)。
  • 90windows-shell-rules-en
    Working rules for Claude Code on Windows - plain ASCII file names, UTF-8 when saving text, quoted paths with spaces, check which shell will run a command (PowerShell vs Git Bash), one task per conversation. Use whenever you create files or folders, save non-English text, or run…
  • 100wp-utf8-text
    Handle UTF-8 and text encoding safely in WordPress plugins, especially on WP 6.9+ where wp_is_valid_utf8(), wp_scrub_utf8(), and noncharacter helpers replace older seems_utf8-style checks. Covers when to validate, scrub, reject, or preserve invalid bytes; wp_check_invalid_utf8…
  • 100edit-mcp
    Precise local file editing with the edit-mcp tools or CLI. Replace text, replace or delete lines by number, replace by line:column, apply many edits in one call, and read lines or ranges with line numbers. Use when changing code in place, when exact line or column control is…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.