natural-japanese
A skill for writing professional Japanese in a clear, readable, and easy-to-understand way. It covers business documents such as minutes, research reports, internal guides, research notes, and slide decks, as well as notes, blogs, and essays. Removing AI-like writing is built into the workflow as one stage.
Position within writing-skills
This Skill assumes the
foundation and is a specialized skill that adds Japanese-specific naturalness and readability, together with detection of AI-like patterns. When a judgment conflicts with the foundation—such as audience / purpose / source fidelity / reader order—
takes precedence. Use this Skill as an additional layer for Japanese expression, diagnosis, and revision.
For its upstream provenance and differences, see UPSTREAM.md.
Design philosophy
There are two axes. First, “detection is mechanical; judgment is AI.” Because AI has difficulty recognizing its own habits, a machine deterministically detects suspected issues, and the AI (you) decides in context whether to revise them. Second, “constraints at generation time are more effective than post-hoc correction.” Preventing problems through design before writing and constraints during writing is more effective than removing AI-like writing afterward. The workflow proceeds in this order: “Design → Drafting → Inspection → Convergence.”
Execution modes — Quick and Full
The same workflow can be run in two modes that differ in the amount of effort required. Observed time estimates are as follows: Quick takes about 30 seconds for a short document, such as meeting notes, and about 3 minutes even for a longer document of around 10,000 characters. Full takes about 7 minutes for a short document and 15–20 minutes for a 10,000-character document. When starting Full mode, first tell the user the estimated time in a single sentence, then begin.
Quick (default): Use this for everyday documents. It does not use subagents and is completed in the current session. The only additional file to read is the template for the applicable doctype. The style constitution summarized in §2 is sufficient; open the other references only if a lint finding leaves you uncertain about how to proceed. For design (§1), confirm the reader, main message, and headings mentally. Inspection consists of one lint pass and your own read-through of the skeleton. Do not skip lint even for a short document. In short texts, statistical detectors may remain silent, but prohibited wording and translationese can still be detected in a single sentence. It takes only a few seconds and acts as insurance; skipping it means Quick mode no longer provides its quality guarantee. End the convergence loop after one round if no new findings appear, and finish with a final read-through. The additional time attributable to the skill should remain within a few dozen seconds. If you begin loading references, you have started doing Full-mode work.
Full: Use this when the user says “thoroughly,” “properly,” or “take your time”; for external-facing or executive-level documents where the cost of failure is high; or for long documents, with around 10,000 characters as a guideline. Once Full mode has been selected—or explicitly requested by the user—do not omit any part of the process, even if the document is small. In addition to lint, run outline / terms. Always perform all three inspections in §4—structural review, readability review, and doctype matching—in parallel subagents. Each subagent returns its findings, but the parent must integrate them into the decision ledger and make every “fix/keep” decision. Do not divide the writing itself: consistency in emphasis, metaphor, and transitions between chapters can only be maintained by considering the document as a whole. Continue the convergence loop until the state conditions in §5 are satisfied. Even if you feel that a document is excessive, do not silently remove steps; propose switching to Quick mode to the user instead. In practice, runs with a low reasoning budget (effort) can easily rationalize away parts of the Full process. If the environment allows the effort level to be selected, high is recommended for Full mode; low is sufficient for Quick mode.
If you are unsure which mode to use, it is best to finish with Quick mode first and then add that it can also be polished further in Full mode.
Invocation — write / score / mode specification
When the skill is invoked as a command with arguments, interpret them in the following forms.
/natural-japanese [quick|full] <target>
/natural-japanese write [quick|full] <topic or source material>
/natural-japanese score [quick|full|exp] <file>
If no mode is specified, choose one based on the execution-mode criteria above. The same rules apply to natural-language requests: “Write about ○○” means write, while “Does this text sound AI-written?” or “Score the AI-like quality of this text” means score.
1. Design — Decide before writing
1-1. Reader, purpose, and document type
Identify who will read the document and what should happen after they read it. If either is unclear, ask the user. Once the document type has been determined, read the corresponding template:
- Minutes →
references/doctypes/minutes.md
- Research or analytical report →
references/doctypes/report.md
- Internal guide or manual →
references/doctypes/guide.md
- Research memo, discussion paper, or proposal →
references/doctypes/memo.md
- Slide structure →
references/doctypes/slide.md
This section can be skipped for document types that do not fit these templates, such as notes, blogs, and essays.
1-2. Main message and skeleton
Before writing the body, express the main message in a single sentence. If this is impossible, the problem is insufficient source material rather than writing technique (→ 1-4). Next, create a heading skeleton. Each heading should convey a message containing the conclusion, rather than a generic label such as “Background” or “Summary.” Read only the headings in order and confirm that the argument holds before proceeding to the body.
1-3. Emphasis and depth design
Writing every section with the same intensity and depth creates an unnaturally over-neat quality in itself. Design intentional variation: make important sections more substantial and keep lighter sections honestly light. For the procedure, see “Emphasis and Depth Design” in
references/revision-guide.md
.
1-4. Material gathering — Optional, for new writing
If you begin writing while lacking proper names, numbers, and concrete examples, it will be too late to fix the result if you later realize that it can only say something generic. For the procedure that alternates between reasoning and search, the criteria for determining when enough material has been gathered, and how to request material from the user in environments without Web search, see “Material Gathering” in
references/revision-guide.md
.
1-5. Style profile — Optional
If
already exists in the project root or a location specified by the user, load it and use its voice, vocabulary, and rhythmic patterns as an underlying guide. If it does not exist, proceed in generic mode. Only when the user asks you to learn their writing style, extract characteristics from three to five previous texts according to
assets/style-profile-template.md
and write a profile. Avoid overstating your conclusions; frame them as tendencies. If the user explicitly identifies particular words or combinations as ones they never use or that sound unnatural, do not generalize them into general rules. Instead, record them under the same profile’s “Expressions to Avoid,” with the source and scope of the observation. Do not ban entire words; record the specified combination as the smallest unit.
2. Writing — Write under the style constitution
Use the 12 provisions in
references/writing-constitution.md
as constraints while writing the body. The main points are as follows: lead with the conclusion and do not add a preamble; make headings convey messages; write explanations in continuous prose, using bullet points only to compress genuinely parallel items; explain technical terms within the text in the order of function → name; ground the text with proper names and numbers; use bold text only once, at the core point of a passage; vary emphasis and depth; do not repeat the same template three times; use “not X, but Y” only for genuine corrections of misunderstandings; disclose limitations and inferences with explicit labels; separate facts from opinions; and bring the conclusion back together, carrying reports through to the So What.
At this stage, do not worry too much about prohibited wording or rhythm. Fully develop the content within the constitution, and leave the fine details to the inspection stage.
3. Inspection (1) — Static detection
In the following command, resolve
to the absolute path of the directory containing the currently loaded
before using it. Even if the Skill is installed in another project, the script must use
rather than the working directory. The target document
may still be resolved relative to the user's working directory.
uv run "$SKILL_DIR/scripts/lint.py" --json <file>
This mechanically detects prohibited wording, translationese, repeated negative-positive contrasts, uniform sentence lengths, nominal-ending frequency, paragraph-initial connective frequency, lexical diversity, suspected English syntax, and similar issues. The result uses exit code 0 regardless of the number of findings, because lint does not stop CI based on the count. It uses exit code 1 only for input errors.
If the genre of the target document is clear, specify
--genre essay|tech|business
to switch to corpus-calibrated threshold profiles and reduce false positives. For differences in the judgment criteria between genres, see
references/genre-notes.md
.
During the convergence loop in 4–5, pass the previous
output as
to have the tool automatically classify findings as resolved / new / persisting. In environments where
is unavailable, such as Claude.ai, use
references/manual-checklist.md
to check the same aspects manually.
There is also
, an EXPERIMENTAL semantic detector. It uses sentence embeddings to measure fluctuations in the similarity between adjacent sentences, capturing the characteristic blandness of trending-topic prose. Because it depends on torch + sentence-transformers and requires an approximately 1 GB model download on the first run, it is heavyweight and is not integrated into lint.py itself. Instead, it is exposed as a separate opt-in entry point. Run it only when the Full workflow or the environment permits:
uv run "$SKILL_DIR/scripts/semantic.py" --json <file>
Add the findings to the decision ledger in the same way as lint findings.
4. Inspection (2) — Decision ledger and two reviews
Lint findings are signals of possible issues, not instructions to fix everything mechanically. Reread the relevant category section in
references/revision-guide.md
, and judge each issue in context to decide whether to fix it. For every finding, record whether it was “Fixed” or “Kept (with reason)” as you proceed. See “Decision Ledger” in the same file for the ledger format.
If a terminology catalog is needed: prohibited wording →
references/forbidden-patterns.md
; translationese →
references/translationese.md
. To check whether specialized terms are explained when they first appear, use:
uv run "$SKILL_DIR/scripts/terms.py" <file>
This lists Katakana compounds, ASCII abbreviations, and terms that appear to be proper names, together with their first occurrence, occurrence count, and the presence of explanation markers. The machine does not determine whether a term has actually been explained; the AI or human does.
Structural review — Read through the skeleton
Lint can see only the surface at the sentence level. In list-heavy minutes and slides, lint will often pass almost everything, so structural review becomes the main task. From the completed body, extract only the headings and the first sentence of each paragraph, then check the following. The tool
uv run "$SKILL_DIR/scripts/outline.py" <file>
can mechanically extract headings, the first sentence of each paragraph, and bullet-point placeholders with line numbers:
- Does the argument hold? Can the reader follow the logic from the skeleton alone?
- Does every heading convey a message?
- Is the same template repeated? Consider definition patterns, internal section structures, and opening sentence forms.
- Is there variation in depth? Are all sections equally substantial?
- For reports, does the ending connect to the So What?
- In business or tech explainers, case studies, and reports, are the primary answers to expected questions unnecessarily delayed until late in the document? Similarly, are facts repeatedly withheld in favor of foreshadowing, anomalies, reveals, and payoffs?
When a document type has been established, compare it with the doctype’s “Required Elements” and “Common AI Failures.”
Readability review
You can use
uv run "$SKILL_DIR/scripts/lint.py" --reading-load <file>
to identify passages with a high comprehension load, including long sentences, buried enumerations, consecutive kanji, double negatives, and chains of 「の」.
This is a revision lane separate from AI-like style detection and is not included in either the naturalness score or comparisons. Its output means “look here,” not “fix this.” Treat the findings as starting points, and decide how to revise them by consulting the relevant entries in the catalogs below.
Word order, comma placement, one proposition per sentence, subject–predicate distance, overuse of kosoado (これ/それ/あれ), and verbose expressions are judgment areas that have been shown not to be reducible to mechanical thresholds. Consult
references/readability-principles.md
for general principles and
references/readability-antipatterns.md
for a catalog of 27 poor-sentence patterns classified from A to J in order of comprehension load. Make these judgments visually on every pass, working through the catalog from the beginning. A, nested negation; B, dependency distance; and C, the weight of words and inflected forms force readers to perform calculations within a single sentence, while H, I, and J operate across the document, its notation, and the reader’s knowledge. Brevity is not the objective function. Use length only as a tie-breaker among equivalent candidates after confirming fact preservation, subject–predicate relationships, and dependencies. Increasing the character count by splitting sentences or expanding an enumeration can be the correct result and must not be treated as a failure.
Add issues found during the structural and readability reviews to the decision ledger as individual entries, just as with lint findings.
If a paragraph can only say something generic, with no proper names, numbers, or examples, the problem is often insufficient source material rather than writing technique. Consult “Branch for Insufficient Material” in
references/revision-guide.md
to decide whether to return to information gathering.
5. Convergence
After applying the items marked “Fixed” in the ledger, rerun lint and check whether new findings appear. Repeat 3–4 until every finding in the ledger has been dispositioned and the revisions have not created any new findings. If the same finding reappears for two consecutive rounds, see “Divergence Guard” in
references/revision-guide.md
.
When rewriting an existing document, do not indiscriminately apply the same kind of revision—such as turning every heading into a conclusion or converting every list into prose—to every item. Doing so removes the document’s natural variation in depth and may increase its AI-like quality. Select only the changes that add value. See “Do Not Apply Revisions Uniformly” in
references/revision-guide.md
.
6. Final pass — Self-review loop and evaluation harness
Even after lint and the ledger converge, that only means the known surface-level patterns have been removed. At this point, qualities that lint cannot detect, such as “sterile coldness” and “sluggish, padded elongation,” may remain.
In Full mode, and for important documents, use the
6-axis revision rubric in
references/eval-rubric.md
to perform an objective evaluation.
- Removal of AI-like writing and stylistic naturalness: Are there no presentation-style numerical declarations, empathy-triggering appeals, translationese dashes, or categorical pronouncements?
- Information density and concision, excluding sluggish padding: Have unnecessary preambles, lectures, and restatements that waste the reader’s time been removed?
- Functionality and scannability: Can readers reach the information they need by the shortest route without confusion?
- Logical clarity and persuasiveness: Do the causal relationships feel convincing, and are they grounded in actual measurements and concrete examples?
- Human touch and sincerity, including warmth and motivation: Does the text avoid a sterile atmosphere and contain the writer’s lived experience and awareness of the problem, including the Why?
- Self-demonstrating quality: Is the document itself an honest and exemplary model of what it recommends?
The pass criteria are at least 90 points on every axis and an overall average of at least 92. If any axis falls short, identify the bottleneck, revise the document, and repeat the loop until it passes. See
references/eval-rubric.md
and
references/revision-guide.md
for the detailed procedure. In Quick mode, mentally check these six perspectives and finish. If you notice anything that feels wrong, revise it and complete the task.
7. Cleanup
When the task is complete, delete all intermediate files created during the work, including the ledger, lint JSON, and draft backups. The only files that should remain in the user’s project are the completed document and, if explicitly requested by the user,
. See “Handling Working Files” in
references/revision-guide.md
for details.
Examples
For concrete before-and-after examples, see
.