Rewrite AI-Generated Japanese into Readable Prose with yomiyasu

AI-generated Japanese has a recognizable smell: metaphorical verbs like 壊れる (break) attached to tools and concepts, missing subjects, bold everywhere, bullet lists where prose belongs. yomiyasu, a 3k-star MIT agent skill by Aiichiro Oga of ALGO ARTIS, is built to fix exactly that, leaving what already reads naturally alone.

Why This Skill Matters

Per the README, yomiyasu (よみやす, "easy to read") rewrites AI-generated Japanese prose to make it easier to read. It fixes unnatural metaphors, unclear subjects and predicates, tools and ideas written as if they had feelings or a will, filler phrases, and decoration such as heavy bold, bullet lists, emoji, and trailing colons. Parts that already read naturally are left alone. It works on Japanese text only, and its instructions, check output, and reports are in Japanese.

The meaning is the hard constraint: numbers, negations, conditions, who does what, and how strongly a claim is made must survive. It does not add facts that are not in the original or in the material you provide, and where the meaning cannot be decided from the text, it keeps the original wording and asks the writer instead of guessing. The Japanese README documents seven transformation principles — from checking subject-predicate pairing and conditions to keeping average sentence length between 30 and 45 characters with 0 to 2 commas per sentence. It is designed for practical writing — technical articles, design documents and specifications, pull request descriptions, internal reports — and it knows thirteen document types, including mail, minutes, slides, papers, essays, fiction, and scripts, leaving each type's usual style alone.

Installation

# skills CLI (recommended)
npx skills add nanaism/yomiyasu

# GitHub CLI
gh skill install nanaism/yomiyasu yomiyasu

# openskills (through AGENTS.md)
npx openskills install nanaism/yomiyasu
npx openskills sync

As a Claude Code plugin, run these two commands in Claude Code; the README notes the skill is then named yomiyasu:yomiyasu and that a user reported plain yomiyasu gave "Unknown skill":

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

For Claude.ai (web), upload the yomiyasu.zip from the latest release as it is, without unpacking — the ZIP GitHub's "Download ZIP" button makes contains the whole repository and may be rejected. For Codex, copy the skills/yomiyasu/ folder into .agents/skills/yomiyasu/. The README also publishes two smaller variants for hosts that cannot load the full skill: yomiyasu-mini keeps its SKILL.md within 18,000 characters for hosts with size limits such as Microsoft 365 Copilot declarative agents, and yomiyasu-pocket is a 400 to 500 character instruction with no bundled checks.

Real Workflow: Polishing a Technical Draft

1. Name yomiyasu in the request and paste the draft. The README's example request:

この文章を yomiyasu で読みやすくして。
（ここに修正したい文章を貼り付け）

2. Optionally state the document type, how much the readers know, and who writes to whom — the README gives 「取引先に送るメールです」 (an email to a client) as an example. With the relationship given, yomiyasu adjusts the politeness level the way a person in that relationship would write; say nothing and it infers the type when it can and does not change the politeness.
3. Sending only /yomiyasu makes it rewrite the text the AI wrote in its previous answer, or the single draft (.md or .txt) directly under the working folder. When it works on a file, it does not overwrite it and saves the final draft in the same folder under a new name.
4. After the rewritten text, it reports what it changed and the record of the checks it ran, and, when there is something to say, the AI-like wording it chose to keep and questions for the writer. Ask for 「本文だけ」 (the text only) to get the rewritten text alone; the checks still run.

Since 2.0.2, agents use yomiyasu only when you ask for it — the request names it, you send /yomiyasu, or you clearly ask for the Japanese proofreading skill. To have it apply to every Japanese rewrite, the Japanese README documents the line to paste into your CLAUDE.md or AGENTS.md.

The Bundled Checks

Since 2.0.0, yomiyasu runs bundled checks on its final draft before returning it, so changed numbers, negations, or swapped subjects and objects show up as items to review. The skill ships four Python scripts that need only the standard library and are tested on Python 3.9 and 3.14:

python3 scripts/yomiyasu_lint.py article.md
python3 scripts/yomiyasu_lint.py article.md --fail-on warn   # exit code 1 if there are warn or error items
python3 scripts/yomiyasu_diff.py original.md rewritten.md
python3 scripts/yomiyasu_check.py run --source original.md --final final.md
python3 scripts/yomiyasu_check.py verify --final final.md

yomiyasu_lint.py lists expressions and Markdown formatting worth reviewing, line by line; yomiyasu_diff.py puts edits that may change the meaning first; yomiyasu_check.py runs lint plus diff and keeps a record in .yomiyasu/ at the top of the repository; yomiyasu_hook.py is an optional hook for Claude Code and Codex that runs only if you add it to your own settings. The scripts only report items to review and the places that changed — they do not judge whether the meaning was kept. A project word list in .yomiyasu-words/ (allow.txt, flag.txt) removes wrong marks and adds project-specific words.

Tips

• Do not edit files inside the installed skill folder: the README warns some install methods replace the whole folder on update and your edits are not kept. Put project words in .yomiyasu-words/ and your own instructions in CLAUDE.md or AGENTS.md.
• The lint --json score key is rule_penalty_score (score up to 1.1.2) — the README points at docs/tools.md for jq examples when reading older JSON.
• The rewriting was checked with Claude Code and Codex on macOS through their non-interactive commands (claude -p and codex exec); per the README's limits section, rewriting has not been tested in the interactive interfaces, through the plugin or CLI installs, in Codex Cloud, in Cursor, with the Claude.ai ZIP upload, or on Windows.

When Not to Use This

It works on Japanese text only — for any other language it is simply not the tool. And the README is explicit that the checks catch fixed patterns only: pages without any lint item still need to be read against the original. It is a personal project by Aiichiro Oga and, per the README, is not an official product of ALGO ARTIS and does not represent its views.

See the leaderboard for more skills.