natural-japanese
A skill for writing Japanese business documents to make them easy to read and understand. It covers everything from business documents like meeting minutes, research reports, internal guides, research notes, and slides to notes, blogs, and essays. Removing AI-like tones is built into the process.
Design Philosophy
There are two core principles. First, "Detection by machine, judgment by AI". AI has difficulty recognizing its own quirks, so machines perform definitive detection of suspicious elements, while AI (you) decides whether to revise based on context. Second, "Constraints during generation rather than post-hoc correction". Preventing AI-like tones from occurring through pre-writing design and writing constraints is more effective than removing them after writing. The process proceeds in the order of "Design → Writing → Inspection → Convergence".
Execution Modes — Quick and Full
The same process can be run in two modes with different levels of effort. Estimated time requirements: Quick mode takes around 30 seconds for short documents (like meeting notes) and about 3 minutes for longer ones (around 10,000 words). Full mode takes around 7 minutes for short documents and 15-20 minutes for 10,000-word documents. When starting Full mode, inform the user of this estimate before beginning.
Quick (Default): Use this for daily documents. Complete the process here without using sub-agents. You only need to read the Type 1 file for the relevant doctype (the summary in §2 of the Writing Constitution is sufficient; other references are only opened when you're unsure after lint findings). For Design (§1), confirm the reader, core message, and headings mentally. Inspection consists of one lint run and a skeleton read-through. Do not skip lint even for short documents (statistical detectors may remain silent for short texts, but forbidden words and translationese can be detected even in a single sentence. This is a few seconds of insurance, and skipping it invalidates the quality guarantee for Quick mode). The convergence loop ends after one round if no new findings appear, followed by a final pass read-through. The additional time from this skill should be within tens of seconds; if you start reading references beyond that, you're doing Full mode work.
Full: Use this when the user says "thoroughly", "carefully", "take your time", for documents with high failure costs (such as external or executive-facing documents), or for long documents (over 10,000 words as a guideline). Once you decide on Full mode (or if the user specifies it), do not skip any steps even for small documents. In addition to lint, run outline/terms, and always perform the three inspection (§4) reviews—Structure Review, Readability Review, and Doctype Matching—using parallel sub-agents (each returns their findings, and the parent agent must integrate them into the judgment ledger and decide whether to revise/retain. Do not split the writing itself—consistency of tone, metaphors, and inter-chapter connections can only be maintained by looking at the entire document). Repeat convergence until the state conditions (§5) are met. Even if you feel "overkill" for the document, do not arbitrarily skip steps; instead, propose switching to Quick mode to the user. It has been empirically confirmed that executing with a low thought budget (effort) tends to streamline Full mode steps. If you can choose effort in the environment, recommend high for Full mode (low is sufficient for Quick mode).
If you're unsure, first finish in Quick mode, then add a note to the user that "we can also polish it in Full mode".
How to Call — write / score / Mode Specification
When the skill is called as a command with arguments, interpret the following formats:
/natural-japanese [quick|full] <target>
/natural-japanese write [quick|full] <topic or materials>
/natural-japanese score [quick|full|exp] <file>
If no mode is specified, choose it yourself based on the execution mode criteria. The same applies for natural language requests (e.g., "Write about X" corresponds to write, "Is this text AI-like?" or "Score the AI-like tone" corresponds to score).
1. Design — Decide Before Writing
1-1. Reader, Purpose, Document Type
Identify who will read the document and what you want to happen after they read it (ask the user if unclear). Once the document type is determined, read the corresponding template:
- Meeting minutes →
references/doctypes/minutes.md
- Research/analysis reports →
references/doctypes/report.md
- Internal guides/manuals →
references/doctypes/guide.md
- Research notes, discussion papers, proposals →
references/doctypes/memo.md
- Slide outlines →
references/doctypes/slide.md
You may skip this section for documents that don't fit these templates (such as notes, blogs, essays).
1-2. Core Message and Skeleton
Write the core message in one sentence before drafting the main text. If you can't write it, you lack materials—it's not a writing issue (→ 1-4). Next, create a heading skeleton. Each heading should be a message containing a conclusion, not a label like "Background" or "Summary". Confirm that the argument flows when reading only the headings in order before proceeding to the main text.
1-3. Tone Variation Design
Writing all sections with the same intensity and depth creates "overly uniform unnaturalness". Intentionally design unevenness by making important sections detailed and minor sections lightly written. Refer to "Tone Variation Design" in
references/revision-guide.md
for procedures.
1-4. Material Collection — Optional, for New Writing
If you start writing without enough proper nouns, numbers, or examples, you won't be able to fix it later even if you realize you're only stating generalities. Refer to "Material Collection" in
references/revision-guide.md
for procedures to collect materials via inference and search, criteria for determining sufficiency, and how to request materials from the user in environments where web search is unavailable.
1-5. Writing Style Profile — Optional
If
(at the project root or user-specified location) already exists, load it and use it as a basis for perspective, vocabulary, and rhythm quirks. If not, proceed in general mode. Only when the user requests "Teach my writing style", extract features from 3-5 past texts following
assets/style-profile-template.md
and write a profile (avoid overassertion; use phrases like "tend to"). If the user explicitly states that specific words or combinations are "something I don't use" or "unnatural", do not extend it to general rules—record it in the "Avoided Expressions" section of the same profile with the source and scope of application. Do not ban entire words; use the pointed-out combination as the smallest unit.
2. Writing — Write Under the Writing Constitution
Write the main text using the 12 articles in
references/writing-constitution.md
as constraints. Key points include: Write from the conclusion without preambles; headings are messages; explanations are in plain text (use bullet points only for truly parallel compressions); explain technical terms in the order of "function → name" within the text; ground content with proper nouns and numbers; use bold for only one core point per text; add tone variation; do not repeat the same template three times; use "not... but..." only for true misunderstanding corrections; disclose limits and estimates with explicit labels; separate facts and opinions; for reports, connect the conclusion to "So What".
At this stage, don't worry too much about forbidden words or rhythm—focus on getting the content out within the constitution's scope. Details will be caught in the next inspection step.
3. Inspection(1) — Static Detection
uv run scripts/lint.py --json <file>
Mechanically detect forbidden words, translationese, repetition of negation-affirmation contrasts, homogeneous sentence length, rate of noun-clause endings, rate of conjunctions at paragraph starts, vocabulary diversity, suspicion of English syntax, etc. The detection result returns exit code 0 regardless of the number of findings (since it's lint, we don't stop CI based on the count). Exit code 1 is only returned for input errors.
If the genre of the target document is clear, specify
--genre essay|tech|business
. This switches to a corpus-calibrated threshold profile, reducing false positives. Refer to
references/genre-notes.md
for differences in judgment criteria by genre.
In the convergence loop (4-5), passing the previous
output to
automatically sorts findings into resolved/new/persisting. In environments where
is unavailable (such as Claude.ai), manually check the same aspects using
references/manual-checklist.md
.
There's also an EXPERIMENTAL semantic detector called
. It measures the fluctuation of similarity between adjacent sentences (flatness of topics) using sentence embeddings. Due to its heavy dependencies on torch + sentence-transformers and initial ~1GB model download, it's not integrated into lint.py itself and is an independent opt-in entry. Run
uv run scripts/semantic.py --json <file>
additionally only during Full mode or if the environment allows, and handle findings the same way as lint by adding them to the judgment ledger.
4. Inspection(2) — Judgment Ledger and Two Reviews
Lint findings are only suggestions of suspicion, not instructions to revise everything. Re-read the section for the category that hit this time in
references/revision-guide.md
, and judge whether to "revise/retain" based on context. Proceed by writing down "revised" or "retain (reason)" for each finding (refer to "Judgment Ledger" in the same file for the ledger format).
If you need a term catalog: Forbidden words →
references/forbidden-patterns.md
, translationese →
references/translationese.md
. To check if technical terms are explained on first occurrence, use
uv run scripts/terms.py <file>
. This lists katakana compound words, ASCII abbreviations, and words that appear to be proper nouns with their first occurrence line, number of occurrences, and presence of explanation markers (AI/humans judge whether they've been explained, not the machine).
Structure Review — Skeleton Read-Through
Lint only sees the surface level of sentences. Especially for minutes and slides that are mainly bullet points, lint will almost pass through, so the Structure Review becomes the main focus. Extract only the headings and the first sentence of each paragraph from the completed text and read them to confirm the following (you can use
uv run scripts/outline.py <file>
to mechanically extract headings, first sentences of each paragraph, and bullet point placeholders with line numbers):
- Does the argument flow (can you follow the story with just the skeleton)?
- Does each heading contain a message?
- Is there no repetition of the same template (definition sentence type, internal section structure, opening sentence pattern)?
- Is there tone variation (are all sections not the same depth)?
- Does the conclusion connect to "So What" (for reports)?
- For business/tech explanations, case studies, and reports, are key answers to fixed questions not delayed until the latter half? Also, are users not repeatedly asked to follow announcements, anomalies, revelations, or recoveries separate from factual explanations?
If the document type is determined, also check against the "Required Elements" and "Common AI Failures" of the doctype.
Readability Review
Word order, comma placement, one meaning per sentence, distance between subject and predicate, overuse of demonstrative words, and redundant expressions are judgment areas that have been proven cannot be mechanically thresholded. Refer to
references/readability-principles.md
(general principles) and
references/readability-antipatterns.md
(24 bad writing patterns) each time, and judge visually. Do not use brevity as an objective function; only use it as a tiebreaker between equivalent candidates after confirming fact retention and subject-predicate relationships.
Problems found in the Structure Review and Readability Review should also be entered into the judgment ledger as individual lines, just like lint findings.
If a paragraph only states generalities (no proper nouns, numbers, or examples), it's often a material issue rather than a writing issue. Refer to "Branch for Insufficient Materials" in
references/revision-guide.md
to decide whether to return to information collection.
5. Convergence
After reflecting the "revised" items in the ledger, re-run lint to check for new findings. Repeat steps 3-4 until all findings in the ledger are sorted and revisions do not generate new findings. If the same finding recurs for two consecutive rounds, refer to "Divergence Guard" in
references/revision-guide.md
.
When rewriting existing documents, uniformly applying the same type of correction (such as turning headings into conclusions, converting bullet points to plain text) will erase the natural tone variation of the original document and instead increase the AI-like tone. Refer to "Do Not Apply Revisions Uniformly" in
references/revision-guide.md
for the principle of only revising parts that add value.
6. Final Pass — Self-Inspection Loop
Even if lint and the ledger converge, it only means known patterns have been eliminated. Finally, be sure to read through the document as a first-time reader, and check the rhythm as if reading aloud. Refer to "Self-Inspection Loop" in
references/revision-guide.md
for procedures. If you find any discomfort, enter it into the ledger and return to step 5; if none, consider it complete.
7. Cleanup
After completion, delete all intermediate files created during work (ledger, lint JSON, draft backups, etc.). The only files you may leave in the user's project are the completed document and
if the user explicitly requests it. Refer to "Handling Work Files" in
references/revision-guide.md
for details.
Reference Examples
For specific before/after examples, refer to
.