insightflo/edu-deck-skills / edu-deck/shared/skills/humanize-korean
humanize-korean
VerifiedAI(ChatGPT·Claude·Gemini 등)가 쓴 한글 텍스트를 "사람이 쓴 글처럼" 윤문해주는 오케스트레이터 스킬. 번역투·영어 인용 과다·기계적 병렬·관용구·피동태 남용·접속사 남발·리듬 균일성·이모지/불릿 과다 등 10대 카테고리 70개 AI 티 패턴을 탐지·분류해 내용은 한 글자도 건드리지 않고 문체·리듬·표현만 자연스러운 한국어로 재작성한다. shim의 route_hint(light|standard|heavy)로 경로를 정해 잘 쓴 글은 1콜, 표준은 2콜, 중증·장문만 3+콜(진단→겨냥 윤문→finalize)로 처리한다. 트리거 — "AI 티 없애줘", "AI 같은 글 자연스럽게", "GPT/ChatGPT 문체", "AI 번역투 고쳐", "사람이 쓴 것처럼 윤문", "AI 윤문", "ChatGPT 티 제거", "한글 AI 탐지·윤문", "AI 글 사람처럼", "번역투 제거", "영어 인용 많은 글 윤문", "AI 글 티 안 나게", "휴머나이저", "humanize Korean", "AI detector bypass 한글". 후속 작업 — "특정 카테고리만 다시", "윤문 강도 조정", "장르 바꿔서", "이 문단만", "2차 윤문" 도 모두 이 스킬. 단순 맞춤법·오탈자 교정은 직접 처리, 번역은 번역 스킬, 내용 추가·삭제를 동반한 재작성은 별도 집필 스킬.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 28.5 KB |
| references/ai-tell-taxonomy.md | markdown | 120.7 KB |
| references/baseline.json | config | 8.5 KB |
| references/baseline_v2.json | config | 13.2 KB |
| references/design-notes.md | markdown | 5.8 KB |
| references/diagnosis-rules.md | markdown | 16.1 KB |
| references/empirical-validation.md | markdown | 14.7 KB |
| references/metrics.py | script | 14.7 KB |
| references/metrics_v2.py | script | 30.6 KB |
| references/quick-rules.footer.md | markdown | 2.9 KB |
| references/quick-rules.header.md | markdown | 2.2 KB |
| references/quick-rules.md | markdown | 16.2 KB |
| references/rewriting-playbook.md | markdown | 15.5 KB |
| references/scholarship.md | markdown | 34.7 KB |
| references/web-service-spec.md | markdown | 7.8 KB |
references/metrics.py
View on GitHub"""Humanize KR v1.6 quantitative metrics calculator.
External pre-processor for the monolith fast path. Run BEFORE the monolith
agent — its output (prepended to the input text) gives the LLM a numerical
baseline read so it does not waste tool-call budget computing comma rates
or counting hanja suffixes.
Hard rule: standard library ONLY (json/re/math/collections/os/sys/argparse).
No konlpy/bareun/mecab/spaCy. We approximate morphological analysis with
regex + a small hanja suffix dictionary. Final judgement is monolith's job.
CLI:
python metrics.py --input run/01_input.txt \
--genre essay --output run/00_metrics.json
"""
from __future__ import annotations
import argparse
import json
import math
import os
import re
import sys
from collections import Counter
from typing import Any
# ---------------------------------------------------------------------------
# Module-level constants
# ---------------------------------------------------------------------------
VERSION = "v1.6"
# Connective endings (-고, -며, -지만, -면서, -아서, -어서) followed by a comma.
# All of these end at a syllable boundary, so we anchor to the syllable + ",".
# Use a non-capturing group; allow space before comma (Korean writers
# sometimes type "...고 ,").
_ENDING_COMMA_RE = re.compile(
r"(?:고|며|지만|면서|아서|어서)\s*,"
)
# Eojeol = whitespace-separated token. Strip trailing punctuation for length
# accounting but keep raw token for diversity / suffix tests.
_EOJEOL_SPLIT_RE = re.compile(r"\s+")
# Sentence boundary: . ! ? + closing quote/bracket optional + whitespace or EOS.
# Korean text rarely uses semicolons; we keep them out to avoid false splits.
_SENTENCE_SPLIT_RE = re.compile(r"(?<=[\.!?。])\s+")
# Hanja-style nominalizer suffixes: 성, 적, 화. We only count them when the
# *token* ends with one of these AND has at least 2 chars before — that
# excludes the standalone particles "적" / "성" / "화" and short adverbial
# uses. We also skip pure-Hangul exact matches in a small block-list.
_HANJA_SUFFIXES = ("성", "적", "화")
_HANJA_BLOCK = {
# Common false positives — bare verbs / nouns that happen to end in these
# syllables but are not -성/-적/-화 nominalizations.
"있는화", "되는화", # placeholder — extend as needed
"맞아", "와서", # not actually -화 but caught for safety
}
# Tokens we never count for hanja density: numerals, English, single-char.
_PUNCT_STRIP_RE = re.compile(r"[\.,!?;:\(\)\[\]\{\}\"'`~、。“”‘’\-]+")
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _split_sentences(text: str) -> list[str]:
text = text.strip()
if not text:
return []
parts = _SENTENCE_SPLIT_RE.split(text)
# Each `parts[i]` may contain newlines; flatten on \n too.
out: list[str] = []
for p in parts:
for line in p.split("\n"):
line = line.strip()
if line:
out.append(line)
return out
def _eojeols(text: str) -> list[str]:
return [tok for tok in _EOJEOL_SPLIT_RE.split(text.strip()) if tok]
def _strip_punct(token: str) -> str:
return _PUNCT_STRIP_RE.sub("", token)
# ---------------------------------------------------------------------------
# 6 + 2 metric functions (signatures requested in the brief)
# ---------------------------------------------------------------------------
def comma_inclusion_rate(text: str) -> float:
"""Ratio of sentences containing 1+ commas (0~1)."""
sents = _split_sentences(text)
if not sents:
return 0.0
with_comma = sum(1 for s in sents if "," in s)
return with_comma / len(sents)
def comma_usage_rate(text: str) -> float:
"""Average comma count per sentence."""
sents = _split_sentences(text)
if not sents:
return 0.0
return sum(s.count(",") for s in sents) / len(sents)
def ending_comma_rate(text: str) -> float:
"""Ratio of connective-ending positions immediately followed by a comma.
Denominator = total connective-ending occurrences (with or without comma).
Numerator = ending + comma matches.
Returns 0.0 when the denominator is 0.
"""
if not text.strip():
return 0.0
# All occurrences of the endings (with optional trailing comma).
all_endings = re.findall(r"(?:고|며|지만|면서|아서|어서)(?:\s*,)?", text)
# Filter to those that actually represent a connective ending. The bare
# syllable can occur inside other words (e.g. "고기"), so we require that
# the syllable sit at an eojeol's end OR be followed by space/punct.
# Approximation: count regex hits whose match ends at a token boundary.
boundary_endings = re.findall(
r"(?:고|며|지만|면서|아서|어서)(?=[\s,\.!?、。]|$)", text
)
if not boundary_endings:
return 0.0
# Count those followed by comma.
with_comma = len(_ENDING_COMMA_RE.findall(text))
return with_comma / len(boundary_endings)
def comma_segment_length(text: str) -> float:
"""Average eojeol-count of comma-delimited segments across sentences."""
sents = _split_sentences(text)
seg_lens: list[int] = []
for s in sents:
if "," not in s:
seg_lens.append(len(_eojeols(s)))
continue
for seg in s.split(","):
seg = seg.strip()
if seg:
seg_lens.append(len(_eojeols(seg)))
if not seg_lens:
return 0.0
return sum(seg_lens) / len(seg_lens)
def conclusion_pivot_count(text: str, lexicon: list[str] | None = None) -> int:
"""Count occurrences of conclusion-pivot lexicon items."""
items = lexicon or ["결론적으로", "따라서", "이를 통해", "그러므로"]
return sum(text.count(w) for w in items)
def safe_balance_count(text: str, lexicon: list[str] | None = None) -> int:
"""Count occurrences of safe-balance hedge lexicon."""
items = lexicon or ["양쪽 모두", "두 가지 모두", "장점도 있지만", "신중하게", "균형"]
return sum(text.count(w) for w in items)
def hanja_nominalizer_density(text: str) -> float:
"""Token-level density of -성 / -적 / -화 endings (0~1).
Token = whitespace-split eojeol after stripping trailing punctuation.
A token "counts" only if it has >= 2 chars total (so bare "성", "적",
"화" don't count) and its final char is one of the three suffixes.
"""
tokens = [_strip_punct(t) for t in _eojeols(text)]
tokens = [t for t in tokens if t]
if not tokens:
return 0.0
hits = 0
for t in tokens:
if len(t) < 2:
continue
if t in _HANJA_BLOCK:
continue
if t[-1] in _HANJA_SUFFIXES:
hits += 1
return hits / len(tokens)
def lexical_diversity(text: str) -> float:
"""Type-token ratio over eojeols (unique / total)."""
toks = [_strip_punct(t) for t in _eojeols(text)]
toks = [t for t in toks if t]
if not toks:
return 0.0
return len(set(toks)) / len(toks)
# ---------------------------------------------------------------------------
# Baseline + z-score
# ---------------------------------------------------------------------------
def _default_baseline_path() -> str:
here = os.path.dirname(os.path.abspath(__file__))
# Baseline ships next to metrics.py: references/baseline.json
return os.path.join(here, "baseline.json")
def _load_baseline(path: str | None) -> dict[str, Any]:
p = path or _default_baseline_path()
with open(p, "r", encoding="utf-8") as f:
return json.load(f)
def _resolve_genre_cells(
baseline: dict[str, Any], genre: str
) -> tuple[dict[str, Any], str | None]:
"""Return (cells, fallback_warning_or_None).
Cells = mapping metric_key -> {"human": x, "ai": y, ...} merged across
requested genre with global_average fill for missing fields.
"""
genres = baseline.get("genres", {}) or {}
requested = genres.get(genre)
fallback = None
if requested is None:
fallback = f"baseline_genre_null:{genre}->essay"
requested = genres.get("essay") or {}
# Merge with global average for any missing keys.
g = baseline.get("global_average", {}) or {}
merged: dict[str, Any] = {}
keys = set(requested.keys()) | set(g.keys())
for k in keys:
cell = requested.get(k) or g.get(k)
if cell:
merged[k] = cell
return merged, fallback
def _z(value: float, human: float, ai: float, *, percent: bool) -> float | None:
"""Approximate z-score using (ai - human) / 2 as standard deviation.
The KatFish report only gives two means per metric; with no spread
published, we treat half the human-vs-AI gap as a one-sigma proxy.
Direction: positive z means closer to AI. percent=True converts the
measured value (0~1) to percent before subtracting human.
"""
if human is None or ai is None:
return None
val = value * 100 if percent else value
sd = abs(ai - human) / 2.0
if sd == 0:
return 0.0
return (val - human) / sd
def _classify_risk(z_scores: dict[str, float | None], lexicon_hits: dict[str, int]) -> tuple[str, int]:
"""오탐 방지 원칙(ai-tell-taxonomy)의 판정기 구현.
쉼표(C-11) 계열은 필자 개인 습관 편차가 커서 단독으로는 증거가 못 된다
— 계열 기여를 3점으로 상한하고, high 는 독립 계열 2개 이상이 동시에
발화할 때만 부여한다 (Pebblous 티어다운 2026-08 반례 수용).
"""
punct = 0
for key in ("comma_inclusion_rate", "ending_comma_rate", "comma_segment_length"):
z = z_scores.get(key)
if z is not None and z > 1.0:
punct += 2
punct = min(punct, 3)
lexical = 0
ld = z_scores.get("lexical_diversity")
if ld is not None and ld < -1.0:
lexical += 1
hz = z_scores.get("hanja_nominalizer_density")
if hz is not None and hz > 1.0:
lexical += 1
rhetoric = 0
if lexicon_hits.get("conclusion_pivot_count", 0) >= 2:
rhetoric += 1
if lexicon_hits.get("safe_balance_count", 0) >= 2:
rhetoric += 1
score = punct + lexical + rhetoric
families = sum(1 for v in (punct, lexical, rhetoric) if v > 0)
if score >= 6 and families >= 2:
band = "high"
elif score >= 4:
band = "medium"
else:
band = "low"
return band, score
def _evidence_spans(text: str, lexicon: list[str]) -> list[str]:
found: list[str] = []
for w in lexicon:
if w in text:
found.append(w)
return found
# ---------------------------------------------------------------------------
# Public entry point
# ---------------------------------------------------------------------------
def compute_all(
text: str,
genre: str = "essay",
baseline_path: str | None = None,
) -> dict[str, Any]:
"""Compute all v1.6 metrics + z-scores + risk band for a single document."""
baseline = _load_baseline(baseline_path)
cells, fallback_warning = _resolve_genre_cells(baseline, genre)
lex = baseline.get("lexicons", {}) or {}
pivot_lex = lex.get("conclusion_pivot") or [
"결론적으로", "따라서", "이를 통해", "그러므로",
]
safe_lex = lex.get("safe_balance") or [
"양쪽 모두", "두 가지 모두", "장점도 있지만", "신중하게", "균형",
]
metrics: dict[str, float | int] = {
"comma_inclusion_rate": comma_inclusion_rate(text),
"comma_usage_rate": comma_usage_rate(text),
"ending_comma_rate": ending_comma_rate(text),
"comma_segment_length": comma_segment_length(text),
"conclusion_pivot_count": conclusion_pivot_count(text, pivot_lex),
"safe_balance_count": safe_balance_count(text, safe_lex),
"hanja_nominalizer_density": hanja_nominalizer_density(text),
"lexical_diversity": lexical_diversity(text),
}
# baseline cells use percent for inclusion/ending rates.
z_scores: dict[str, float | None] = {}
for key, percent in (
("comma_inclusion_rate", True),
("comma_usage_rate", False),
("ending_comma_rate", True),
("comma_segment_length", False),
):
cell = cells.get(key)
if cell:
z_scores[key] = _z(metrics[key], cell.get("human"), cell.get("ai"), percent=percent)
else:
z_scores[key] = None
# hanja_nominalizer_density baseline: report says 12 occurrences per doc
# = S2 strong signal. We approximate by treating density 0.06 as human
# reference and 0.12 as AI reference (rough proxy when no per-doc cells).
z_scores["hanja_nominalizer_density"] = _z(
metrics["hanja_nominalizer_density"] * 100, 6.0, 12.0, percent=False
)
# lexical_diversity has no baseline cell either; use rough 0.65 human /
# 0.55 AI from typical Korean essay corpora as a placeholder. AI tends
# to repeat tokens slightly more.
z_scores["lexical_diversity"] = _z(metrics["lexical_diversity"], 0.65, 0.55, percent=False)
lexicon_hits = {
"conclusion_pivot_count": int(metrics["conclusion_pivot_count"]),
"safe_balance_count": int(metrics["safe_balance_count"]),
}
risk_band, risk_score = _classify_risk(z_scores, lexicon_hits)
out: dict[str, Any] = {
"version": VERSION,
"genre": genre,
"char_count": len(text),
"metrics": metrics,
"z_scores": z_scores,
"risk_band": risk_band,
"risk_score": risk_score,
"evidence": {
"conclusion_pivots": _evidence_spans(text, pivot_lex),
"safe_balances": _evidence_spans(text, safe_lex),
},
}
if fallback_warning:
out["warning"] = fallback_warning
return out
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def _main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description="Humanize KR v1.6 metric runner")
parser.add_argument("--input", required=True, help="Input text file path")
parser.add_argument("--genre", default="essay", help="essay/poetry/abstract/...")
parser.add_argument("--output", default=None, help="Output JSON path (optional)")
parser.add_argument(
"--baseline", default=None, help="Override baseline JSON path"
)
args = parser.parse_args(argv)
with open(args.input, "r", encoding="utf-8") as f:
text = f.read()
result = compute_all(text, genre=args.genre, baseline_path=args.baseline)
if args.output:
os.makedirs(os.path.dirname(os.path.abspath(args.output)), exist_ok=True)
with open(args.output, "w", encoding="utf-8") as f:
json.dump(result, f, ensure_ascii=False, indent=2)
print(result["risk_band"])
return 0
if __name__ == "__main__":
sys.exit(_main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |