Most of the Japanese I write for work starts as an AI draft: proposals for small businesses, progress reports, Slack updates to people outside engineering. The facts are usually right. I still can't send them as they are, and I kept fixing the same things by hand.
So I turned those fixes into an agent skill and published it. It works with Claude Code, Codex and Cursor.
https://github.com/kojikojikojikoji/natural-japanese-writing
You don't need to read Japanese to use it. You hand the agent a Japanese text and ask it to sound less AI-written.
The problem I kept running into
For a long time I couldn't explain what was wrong. The grammar was fine. A few things that actually happened:
- A slide deck for a client still had 御社 ("your company") in six places. It's the spoken form. In writing you use 貴社, and a client notices.
- A proposal that executives would sign off on said 「稼働中の版には触れません」, roughly "we won't touch the running version". Engineers get it. The people approving the budget had no idea what it meant for them.
- A Slack update to a business team listed file names and line numbers. Nobody on that team opens the repository.
Add the bold "Label:" bullets, the "it's not X, it's Y" lines and paragraphs ending in 「重要です」 ("this is important"). Every time someone pointed one out, I added a line to my CLAUDE.md. The file kept growing and the agent followed it some days and not others.
I tried the English skills first, humanizer and avoid-ai-writing. They look for "delve", "tapestry" and em dashes. On a Japanese report they found almost nothing. So I started collecting Japanese tells from scratch.
How I approached it
Decide who's reading before fixing anything. The skill first labels the text as a business document, casual reading, or a manual. The usual trick for sounding human is to add a personal aside. In a blog post that works. In a proposal to a Japanese client it reads as careless. Without this step, you fix one problem by creating another.
Split the tells into two kinds. Japanese research and measurement posts pointed the same way. Some tells are templates: bold labels, "not X but Y", opening with 「本記事では〜について解説します」 ("In this article, I will explain…") and closing with 「いかがでしたか」 ("How was it?"). Those can be found and deleted. The other kind is evenness: sentence length, sentence endings, paragraph length and comma spacing are all about the same. Human Japanese is lumpier. You can't fix that one phrase at a time, so the skill rewrites the whole paragraph.
Don't convict on one tell. People pick up AI phrasing too, and some "AI phrases" are just normal Japanese. There are 59 tells across six layers. The 25 clearest ones are starred and fixed on sight. The rest are fixed only when three or more different ones land in the same paragraph.
Count what can be counted. An agent reading a checklist misses tells in its own output. So bold text, em dashes, "not X but Y", stock words, repeated endings and sentence-length variance are counted by scripts/check.py (plain Python, no dependencies). After rewriting, the skill runs it again and only returns the text once the starred tells it can count are gone.
What it does to a real draft
I asked a model for a Slack message telling my manager a project is two weeks behind. It returned this (English gloss in brackets):
お疲れ様です。○○プロジェクトについて、進捗が当初のスケジュールから 2 週間遅延 しています。主な要因は以下の通りです。
- 要件定義の変更 が多数発生し、再設計に時間を要したこと。
- 外部ベンダーの納品遅延 に伴う依存タスクの遅れ。
- リソース不足（開発メンバーの一時的な兼任業務）
現在、遅延分の取り戻しに向けて、次の対策を実施中です。
- 余裕のあるタスクを再割り当てし、重点的にリソースを集約。
- ベンダーと納期再調整を実施し、今後のリスクを低減。
- 進捗管理を週次ミーティングで細分化し、早期検知体制を強化。
つきましては、新たなマイルストーン案（○月○日 完了予定）をご提示いたしますので、ご確認いただけますと幸いです。ご質問やご要望がございましたら、遠慮なくお知らせください。
[The project is 2 weeks delayed. Main factors: 1. Requirement changes … 2. Vendor delivery delay … 3. Resource shortage … Countermeasures: reallocate tasks, re-negotiate with the vendor, strengthen early detection. We hereby present a new milestone proposal and would be grateful for your review. Please do not hesitate to contact us with any questions.]
Five bold phrases in a Slack message to your own manager, bullet points written like slide notes, and a sign-off copied from a customer-service template. After the skill:
お疲れ様です。○○プロジェクトが当初の予定から2週間遅れています。
要件の変更が続いて再設計に時間がかかったことと、外部ベンダーの納品が遅れ、それを待つ作業も遅れたことが主な原因です。開発メンバーの一部は別の業務を兼任していて、人手も足りていませんでした。
今は日程に余裕のある作業から人を外して遅れている作業に回し、ベンダーとは納期を調整し直しています。今後の遅れに早く気づけるよう、毎週の定例会議で進捗を細かく確認するようにしました。
完了予定を○月○日に見直す案をお送りしますので、ご確認をお願いします。
[The project is two weeks behind. Mostly because requirements kept changing and the redesign took time, and because a vendor delivered late, which held up the work that depended on it. Some of the team were also covering other jobs, so we were short-handed. We've moved people off tasks with slack in the schedule onto the late work, and re-agreed the dates with the vendor. To catch future slips earlier, we now go through progress in more detail at the weekly meeting. I'll send a proposal to move completion to [date]. Could you take a look?]
Same delay, same causes, same countermeasures, same request for a new date. Nothing was added. check.py counted six starred tells before and none after.
How you ask changes the fix:
- "Rewrite this for the business team": file names and table names become "who is affected and how".
- "Make this read like a blog post": the writer's doubts and asides stay in.
- Load it before writing: the agent writes to the standard from the start. In my own use that's quicker than fixing afterwards.
Did the tells hold up?
I compared 40 human texts (Slack replies from 14 people) with 40 AI texts (15 everyday prompts such as reports, emails and articles; 15 texts each from Gemini 3.1 Pro and GPT-OSS 120B, 10 from Claude Sonnet 4.6). For each metric I computed the AUC, the chance that a random AI text scores higher than a random human one. 0.5 is a coin flip. Sentence-length variance is lower in AI text, so that row is flipped to read the same way.
| Metric | AUC |
|---|---|
| Starred tells, total | 0.91 |
| Bold text | 0.89 |
| Sentence-length variance (lower in AI) | 0.69 |
| Commas per sentence | 0.65 |
| Em dashes | 0.51 |
Some guesses were wrong. The em dash (—), the best-known English tell, barely showed up in Japanese from these three models. And two phrases usually filed under machine-like translationese, 「に関して」 ("regarding") and 「〜することができます」 ("is able to"), were used more by the humans, so I took them off the starred list. The human side is all Slack, which doesn't match the AI prompts and where people rarely use bold, so that number is probably inflated. Details are in eval/README.md.
Install
Claude Code:
mkdir -p ~/.claude/skills
git clone https://github.com/kojikojikojikoji/natural-japanese-writing ~/.claude/skills/natural-japanese-writing
-
Cursor reads
~/.claude/skills/too, so that's all. -
Codex reads
~/.agents/skills/:mkdir -p ~/.agents/skills && ln -s ~/.claude/skills/natural-japanese-writing ~/.agents/skills/
Then ask: "Make this Japanese sound less AI-written."
It's MIT-licensed. If you find a tell I missed, or Japanese text that slipped past it, please open an issue. I add a line every time someone points one out to me.
Top comments (0)