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
- Author
- LeeGyeongPil ↗
- Repository
- encoding-roundtrip ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
- Rules
- Change a file: one command
- Only look, do not change
- When the script says no
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…