yomiyasu: The Linter That Treats AI Japanese Like Code

A deep look at a zero-dependency Agent Skill that catches AI slop, restores missing subjects, and rewrites Japanese without losing intent.

8 min read • View on GitHub • More from nanaism

A Japanese manuscript passes through a mechanical inspection rig, with a cluttered page on the left and a cleaned-up page on the right. The image explains that yomiyasu treats AI writing as something to lint and repair, not simply prettify. — The project’s thesis in one frame: inspect the prose, keep the meaning, and remove the AI smell without turning editing into guesswork.

Key Takeaways

yomiyasu treats AI Japanese as a semantic maintenance problem, not a taste contest.
Its core promise is meaning preservation, with stance and certainty checked before style changes land.
The tool is narrow by design, using deterministic linting and diff checks instead of another opaque judge model.
That makes it useful where ordinary humanizers are risky: technical docs, specs, PRs, and reports.

Japanese AI text can fail in ways that feel obvious and hard to name at the same time. It gets abstract, decorates itself with tired metaphors, drops the actor from the sentence, and leaves behind a stiffness that reads like nobody actually meant what was written.

yomiyasu starts from a sharper premise: if the failure modes are predictable, the fix can be too. The repo turns prose cleanup into a deterministic workflow, with rules for stance, meaning preservation, slop detection, and semantic diffing.

Why Japanese AI text sounds wrong

The project is aimed at a very specific kind of bad output. Not grammar errors in the usual sense, but the uncanny prose that comes from large models trying too hard to sound polished while saying very little.

That matters more in Japanese than it does in many other languages. Subjects are often omitted, role relationships are implied, and a bad rewrite can quietly change who did what to whom. The result is text that looks smooth but loses its spine.

従来の「単語を禁止する手法」から改善し、統語構造(誰が何をどうした)の復元と、比喩動詞の具体化に特化しています。

Aiichiro Oga (oga_aiichiro), Author/Maintainer · 大賀愛一郎 (oga_aiichiro) on X

What yomiyasu actually does

The repo is not a generic grammar checker and not a full creative rewrite engine. It is a skill for refining AI-generated Japanese into prose that reads naturally in technical docs, design specs, PRs, and reports.

Its structure makes that scope visible. The repository centers on a skill definition in SKILL.md, supported by Python scripts for linting and diff checks, plus a corpus of test texts and domain-specific references.

skills/yomiyasu/
  SKILL.md
scripts/
  yomiyasu_lint.py
  yomiyasu_diff.py
tests/corpus/
references/

The zero-dependency choice matters. The scripts stick to the Python standard library, which makes the project portable enough to slot into CI, editor workflows, or agent environments without pulling in a larger stack.

Meaning preservation is the real feature

The most important idea in the repo is not surface cleanup. It is the contract that the rewrite must preserve four things: assertion, weight, certainty, and function.

That turns editing into a checkable semantic task. A sentence can become shorter, clearer, or less awkward, but it should not silently change from a recommendation into a rule, or from a cautious explanation into a confident directive.

The semantic center of the project: yomiyasu rewrites for readability only after checking that the sentence still means the same thing.

A close-up of a Japanese sentence under a magnifying glass, surrounded by four semantic labels and a flagged ribbon. The image explains that yomiyasu checks stance and meaning before it edits style. — The hidden job is not deleting bad words. It is making sure the rewritten line still carries the same editorial function as the original.

How the linter spots AI slop

yomiyasu_lint.py behaves like a static analyzer for prose. It does not pretend to understand everything. It watches for patterns that repeatedly show up in AI writing and flags them with deterministic heuristics.

The signals are specific. Slop words get caught. Over-decoration gets measured. Negative parallelism, front-loaded fillers, and repetitive sentence endings are treated as smells, not as absolute errors.

Pattern	Why it flags	What it means
Slop words	They often pad weak statements with fake concreteness	The sentence may sound vivid without adding information
Over-decoration	Too much bolding or list structure can mirror AI summary habits	The prose may be performing clarity instead of achieving it
Negative parallelism	Forms like "AではなくB" can become a repetitive crutch	The sentence may be leaning on contrast instead of direct explanation
Front-loaded fillers	Openers like "結論から言うと" can announce certainty before substance	The sentence may be rehearsed rather than earned
Monotonous endings	Repeated sentence endings flatten rhythm	The prose starts to sound machine-made

That makes the linter feel less like a style coach and more like a customs officer. It inspects the surface for telltale baggage, then leaves the bigger semantic call to the rewrite and diff steps.

AI生成の日本語を自然な日本語へ推敲するAgent Skill / Agent Skill for Refining AI-Generated Japanese into Natural Japanese

Aiichiro Oga (oga_aiichiro), Author/Maintainer · nanaism/yomiyasu GitHub Repository

Why the diff step matters

The second guardrail is yomiyasu_diff.py. If the linter is the scanner, the diff step is the safety review that asks whether the rewrite changed the job the sentence was doing.

It tracks markers and logic transitions so the tool can notice when a rewrite has quietly lost obligation, softened certainty, or invented a transition that was never there. That is the part many humanizers miss.

This is where the project feels genuinely engineering-led. It assumes that prose cleanup can introduce bugs, and it treats those bugs like bugs.

Why this beats generic humanizers

The comparison is not really about features. It is about editorial intent.

Tool	Primary goal	What it catches	What it misses	Why it matters
textlint	Rule-based Japanese cleanup	Surface issues and configurable style violations	Semantic drift and stance errors	Useful, but mostly textual rather than intent-aware
Generic humanizer	Make text read more naturally	Fluency problems and awkward phrasing	Whether the rewrite still means the same thing	Can improve polish while blurring meaning
yomiyasu	Refine AI Japanese without losing intent	AI slop, missing subjects, stance shifts, semantic drift	Open-ended creative rewriting	Targets the exact failure mode of machine-written Japanese

That narrowness is the selling point. yomiyasu is not trying to become the everything tool. It is trying to be the right tool for a very specific class of Japanese prose that needs both cleanup and trust.

The project’s real bet

The larger idea is simple and strong. Some of the best AI writing tools will not look like chat interfaces at all. They will look like linters, diff viewers, and semantic guardrails.

yomiyasu makes that argument concrete in Japanese. It encodes editorial judgment as a reproducible system, which is a more durable idea than asking another model to vaguely improve another model.

That is why the project resonates. It does not promise magic. It promises a workflow that can be inspected, tuned, and trusted.