Nihongo
An agent skill that brings AI-written Japanese closer to how people write
Over 200 stars on GitHub

Tools used
- ClaudeSplitting design, implementation and testing (Sonnet writes, Opus judges)
- PythonScripts that check meaning and restore broken sentences
- GitHubPublishing, and taking issues and PRs
Problem
Skills that fix AI output after the fact already exist. I thought that if the fix happened at the moment of writing, it would also apply to everyday conversations with AI and make reading less stressful.
Observation
- Without the skill, the AI added 33 reasons and promises nobody asked for across 11 tasks prone to made-up content.
- Even in a team chat, it used labels like "Conclusion:" and heavy honorifics.
- When asked to edit, it broke the meaning by turning plans into certainties, dropping emphasis like "significantly", or cutting explanatory sentences.
- Given a length target, it filled the space with feelings and events that were not in the material.
- Looking at unnecessary commas one by one, almost all came right after a short opener such as "Now,".
- Versions that only added rule text lost to the previous version; the first one to win came with example sentences.
Without the skill, the AI added "we will work to prevent a recurrence" to an outage report, which the request never mentioned.
- 13versions in about 38 hours after release
- 92tasks used for testing
- 56tests for the scripts
Flow
I split it in two: a short Lite that loads every time, and a Full that loads only when writing something for other people. Unknown values are left blank and asked about, and a script restores any sentence whose meaning changed during editing.
Lite always applies; Full is read only when writing
It stays light day to day, and reads the detailed material only when writing something for other people.
After editing, check against the original and restore
Meaning changes that wording rules could not stop are stopped by a program.
- Original
- AI edits
- Edited text
- check_meaning.pyCompares numbers, negation, certainty, strength, and swapped owners or times
- revert_broken.pyRestores only the broken sentences to the original
- SmoothAdjusts only the restored sentences to fit
- Done
Edits the request asked for (hiding a number, changing a time) are not restored.
Examples
Same request, side by side
RequestFix the following Slack post, written by AI, with Nihongo.
@channel お疲れさまです! 本日のデプロイについて共有させていただきます🚀 結論:本日18時のリリースは予定どおり実施します。 背景:昨日発見された決済画面の不具合は、すでに修正済みであり、ステージング環境での検証も完了しております。 お願い:18時〜18時30分の間は、本番環境への変更を控えていただけますと幸いです。 ご不明点等ございましたら、お気軽にスレッドにてお知らせください!引き続きよろしくお願いいたします🙏
@channel お疲れさまです! 本日18時のリリースは予定どおり実施します🚀 昨日見つかった決済画面の不具合は修正済みで、ステージング環境での検証も完了しています。 18時〜18時30分は、本番環境への変更を控えてください。 不明点があればスレッドでお知らせください。よろしくお願いします🙏
This is the example in the README. The labels like "Conclusion:" are gone, and honorifics too heavy for a team chat became plain polite Japanese. The time and the request did not change.
RequestWrite an outage report email to an outside business partner. From 10:00 to 10:45 on November 17, the order management system was hard to connect to. The cause was a failed network device. It was replaced and service was restored.
今後は、機器の点検を強化するなど、再発防止に努めてまいります。
件名:【お詫び】受注管理システムの接続障害について(11月17日) 【取引先の会社名】 【ご担当者名】様 お世話になっております。【自社名】の【氏名】です。 11月17日に、受注管理システムへ接続しにくい状態が続きました。ご迷惑をおかけし、申し訳ございませんでした。現在は復旧しており、通常どおりご利用いただけます。 日時:11月17日 10:00〜10:45 原因はネットワーク機器の故障でした。機器を交換し、10時45分に復旧しています。 あらためてお詫び申し上げます。 【自社名】【部署名】 【氏名】
The version without the skill is an excerpt. It adds a prevention plan the request never mentioned. Nihongo leaves the recipient and signature blank.
RequestWrite a self-PR for a job application, within 400 characters. My strength is persistence.
私の強みは、困難な場面でも諦めずに粘り強く取り組める点です。 大学でテニスサークルの運営に携わった際、新入生の定着率が低く、一年目は入会者の半数が活動に来なくなるという課題がありました。私は原因を探るため、辞めた人や参加が減った人一人ひとりに話を聞きました。すると、初心者が上級者の中で気後れしていることが分かりました。 そこで、初心者向けの練習日を設けることを提案しました。当初は「手間がかかる」と反対されましたが、具体的な運営案を作り、週ごとに参加者の声を集めて改善を重ねながら、何度も説明を続けました。その結果、三か月後に開始が認められ、翌年度の定着率は約半数から約八割に向上しました。 この経験から、すぐに結果が出なくても、原因を見極めて工夫を続けることの大切さを学びました。入社後も、粘り強く課題に向き合い、成果につなげていきます。 (※サークルの話は仮の例です。実際の経験と数字に差し替えてください。経験を教えてもらえれば、それに合わせて書き直します。)
粘り強さを裏づける経験がまだ分からないので、書く前に教えてください。メモ書きで大丈夫です。 ・何に取り組んだか(部活、バイト、ゼミなど) ・どんな壁があって、そこでどう続けたか ・その結果どうなったか(数字があれば) もらった内容で、400字以内の自己PRを書きます。
Without the skill, it invented an entire tennis-club story and the figure "from about half to about 80%". Nihongo invents nothing and asks for the experience it needs.
RequestFix this message. I'm sending it to my part-time job's group LINE. (A casual message asking who can cover a shift from 17:00 to 22:00, saying a reply is "absolutely" needed by 21:00 today, with a double negative.)
明日のシフトについて相談です。 田中さんが急に来られなくなったので、代わりに入れる人はいませんか? 時間は17時~22時です。 入れる方も入れない方も、今日の21時までに返信をお願いします。 入れない場合は、スタンプだけでも大丈夫です! 急なお願いで申し訳ないですが、よろしくお願いします。
明日のシフトなんだけど、田中さんが急に来れなくなったので、代わりに入れる人いないかな?急なお願いでごめんなさい。 時間:17時〜22時 今日の21時までに絶対に返事がほしいです。入れない人も返事はほしいので、スタンプだけでも押してください。
Only the body is shown for the version without the skill (two lines explaining the edits follow it). It dropped "absolutely" and turned the group chat formal. Nihongo keeps the strength and the tone, and fixes only the double negative.
RequestI want to send a birthday message on LINE to a friend named Misaki. She started working this year.
みさき、お誕生日おめでとう!🎂 社会人1年目、毎日いっぱいいっぱいだと思うけど、本当によくがんばってるね。 今日は自分をいっぱい甘やかしてね。 また近いうちにごはん行こう!素敵な1年になりますように✨
みさき、誕生日おめでとう! 社会人になって初めての誕生日だね 慣れないことも多いと思うけど、無理しすぎないでね
Without the skill it gave three drafts with explanations; this is the first. It also adds a promise to get dinner.
Each output is copied as-is from a single test run, in the original Japanese. The same request will not always produce the same text.
Testing
Every change is compared blind
Only changes that win the comparison go in, not ones that feel better.
- 01
Each time one rule changes, the same tasks are written with the previous version. The writing AI can only read its own version of the skill.
- 02
The two texts are shuffled into X and Y and judged without knowing which version is which. The order is swapped and judged twice.
- 03
The judge gets a list of points that must not change. Any draft that breaks one loses, however readable it is.
- 04
There is a release gate: if a version scores lower than the last one or makes something up, it does not ship. Every release is checked against it.
Where a few lines of instructions fall short
Writing "don't make things up" is not enough on its own, so the skill stops it with structure.
An AI with three lines of instructions in its settings and Nihongo were compared on the same 12 tasks.
| Checked | 3-line instructions | Nihongo |
|---|---|---|
| Made-up content in emails | 5 (in 5 of 6) | 0 |
| Application with no content | A template full of blanks | Asked for the experience all 3 times |
| Text with nothing to fix | Heavily rewritten, with polite forms mixed into casual speech | Returned unchanged all 3 times |
| Naturalness (average out of 5) | 3.89 | 4.22 |
The AI without the skill made up content 12 times in emails (in all 6). Each check used 3 tasks, judged only twice. The three lines asked it to write natural Japanese for the reader and situation, keep explanations short without preambles or summaries, never add facts, reasons or promises not in the request, and leave unknown values as blanks.
What each version improved
Weaknesses found in testing are fixed in the next version, with numbers.
- 1.4.0Fewer meaning changes4 → 1 (10 technical documents × 2, vs 1.3.0)
- 2.0.0Added Lite, which applies to everyday replies too13 wins, 2 losses against another public skill on 15 tasks
- 2.3.0No more made-up content in 300-character essaysFull: 6/18 → 0/18 (vs 2.2.0)
- 2.3.0Added Personal, which brings text closer to your own style"Sounds like the person" in new situations: 10/24 (2/24 when just pasting their writing)
- 2.3.1Fewer spoken-style verbs in written documentsPer text: 19 and 28 → 3 and 2; naturalness 21 wins, 5 losses (7 tasks)
All judging was done by AI, so the numbers are a guide.
Before and after 2.3.1 (a portfolio project description, in the original Japanese)
RequestWrite a project description for a portfolio. The project is "Yomitsugi", a web app that recommends three similar books when you write a review. The reason for each is one line, shown with the title; titles appear first when loading is slow.
本の感想を書くと、似た本を3冊すすめるWebアプリです。 感想を書くと、似た本が画面に出ます。すすめる理由は1行で、書名と一緒に表示します。長い説明は読まれないので、理由は1行と書名だけにしました。 読み込みが遅い時は、先に書名だけを出し、理由はあとから出すようにしています。
本の感想を書くと、似た本を3冊すすめるWebアプリです。感想を入力すると、似た本が画面に表示されます。 長い説明は読まれにくいため、すすめる理由は1行とし、書名とあわせて表示します。読み込みに時間がかかる場合は、先に書名のみを表示し、理由は後から表示するようにしました。
Decisions
- Apply it while writing, not afterI wanted it to be different from existing skills that fix output. It can write technical documents too, but its first priority is text that Japanese speakers read naturally and without effort.
- Split it into Lite and FullI wanted it to apply to everyday replies too, without making it read the heavy procedures every time. Full is read only when writing for other people.
- Put "never make things up" firstUnknown values become blanks to ask about. Other skills and the plain AI made up prevention plans in an outage email.
- Restore broken meaning with a scriptAdding rules did not reduce meaning changes during editing. The scripts have 56 tests.
- Leave natural text alone and keep emphasisIt does not make changes that only swap notation or wording. Words like "dramatically" are the writer's choice.
- Use Personal under the judgment of the situationThe style memo once won over the situation, and a message to a store manager came out too casual.
Result & lesson
I shipped 13 versions in about 38 hours after release. It has passed 200 stars on GitHub and received 3 pull requests from outside contributors.
Publishing something comes with responsibility, and sometimes critics. It matters to listen sincerely to every opinion and keep taking it in. But when outside opinions pour in, you want to change course. I learned it also matters not to run away easily, and to keep in mind what I decided at the start and who I want to reach. I knew it already, but I felt that testing is harder, and more important, than design.
TechMarkdown (the skill itself), Python and pytest (scripts and tests)
Other work