← Work

Nihongo

An agent skill that brings AI-written Japanese closer to how people write

Period
2026.11–
Users
Public on GitHub
Role
Direction, some of the rules, and what to adopt (AI wrote the code and ran the tests)
Status
Live

Over 200 stars on GitHub

Nihongo のトップ画像

Tools used

01

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.

02

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
VersionWhat changed
1.0.0First public release
1.4.01.3.0 broke the meaning of ad copy by dropping words like "dramatically", so I added a rule to keep emphasis and explanations of how things work
2.0.0Split into a short Lite read every time and a detailed Full
2.2.0It was cutting too much: a 300-character essay came out at 70–180. I redefined Lite as polishing and Full as structuring
2.3.0Added Personal, which builds a style memo from your own writing. When a message to a store manager came out too casual, I put the judgment of the situation above the memo
03

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.

1InstallOne line: npx skills add
2Everyday repliesLite always applies
3Writing for othersFull is read to structure it
4After editingA script checks it against the original

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.

LitePlaced in settings such as CLAUDE.md, it is read every time, including small talk and everyday replies. About 2,700 characters.
PersonalApplies only to text sent under your own name, inside Lite's judgment of the situation. It does not loosen the tone toward seniors, shops or public notices.
Requests for emails, notices, applications, READMEs or documents
FullReads SKILL.md and the references, and lines up the purpose, the reader and the required items before writing.

After editing, check against the original and restore

Meaning changes that wording rules could not stop are stopped by a program.

  1. Original
  2. AI edits
  3. Edited text
  4. check_meaning.pyCompares numbers, negation, certainty, strength, and swapped owners or times
  5. revert_broken.pyRestores only the broken sentences to the original
  6. SmoothAdjusts only the restored sentences to fit
  7. Done

Edits the request asked for (hiding a number, changing a time) are not restored.

04

Examples

Same request, side by side

RequestFix the following Slack post, written by AI, with Nihongo.

Original post written by AI

@channel お疲れさまです! 本日のデプロイについて共有させていただきます🚀 結論:本日18時のリリースは予定どおり実施します。 背景:昨日発見された決済画面の不具合は、すでに修正済みであり、ステージング環境での検証も完了しております。 お願い:18時〜18時30分の間は、本番環境への変更を控えていただけますと幸いです。 ご不明点等ございましたら、お気軽にスレッドにてお知らせください!引き続きよろしくお願いいたします🙏

Nihongo 1.0.0

@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.

Without the skill

今後は、機器の点検を強化するなど、再発防止に努めてまいります。

Nihongo Full

件名:【お詫び】受注管理システムの接続障害について(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.

Without the skill

私の強みは、困難な場面でも諦めずに粘り強く取り組める点です。 大学でテニスサークルの運営に携わった際、新入生の定着率が低く、一年目は入会者の半数が活動に来なくなるという課題がありました。私は原因を探るため、辞めた人や参加が減った人一人ひとりに話を聞きました。すると、初心者が上級者の中で気後れしていることが分かりました。 そこで、初心者向けの練習日を設けることを提案しました。当初は「手間がかかる」と反対されましたが、具体的な運営案を作り、週ごとに参加者の声を集めて改善を重ねながら、何度も説明を続けました。その結果、三か月後に開始が認められ、翌年度の定着率は約半数から約八割に向上しました。 この経験から、すぐに結果が出なくても、原因を見極めて工夫を続けることの大切さを学びました。入社後も、粘り強く課題に向き合い、成果につなげていきます。 (※サークルの話は仮の例です。実際の経験と数字に差し替えてください。経験を教えてもらえれば、それに合わせて書き直します。)

Nihongo Lite

粘り強さを裏づける経験がまだ分からないので、書く前に教えてください。メモ書きで大丈夫です。 ・何に取り組んだか(部活、バイト、ゼミなど) ・どんな壁があって、そこでどう続けたか ・その結果どうなったか(数字があれば) もらった内容で、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.)

Without the skill

明日のシフトについて相談です。 田中さんが急に来られなくなったので、代わりに入れる人はいませんか? 時間は17時~22時です。 入れる方も入れない方も、今日の21時までに返信をお願いします。 入れない場合は、スタンプだけでも大丈夫です! 急なお願いで申し訳ないですが、よろしくお願いします。

Nihongo Lite+Full

明日のシフトなんだけど、田中さんが急に来れなくなったので、代わりに入れる人いないかな?急なお願いでごめんなさい。 時間: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.

Without the skill

みさき、お誕生日おめでとう!🎂 社会人1年目、毎日いっぱいいっぱいだと思うけど、本当によくがんばってるね。 今日は自分をいっぱい甘やかしてね。 また近いうちにごはん行こう!素敵な1年になりますように✨

Nihongo Lite

みさき、誕生日おめでとう! 社会人になって初めての誕生日だね 慣れないことも多いと思うけど、無理しすぎないでね

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.

05

Testing

Every change is compared blind

Only changes that win the comparison go in, not ones that feel better.

  1. 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.

  2. 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.

  3. 03

    The judge gets a list of points that must not change. Any draft that breaks one loses, however readable it is.

  4. 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.

Checked3-line instructionsNihongo
Made-up content in emails5 (in 5 of 6)0
Application with no contentA template full of blanksAsked for the experience all 3 times
Text with nothing to fixHeavily rewritten, with polite forms mixed into casual speechReturned unchanged all 3 times
Naturalness (average out of 5)3.894.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. 1.4.0Fewer meaning changes4 → 1 (10 technical documents × 2, vs 1.3.0)
  2. 2.0.0Added Lite, which applies to everyday replies too13 wins, 2 losses against another public skill on 15 tasks
  3. 2.3.0No more made-up content in 300-character essaysFull: 6/18 → 0/18 (vs 2.2.0)
  4. 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)
  5. 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.

Before (without the written-style rules)

本の感想を書くと、似た本を3冊すすめるWebアプリです。 感想を書くと、似た本が画面に出ます。すすめる理由は1行で、書名と一緒に表示します。長い説明は読まれないので、理由は1行と書名だけにしました。 読み込みが遅い時は、先に書名だけを出し、理由はあとから出すようにしています。

After (2.3.1)

本の感想を書くと、似た本を3冊すすめるWebアプリです。感想を入力すると、似た本が画面に表示されます。 長い説明は読まれにくいため、すすめる理由は1行とし、書名とあわせて表示します。読み込みに時間がかかる場合は、先に書名のみを表示し、理由は後から表示するようにしました。

06

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.
07

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.

Lesson

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)

LinksGitHub ↗Changelog ↗Test records ↗

Other work