What is coji/natural-japanese?

The project is a Claude Code Agent Skill for writing and revising business Japanese, combining a twelve-article style constitution with sudachipy-based linting. It is aimed at anyone who has to hand over meeting minutes, reports or internal guides that currently read like a language model wrote them.

Can I use coji/natural-japanese commercially?

Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.

Is coji/natural-japanese still maintained?

Yes. The repository last received commits 12 days ago.

What programming language is coji/natural-japanese written in?

Mainly Python, according to GitHub's language statistics.

coji/natural-japanese: Agent Skill for clear Japanese

At a glance

What is it?: The project is a Claude Code Agent Skill for writing and revising business Japanese, combining a twelve-article style constitution with sudachipy-based linting. It is aimed at anyone who has to hand over meeting minutes, reports or internal guides that currently read like a language model wrote them.
Who is it for?: Adopt it if your team already runs Claude Code, Cursor or another agent that reads AGENTS.md, and if the documents you produce are Japanese meeting minutes, reports or internal guides. Skip it if your writing is English, if you want a deterministic formatter that rewrites text without an agent in the loop, or if you cannot accept that the lint output is a list of suspects rather than a fix list.
Can I use it commercially?: Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?: Yes. The repository last received commits 12 days ago.
What is it written in?: Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.

DEEP OPEN-SOURCE ANALYSIS

Hysen Labs Editorial · September 15, 2026 · coji/natural-japanese

The problem: Japanese business text that carries an AI accent

The README opens with a specific complaint. When you ask an AI to write a work document in Japanese, the result keeps a distinctive smell. Headings do not say what the section contains, every paragraph runs to a similar length, and the piece closes on a conclusion safe enough to mean nothing. The author compares fixing this afterwards to removing salt from a dish once it is cooked: asking the model to "make it more natural" just swaps one stock phrase for another, because the model cannot see its own habits.

That framing sets the audience. This is not a general Japanese learning tool and not a grammar checker for learners. It targets people who already write Japanese professionally and need meeting minutes, research reports, internal guides, proposals and blog posts to survive being read by colleagues. The repository description says as much: it is an Agent Skill for writing and correcting work Japanese so that it reads clearly.

Prevention before correction: the skeleton and the twelve-article constitution

The design splits the job in two, and the split is the interesting part. Before drafting, the skill fixes the heading skeleton and applies a twelve-article writing constitution as a constraint. Rules such as "write from the conclusion" and "do not repeat the same pattern" are meant to keep the draft from drifting in the first place. The constitution lives at skills/natural-japanese/references/writing-constitution.md.

What remains is handled by detection. A script, skills/natural-japanese/scripts/lint.py, uses morphological analysis through sudachipy to mechanically surface stock phrases, monotonous sentence rhythm and translationese from English. The README is careful about what this means: the machine points at suspects, and a human or the agent decides what to change and what to deliberately keep. Wholesale replacement of every flagged phrase is described as a way to lose nuance, not a fix.

The README also reports a limit found through corpus verification across more than 180 comparisons: word order and comma placement, the parts that make text hard to read in the first place, resist mechanical judgement. For those, the project points to visual review against a rule catalogue and an auxiliary reading-load check.

Installing the skill and scoring your first document

The README gives four installation routes. The recommended one uses the skills CLI, which places the skill in the agent configuration directory used by Claude Code and similar tools.

bash

npx skills add coji/natural-japanese

For Cursor, ChatGPT or Codex, the project documents the openskills route instead. The second command syncs the skill so it becomes reachable through AGENTS.md.

bash

npx openskills install coji/natural-japanese
npx openskills sync

Claude Code users can add it as a plugin, and there is a manual path that downloads natural-japanese.skill from the Releases page and unpacks it into the agent's skill directory.

code

/plugin marketplace add coji/natural-japanese
/plugin install natural-japanese@natural-japanese

Once installed, the skill is invoked automatically inside ordinary requests: drafting or proofreading minutes, reports, guides and proposals, or instructions like "make this readable" and "fix unnatural phrasing". To measure a document without changing it, the README documents a score command that reports a naturalness value from 0 to 100.

code

/natural-japanese score path/to/document.md

The scripts also run standalone, without the skill layer, provided uv is available. The README notes that dependencies are declared inside the scripts and resolved by uv at run time.

bash

brew install uv
uv run skills/natural-japanese/scripts/lint.py path/to/draft.md
uv run skills/natural-japanese/scripts/lint.py path/to/draft.md --genre tech
uv run skills/natural-japanese/scripts/lint.py path/to/draft.md --reading-load
uv run skills/natural-japanese/scripts/outline.py path/to/draft.md
uv run skills/natural-japanese/scripts/terms.py path/to/draft.md

The genre flag is documented as a way to suppress false positives, and outline.py extracts headings and paragraph-opening sentences while terms.py checks technical terms against first-use explanations.

What the lint output will not do for you

The honest limitation is stated in the README rather than buried. Mechanical replacement of every flagged phrase degrades the text, so the project deliberately stops short of auto-fixing. If you want a tool that takes a draft and returns a corrected draft with no judgement in between, this is the wrong shape. The lint script hands you a list and expects someone to sort it.

The second limit comes from the project's own corpus work. Word order and comma placement are described as hard to judge mechanically, which means the reading-load check and the rule catalogue are aids for a human pass, not a verdict. A team that reads a clean lint run as proof of good writing will be misled.

There is also a practical dependency question. The standalone scripts need uv installed, and the agent integration assumes a host that supports Agent Skills, whether through the skills CLI, openskills and AGENTS.md, or the Claude Code plugin marketplace. The README does not document a rollback procedure for an installed skill, so removal is not covered.

How it differs from meiseki and from plain style guides

The README credits meiseki (bamboo-nova) as an influence, specifically for combining mechanical detection with LLM revision and for organising reading-load concerns. The difference in approach is where the constraint sits. meiseki is described in the credits as an approach the author drew on; natural-japanese packages the constraint as an Agent Skill with a writing constitution applied before drafting, plus document-type templates under references/doctypes/ for minutes, reports and guides.

A plain style guide, by contrast, has no executable half. Here the rules are split between prose references the agent reads and Python scripts you can run in a terminal. That makes the project testable: the repository ships a fixture regression check, and contributors are told to point git at .githooks and run ./dev/check-fixtures.sh after changing scripts or fixtures. A static guide cannot offer that.

Maintenance, licence and what upgrades cost

The repository is not archived, and the last push was on 2026-09-04. Release v1.5.0 is dated 2026-09-04, following v1.3.0 on 2026-07-22 and v1.2.0 on 2026-07-13, so the cadence over the visible window is a few weeks between tagged releases. The README points to a visual release note for v1.5.0 that contains long-form before-and-after comparisons, including a meeting-abolition memo and a Redis-to-KV migration memo, for readers who want to judge output quality before installing.

The licence is MIT, declared in the README badge and the LICENSE file. For most internal use that is permissive, but the usual caveat applies: if you redistribute the skill inside a product, read the licence text rather than this summary, and note that the repository carries a corpus directory whose contents the README does not describe.

Upgrade cost is low in the normal case, since installation is a CLI command or a plugin install. The real cost sits in the fixture check for anyone modifying scripts: git config core.hooksPath .githooks followed by ./dev/check-fixtures.sh is the documented loop. The README's own credit line notes that its text was written and revised by Cursor Agent (Gemini 3.8 Flash High), which is a candid detail worth knowing when you read the README as a style sample.

Editorial conclusion

Adopt it if your team already runs Claude Code, Cursor or another agent that reads AGENTS.md, and if the documents you produce are Japanese meeting minutes, reports or internal guides. Skip it if your writing is English, if you want a deterministic formatter that rewrites text without an agent in the loop, or if you cannot accept that the lint output is a list of suspects rather than a fix list. Before rolling it out, run lint.py on one real document and read the flagged phrases yourself: the README is explicit that mechanical replacement destroys nuance, so the value depends on whether a human or agent is willing to triage each hit.

Frequently asked questions

Is this an app for learning natural Japanese?

No. The README describes coji/natural-japanese as an Agent Skill for writing and revising business Japanese documents, not a learning app. It targets minutes, reports, internal guides, proposals and blog posts.

What does natural-japanese mean in this project?

It means work Japanese that reads clearly: headings that state their content, varied sentence rhythm, and conclusions that do not lean on stock phrases. The README frames the goal as removing the distinctive smell left when an AI drafts Japanese text.

Is this natural Japanese, or does the tool just say so?

The project separates the two. A sudachipy-based script, lint.py, flags suspects mechanically, while the README states that a human or the agent decides what to change and what to keep, because replacing every flagged phrase loses nuance.

How does natural-japanese compare with an ordinary Japanese style guide?

A style guide is prose only. Here the twelve-article writing constitution and document-type templates are paired with runnable scripts, and the repository ships a fixture regression check that contributors run with ./dev/check-fixtures.sh.

Official sources

Community notes