Remove AI Traces from Japanese with yomiyasu: Installation, Rewriting, and Automated Checking Guide

What Is yomiyasu?

yomiyasu (よみやす) is a Japanese proofreading skill for AI coding environments. It corrects unnatural expressions in AI-generated Japanese and rewrites drafts into articles that are easier to read and denser in information.

The project can be loaded into environments such as Codex, Claude Code, and Cursor. Rather than simply replacing a few words that tend to make text appear "AI-generated," it adjusts subject-verb relationships, the agents performing actions, rhetorical techniques, and information structure.

The project was created through individual research and creative work and is released under the MIT License. For its design background and corpus validation process, see the project overview article.

Japanese Writing Problems It Addresses

Generic style prompts often only ban words such as “解像度” (resolution), “手触り” (texture), and “泥臭い” (hands-on). The model may replace them with other vague words while leaving the underlying syntactic problems untouched. Too many editing rules can also lead the model to invent words or use exaggerated expressions.

yomiyasu primarily addresses the following issues:

• Failing to clearly state who performed which operation.
• Using ambiguous demonstrative pronouns such as “これ” (this), “両者” (both parties), and “片方” (one side).
• Using concepts or tools as anthropomorphized subjects.
• Using vague metaphorical verbs such as “壊れる” (break), “倒す” (take down), “効く” (work), “溶かす” (melt), and “潰す” (crush).
• Stacking bold text, lists, and formulaic openings while omitting actual steps and operating mechanisms.
• Adding subjects, specifications, disclaimers, or general conclusions that were not present in the source text.

Seven Core Conversion Principles

1. Restore a complete SVOCM structure: Clearly identify the agent of an action, such as a developer, user, or system, and replace ambiguous pronouns with specific nouns.
2. Distinguish the agent from the purpose of the expression: Use clear requests for reader-directed requirements, and explain exactly what the system can do in feature descriptions.
3. Break down inanimate subjects: Rewrite anthropomorphic descriptions as objective operations performed by a person or system.
4. Turn metaphorical verbs into technical operations: Directly describe states such as processing, skipping, terminating, reducing, or becoming inconsistent.
5. Remove unnecessary preambles: Omit clichés such as “what is important is,” and rewrite double negatives and rhetorical contrasts as concise affirmative sentences.
6. Preserve the original meaning: Retain numerical values and technical constraints without adding facts absent from the draft.
7. Control sentence length and decoration: Use an average of 30 to 45 Japanese characters per sentence as a guideline, limit commas to 0 to 2 per sentence, and reduce emojis, colons at the end of sentences, bold text, and unnecessary half-width spaces.

Installing yomiyasu

Method 1: Use skills add

This is the installation method recommended in the README. After running the following command, the tool installs the skill in the configuration directory used by agents such as Claude Code:

npx skills add nanaism/yomiyasu

Method 2: Use with Cursor or Codex

You can install and synchronize the skill with OpenSkills:

npx openskills install nanaism/yomiyasu
npx openskills sync

After synchronization, each agent can use the skill through AGENTS.md.

Method 3: Install the Claude Code plugin

Run the following commands in Claude Code:

/plugin marketplace add nanaism/yomiyasu
/plugin install yomiyasu@yomiyasu

Method 4: Place it manually

Download yomiyasu.skill from GitHub Releases, extract it, and place it in the skill directory used by your agent.

If other Japanese proofreading or style-adjustment skills are enabled in the same environment, their instructions may interfere with each other. When using yomiyasu, temporarily disable skills with similar functionality.

Basic Usage

After installation, paste a Japanese draft into an AI chat interface or coding agent and provide a simple proofreading request:

Make this text easier to read.
(Paste the text you want to revise here)

If no purpose is specified, yomiyasu automatically determines the appropriate domain from the input. It tries to preserve the facts, numbers, and technical constraints in the draft while correcting subject-predicate relationships, abstract expressions, and excessive decoration.

A Simplified Example

Suppose the original text uses the following expression:

DBの負荷を逃がし、失敗したメッセージを潰していきます。

You can ask yomiyasu to replace the metaphor with specific operations. Following the project's editing principles, the rewrite should explain how the system reduces load and how failed messages are handled, such as by extending the retry wait time and moving data that exceeds the prescribed retry count to a dead-letter queue. The actual output depends on the full context and cannot add specifications absent from the original based only on a single sentence.

Specify a Style by Purpose

For more consistent results, specify a domain in the prompt. The project provides three guidance categories: tech, business, and essay.

Technical Articles: tech

This mode is suitable for technical blogs and code explanations. It prioritizes restoring operational steps and implementation mechanisms while suppressing unnecessary lists.

Make this text easier to read for a technical article.
(Paste the text you want to revise here)

You can also state the domain explicitly:

Domain: tech
Make this text easier to read.
(Paste the text you want to revise here)

Business Documents: business

This mode is suitable for specifications, public relations materials, and proposals. It focuses on removing metaphors and clarifying boundary conditions and responsible parties.

Domain: business
Make this text easier to read for a business specification.
(Paste the text you want to revise here)

Essays: essay

This mode is suitable for personal blogs and note articles. It avoids exaggerating ordinary experiences into lessons while preserving natural feelings and personal experiences.

Domain: essay
Make this text easier to read as an essay.
(Paste the text you want to revise here)

Quantify AI Traces with the Built-in Checker

The repository includes scripts/yomiyasu_lint.py. This script checks for unnatural metaphors, excessive bold text or lists, emojis, colons at the ends of sentences, and repeated identical sentence endings.

The checker only depends on the Python standard library and requires no additional third-party packages. To check a Markdown file, run:

python3 scripts/yomiyasu_lint.py README.md

The report displays the total score, character count, line count, bold-text count per thousand characters, list ratio, and other information. If no rules are triggered, the result is PASS.

Enable Strict Mode in CI or a Git Hook

After adding --strict, the script returns exit code 1 whenever a warning exists:

python3 scripts/yomiyasu_lint.py article.md --strict

You can therefore add this command to a continuous integration workflow or pre-commit Git Hook to prevent articles with obvious style problems from proceeding to later stages.

Advanced Usage Recommendations

Finalize the Content Before Proofreading

yomiyasu is designed to adjust expression, not replace fact-checking. Before providing input, verify the parameters, constraints, and technical conclusions in the draft. This allows its meaning-preservation principle to work effectively and reduces the risk of factual deviations during proofreading.

Specify the Reader and Purpose in the Prompt

In addition to the domain name, retain necessary context in the draft, such as whether the article is intended for developers or business users. The project explicitly supports three domain modes, so do not assume that it includes other specialized modes not mentioned in the README.

Combine Manual Review with lint

The checker identifies formal issues covered by its predefined rules and cannot replace human judgment. The recommended process is to have the agent rewrite the text, run yomiyasu_lint.py, and then manually verify the technical facts, tone, and original author's style.

Understand the Sources of the Repository Rules

The core skill entry point is SKILL.md. The syntax conversion principles, catalog of unnatural vocabulary and structures, and domain rules are located in the references directory. Comparative validation data is located in evals/comparison_benchmark.md. When researching or adjusting the skill's behavior, start by reading these files.

Conclusion

yomiyasu shifts the focus of Japanese proofreading from banning individual popular words to sentence structure, subject relationships, technical operations, and information density. With suitable domain prompts, manual review, and the built-in lint tool, you can establish an AI-assisted Japanese editing workflow for technical articles, business documents, and essays.