| name | saramchae-ko |
| description | Make a Korean document read like a person wrote it — 어체 mixing and 번역투 out, clause-chained sentences split, source wrapping and paragraph breaks fixed, buried enumerations turned into lists and bullet soup turned back into prose, emoji cut to what carries meaning. Keeps term-level bold and tables; strips sentence-level bold. Ships a scanner that measures all of it first, including a 평서체/존댓말 count. Use on "문체 다듬어", "AI 티 빼줘", "가독성 검토", "읽기 좋게 다듬어", "이 문서 다듬어", "사람체", "이 문서 사람이 쓴 것처럼", "humanize this Korean doc". Never touches verbatim records, code, tables, or numbers. This is the Korean one and covers everything `saramchae` does, so use it whenever the document being edited is written in Korean — reach for `saramchae` only when it is not. |
saramchae-ko — Korean documents that read like a person wrote them
사람체: 사람 + 글씨체. The shape of writing a person actually produces.
A document fails in two ways at once. It sounds generated — 번역투, a 존댓말 sentence dropped into
평서체 prose. And it is shaped wrong — a 340-character paragraph, or nine nested bullets where two
sentences belonged. The reader experiences both as the same problem, so this handles both.
For a non-Korean document use saramchae. The structural checks are the
same there; what is missing is everything in sections 4.1 through 4.3, which only exists in Korean.
Do not run both on one document.
1. Never touch these
Getting this wrong is worse than leaving the document alone.
| Zone | Why |
|---|
| Verbatim records — transcripts, logs, chat exports | Rewording destroys the thing they exist to prove. When a spec demands an "unedited" record, editing prose is editing. Only credential masking is exempt |
| Code fences, command output, stack traces | Line breaks are data there |
| Tables | The row is the unit. Never flatten a table into bullets to "simplify" |
| Numbers, IDs, hashes, paths, API field names, versions | Never paraphrase a value |
| Quotations from a source document | A requirement quoted from a spec stays word-for-word |
CLAUDE.md and agent instruction files | Imperative voice and heavy bold are functional there. A 90% bullet ratio is correct for a file an agent parses |
Anything between <!-- saramchae:off --> and <!-- saramchae:on --> | The author marked it. Do not edit it and do not report it — the scanner already blanks it |
Frontmatter is exempt from every check — a description field is one long line on purpose.
A document about bad prose is full of bad prose: a style guide, a changelog quoting a bug report,
a before/after specimen. That is what the saramchae:off marker is for. If you find yourself
reporting a document's own examples back to it, the region needs the marker rather than an edit.
If the user says "전부 적용해 줘", still exclude the first row and say why in one line.
2. Do not add personality
The skill this one descends from has a section telling you to inject opinions, first person, and
lines like "I genuinely don't know how to feel about this." Ignore that for technical
documents. It was written for blog posts.
A 설계 노트, a 결정 기록, or a hiring submission is read by someone deciding whether to trust the
work. Injected voice reads as padding at best and as unseriousness at worst.
What to do instead:
- Plain declarative sentences. Pick one 어체 and hold it to the end of the document
- Vary sentence length naturally, but do not manufacture rhythm
- Keep the author's own judgments. Deleting
이건 위험하다 and leaving only neutral description is
over-correction, not neutrality
3. Measure first
The scanner sits next to this file, at scripts/scan.py. Resolve it from this skill's own
directory, not from the working directory — the working directory is the project being edited,
which is not where the skill is installed:
The directory depends on which agent loaded this skill and whether it was installed for one project
or for all of them. Use whichever of these exists:
SCAN=~/.claude/skills/saramchae-ko/scripts/scan.py
SCAN=<project>/.claude/skills/saramchae-ko/scripts/scan.py
SCAN=~/.codex/skills/saramchae-ko/scripts/scan.py
SCAN=~/.agents/skills/saramchae-ko/scripts/scan.py
SCAN=<repo-root>/.agents/skills/saramchae-ko/scripts/scan.py
python3 "$SCAN" FILE
If none of them resolve, find it instead of guessing: find ~ -name scan.py -path '*saramchae-ko*'.
Read the output as triage, not as a verdict. Most documents fail two of the seven checks. Section 7
lists what each number gets wrong; a finding you cannot see when you look at the line is a false
positive, so drop it and say you did.
If everything is clean, say so and stop. Not every document needs this.
4. The checks
4.1 어체 — the most common Korean-specific tell
LLMs drop a 존댓말 sentence into 평서체 prose, and the reverse. It is the single most frequent
Korean slip and the easiest to miss by eye. The scanner counts both and points at the minority:
[1] register: 평서체 6 / 존댓말 2 — mixed. minority 존댓말, 2 of them (25%)
L3 …수 있도록 작성되었습니다.
Do not simply convert the minority. Pick the 어체 that fits the document's purpose and move
everything to it: 존댓말 for a README or user-facing guide, 평서체 for a 설계 노트 or 결정 기록.
Either way, check the last paragraph against the first.
4.2 번역투 and filler
| Tell | Fix |
|---|
| ~에 있어서 | ~에서 |
| ~을 통해 (overused) | ~로, ~으로 |
| ~하는 데 있어 | ~할 때 |
| ~의 경우 (unnecessary) | delete |
| ~라고 할 수 있다 / ~로 볼 수 있다 | state it directly |
| ~을 진행하다 / ~을 수행하다 | use the verb: 한다, 만든다, 돌린다 |
| 결론적으로 / 요약하면 / 종합해보면 | delete; the conclusion is the sentence itself |
Inflated significance (번역투 과장)
| Tell | Fix |
|---|
| ~에 있어 중요한 역할을 한다 | say what it does |
| ~의 분수령 / 이정표 / 큰 획을 긋는 | usually delete; if the claim is real, state it plainly |
| ~을 시사한다 / 방증한다 | 보여준다, or name the evidence |
| 핵심적인, 필수적인, 획기적인 (overused) | keep at most one per document |
이번 마이그레이션은 팀 배포 문화의 분수령이 될 것이다.
→ 이 마이그레이션이 끝나면 배포가 주 1회에서 하루 여러 번으로 바뀐다.
Labels are chosen, not converted. In a document with an English sibling, the headings and bold
list labels are where the translation shows first — every sentence-level check passes and the label
still reads wrong.
| Tell | Fix |
|---|
조사로 끝나는 라벨 — 앱 밖에서, 설치 전에 | a label is a noun: 위젯과 알림, 설치 |
목록과 어긋나는 추상 명사 — 보관, 활용, 구성 | correct inside a sentence (본문 보관), wrong as the name of the section |
-하기 is not this. 시작하기, 기여하기 are what a Korean heading actually looks like.
The second row has no shape to detect, so the scanner never reports it. Read a label against its
siblings instead: where the rest are nouns a person says out loud (읽기, 계정), the abstract one
is the tell.
Structural tells — negative parallelism (단순히 ~가 아니라 ~이다: write the positive half
only), forced triads (three items because three sounds complete — if there are two, write two),
synonym cycling (사용자 → 유저 → 회원 for one thing: in technical writing, repeat the term), and
hedge stacking (~일 수도 있을 것 같습니다 → say it once, or say it is unknown).
Chat residue — 도움이 되셨길, 궁금한 점이 있으시면, ~해보시기 바랍니다, 물론입니다,
살펴보겠습니다. Delete outright.
4.3 Hard words
The target is a 한자어 with a plain everyday equivalent.
⚠️ This is where it goes wrong most often. 멱등성, 역직렬화, 레이스 컨디션, 백프레셔 are not
hard words, they are the words. Replacing a precise term with a description makes the document
longer and less exact. If a term has no shorter accurate equivalent, it stays.
| Swap | For |
|---|
| 활용하다 | 쓰다 |
| 수행하다 / 진행하다 | 한다, 돌린다, 만든다 |
| 상이하다 | 다르다 |
| 소요된다 | 걸린다 |
| 기입하다 | 적는다 |
| 용이하다 | 쉽다 |
| 제반 ~ | delete it |
| 도모하다 / 극대화하다 | 늘린다, 높인다 |
4.4 Sentence length
In Korean, clause count beats character count. The tell is chaining, not length: ~하며,
~하고, ~이며, ~는데, ~지만 strung together until one sentence carries four claims. Three or
more connectives is the signal whatever the length. Character count (flag at 90자) is the secondary
knob.
Split at the connective and promote the second half:
캐시 무효화는 배포마다 전체를 비우는 방식으로 동작하며, 이는 스테일 데이터를 방지하기 위한 것이고, 운영에서는 비용을 유발할 수 있으므로 버전 프리픽스를 활용하여 부분 무효화를 수행하는 것이 권장된다
→ 캐시 무효화는 배포마다 전체를 비운다. 스테일 데이터를 막기 위해서다. 다만 운영에서는 비용이 크다. 버전 프리픽스로 부분만 비우는 편이 낫다.
Do not chop everything to one length. Uniform short sentences are their own tell — generated
prose runs at one readability level while human writing is lumpy. Fix the sentences carrying more
than one claim; leave a long sentence that is genuinely one thought.
4.5 Line breaks
Three different things get called 줄바꿈. Fix them separately.
Source line width. Semantic line breaks — one sentence per source line,
breaking after an independent clause, wrapping under 80 characters. A one-word change stays a
one-line diff instead of reflowing the paragraph. Worth doing on anything under version control.
⚠️ Check the renderer first. In a .md file a single newline joins with a space, so this is
invisible in the output. In a GitHub issue or PR comment, in Notion, and in most chat renderers, a
single newline is a line break, and applying sembr there reshapes the rendered document. The
spec's own rule is that semantic line breaks must not alter rendered output — on those targets,
obeying it means not doing this.
Paragraph breaks. Over ~300 characters with no blank line is a wall. Korean packs far more
meaning per character than an alphabetic script, so the same count is a much denser block — this
threshold is under half the English one. Break at the topic shift, not at a count.
The opposite failure is as common: every paragraph one sentence long, which is a list that forgot
its bullets. If consecutive one-sentence paragraphs are parallel, make them a list (4.6). If not,
join them.
Rendered breaks. Never use a trailing double-space — invisible in source, and most formatters
strip it. Use a blank line, or a list. <br> only inside a table cell, where nothing else works.
4.6 Lists and numbering
Both directions matter. The scanner reports a bullet ratio: over ~60% is soup; under ~10% in a
procedural document usually means a buried list.
Prose → list when the prose contains:
- An enumeration in sentence form —
첫째 … 둘째 … 셋째, 먼저 … 다음으로 … 마지막으로
- Three or more parallel items chained with
~하고, ~며, or commas
- Ordered steps buried in a paragraph → numbered, not bulleted
- Two or more things compared on the same axes → a table, not a list
List → prose when one idea needs explanation rather than segmentation (a bullet is not a
paragraph with a dot on it), when a list has exactly one item (that is a sentence), when items run
past ~200 characters, when adjacent items depend on each other (the dependency is the connective
that got dropped), or when the whole document is bullets — readers describe that as running an
obstacle course.
| Rule | Detail |
|---|
| Length | 2–7 items. Over 7, group under sub-headings or use a table |
| Nesting | Two levels. A third is an outline pretending to be a list |
| Order | Bulleted for unordered, numbered for sequence or priority — never numbered to look organized |
| Parallelism | Every item the same grammatical shape: all ~다, all 명사형, or all ~음. Mixed endings inside one list is the most common slip |
| Lead-in | A complete sentence, a fragment ending in a colon, or a heading — not a heading and a colon |
| Punctuation | Periods only if items are complete sentences. Never a trailing , ; 그리고 또는 |
4.7 Emoji and decoration
Screen readers speak each emoji's Unicode name aloud, so three in a row is three spoken phrases
dropped into a sentence.
| Use | Verdict |
|---|
A legend defined once and used consistently (🧩 플러그인 · 📄 스킬) | Keep |
A persistent status marker in a working document (⚠️ on a known trap) | Keep, sparingly |
| Heading decoration | Cut. Every one |
| One per bullet as visual rhythm | Cut |
| Standing in for a word | Cut. It survives neither a screen reader nor a grep |
None in headings, none in a document being submitted or graded, never three in a row. If emoji carry
meaning they need a legend; if they need a legend and there is only one, it is decoration.
Em dash (—): fine as a definition dash, but LLMs cluster them. Roughly one per 20 lines; convert
the rest to 쉼표 or 괄호. Curly quotes (“ ”): straighten them.
4.8 Bold
Blanket bold-stripping ruins technical documents. Classify first.
| Kind | Example | Action |
|---|
| Sentence-level — a clause with a 서술어 | **이 설정은 운영 환경에서 쓰면 안 된다.** | Strip |
| Term / value — a noun phrase, number, or label | **512MB**, **타임아웃 3초**, **읽기 전용 모드** | Keep. A scanning aid, not decoration |
Rule of thumb: if it has a 서술어, unbold it. If it is a thing, keep it. Budget: at most one
sentence-level emphasis per section. A document where every third line is bold has no emphasis at
all. A high term-level count is normal in technical writing.
4.9 Rules that do not apply to Korean
Do not spend effort here — and do not invent Korean equivalents:
- Title case in headings. Korean has no case
- Copula avoidance (
serves as, boasts). The Korean analogue — ~로 자리매김한다, ~을 자랑한다
— is already covered under inflated significance in 4.2
- The rule of three as a word-level pattern. In Korean it shows up at the list level, covered in 4.6
5. Procedure
- Scan (section 3). Note which checks fired
- Read the whole file. 어체 consistency and bullet ratio cannot be judged from a diff
- Restructure before rewording — move text between prose and lists first, since that decides
which sentences still exist
- Then split sentences and fix words, line by line — see section 6
- Re-scan and confirm the numbers moved the way you intended
- Report as a table: check, before, after. Name the findings you dropped as false positives
Apply the edits without waiting for approval. Stop and ask only when a fix would change what the
document claims rather than how it reads.
6. The regex trap
Do not do this:
re.sub(r"\*\*(.{25,}?)\*\*", r"\1", line)
On a line with two bold spans it swallows the gap between them:
before: **캐시 무효화**: 배포 때마다 전체를 비운다. 키 전략은 **버전 프리픽스로** 바꿨다
after: 캐시 무효화**: 배포 때마다 전체를 비운다. 키 전략은 **버전 프리픽스로 바꿨다
The marker count stays even, so a balance check does not catch it — the bold silently moved to the
wrong words.
The same trap applies to every rule here. A global substitution for ~하며 hits 하며 inside a noun
and reaches into a quotation you were told not to touch. If you must batch, operate on one **…**
span at a time and skip any line with more than one. Better: targeted edits on the lines you
actually decided to change.
7. What the scanner gets wrong
- Sentence splitting is punctuation-based. A sentence ending in
다 with no period merges with
the next one, so a document that omits terminal periods reports inflated lengths
- The connective regex is verb-stem-anchored (
하고, 되며, 는데) because a bare 고/며
matches 참고, 사고, 명세. Past-tense forms are caught separately by their ㅆ 받침 (했고, 늘렸고,
시켰고), since the contraction lands on a different syllable each time and no stem list follows
it. Only the 고 form needs stems at all: 지만, 는데 and 으며 are listed bare, so 않지만 and
없는데 were never the gap. The stem list stays short on purpose — a stem is added only when it
cannot begin a noun, which rules out 알고 (알고리즘), 보고 (보고서), 가고 (국가고시), 맞고
(맞고소) and 주고 (주고받다). Sentences chained on those are caught by length alone or not at all
, counts toward the clause total but cannot trigger the check on its own. A sentence needs
at least one real connective before the clause rule fires, so A, B, C, D reads as the list it is.
The cost is that a genuinely long comma-spliced sentence is caught by its length alone or not at all- 어체 detection reads sentence endings only. 존댓말 inside a quotation counts; every
니다
except 아니다 is treated as 존댓말; and because 해요체 is caught by the bare 요 ending, a sentence
that happens to end on a noun like 필요 or 중요 is miscounted as 존댓말
- Bullet ratio counts lines, not ideas. A file of one-line reference entries is legitimately 90%
bullets —
CLAUDE.md is the standard case
- Parallelism is checked on the last character only. It catches
~다 mixed with 명사형 and
nothing subtler
- Emoji ranges are approximate. Arrows and
· are excluded deliberately as technical
punctuation, so a document decorating with → reports zero
- The label check reads the tail 조사 only.
-하기 headings are idiomatic and stay off the list,
and the other half of 4.2's label rule — an abstract noun that is wrong only as a label — has no
shape to match and never reports
8. Verification
Restructuring can drop content in a way that re-reading does not catch.
grep -cE '^\s*(`{3,}|~{3,})' FILE; grep -c '^|' FILE; grep -c '^#' FILE
grep -o '[0-9][0-9.]*\(ms\|초\|MB\|%\)' FILE | sort | uniq -c
git diff --word-diff=porcelain FILE | grep -c '^[+-][^+-]'
The last one is the sembr check: a pure re-wrap adds and removes no words. Any hit means the re-wrap
also changed the text.
Then one structural test — a bold span whose content starts with punctuation, which is the exact
shape section 6 damage takes:
python3 - FILE <<'PY'
import re,sys,pathlib
fence=open_bold=False; n=0
for i,raw in enumerate(pathlib.Path(sys.argv[1]).read_text().splitlines(),1):
if raw.lstrip().startswith("```"): fence = not fence; continue
if fence or raw.startswith("|"): continue
line=re.sub(r"`[^`]*`","·",raw)
parts=line.split("**")
if not open_bold:
for j in range(1,len(parts),2):
if parts[j][:1] in ":：,，.。)]" or not parts[j].strip():
print(f"{i}: bold span starts with punctuation — {parts[j][:50]}"); n+=1
if (len(parts)-1)%2: open_bold = not open_bold
if open_bold: print("EOF: a bold span was never closed"); n+=1
print(f"{n} finding(s)")
PY
It tracks delimiter parity across lines rather than grepping: bold wrapped onto the next line is
normal in prose, and a naive check reports every legitimate **항목**: 설명 as damage.
9. Extra rules for graded or submitted documents
When a reviewer is judging the work:
- No emoji anywhere, including body text
- No first-person color (
제 생각에는, ~인 것 같아요). State the judgment and its basis
- Quotations from the spec stay verbatim, in quotes — never paraphrase a requirement
- Keep every number, log line, and reproduction command. Density of evidence is the point;
trimming it to read smoothly defeats the document
- One 어체 throughout. Check the last paragraph against the first
Credits
Sections 1, 2, 4.2, 4.8, 4.9 and 6 are a derivative work. The rest — the 어체 check (4.1), the
structural checks (4.4 through 4.7), the scanner, and the verification — is original.
What this changes from upstream: it drops the "inject personality" section (§2), splits the bold rule
into sentence-level and term-level instead of stripping all of it (4.8), adds the protected zones
(§1), replaces the English pattern list with Korean ones, names the upstream rules that have no
Korean equivalent so nobody invents one (4.9), and adds the structural half that upstream does not
address at all.
Thresholds in the structural sections are sourced, not invented:
Both upstream skills are MIT. Their copyright notices and license terms are reproduced in full in
NOTICE at the root of this repository.
