Plain writing
Works in Vietnamese (vi), English (en) and Japanese (ja), grouped into two voice families: plain and creative.
Who owns what
Each rule has one owner. Read a rule in its owner file, not in a copy.
| Owner | Owns |
|---|---|
SKILL.md (this file) | The workflow and the core rules that hold for every type and every language |
doc-types/<type>.md | Everything that depends on the type: voice, structure, length policy, sentence rhythm, and the kinds of phrases to ban |
languages/<lang>/ | Everything that depends on the language: the unit, numeric limits (profile.json), the actual banned phrases (banned.txt, banned-guide.md), grammar traps, pronoun and level words, terms (terms.txt), and examples |
When two owners disagree:
- On limits and structure,
doc-types/<type>.mdwins overSKILL.md. - On words and grammar,
languages/<lang>/wins overdoc-types/<type>.md. - On how much a text may add beyond the source (reasoning, reactions, inner thoughts), the voice family below and
doc-types/<type>.mdwin over the core rules. The facts in core rule 5 never change. - Every limit that has a key in
profile.jsoncomes fromprofile.json. No other file repeats it.
Workflow
- Check for
PLAIN-WRITING.mdin the project root (template:templates/PLAIN-WRITING.example.md). IfPLAIN-WRITING.mdexists, read it and let it win on voice and terms. Usedefault_langanddefault_typeto skip the questions in steps 1 and 2. - Pick the output language (
vi,enorja). It is the language of the text you produce, not the language of the prompt. A Vietnamese brief that asks for a Japanese manual meansja. If unclear, ask one question. Then readlanguages/<lang>/profile.json(the limits for your type) andlanguages/<lang>/profile.md. - Pick the document type (table below). Read
doc-types/<type>.mdandlanguages/<lang>/examples/<type>.md. Read only these. - Know the reader: who they are, what they already know, what they must do after reading. If missing, ask one question. If you cannot ask, state your assumption outside the document (or mark
TBD:inline in specs). - Outline (one line per idea) for any text longer than about 400 words. Write only ideas that are in the outline. In the
creativefamily, the outline fixes the scenes, not every sentence. - Draft with the core rules and the type's voice, structure and rhythm. Write normal paragraphs—never put every sentence on its own line.
- Edit in a separate pass: cut, run the checklist, run the script. Fix until clean.
- Report two things outside the generated text: the result, and what you had to guess. Never prepend or append
Result:,Guesses:,---, or**推測したこと:**lines inside the document. When your reply is the document itself and you have no other place for a note, leave the report out. In specs, mark missing details inline withTBD:. The script flags the labels inbanned.txt, section[report], on the first or last 3 lines.
Draft and edit are two passes. Do not try to get it right in the first pass.
Choose the document type
| Type | Family | Structure file | --type | Typical reader |
|---|---|---|---|---|
| Tech blog (sharing technical experience) | plain | doc-types/tech-blog.md | tech-blog | Peers |
| Essay (personal, reflective) | creative | doc-types/essay.md | essay | General readers |
| API design (one endpoint) | plain | doc-types/api-design.md | api-design | Developers, QA |
| User guide, manual | plain | doc-types/user-guide.md | guide | General users |
| Anything else | plain | languages/<lang>/examples/common.md | tech-blog | Varies |
Always read languages/<lang>/banned-guide.md too (banned phrases and what replaces them).
Core rules (both families, all languages)
These rules hold for every document type:
| # | Rule | Limit |
|---|---|---|
| 1 | One idea per sentence | In plain, two subordinate clauses means split. In creative, the type file sets sentence rhythm |
| 2 | Concrete verbs, active voice | "send", not "perform the sending of" |
| 3 | Banned phrases | Zero hits from banned.txt ([all] plus the type section) |
| 4 | Opening and closing | Opening: at most 2 sentences, straight to the point. No recap, no empty thanks |
| 5 | No invention | Add no number, event, person, place, technical spec, or outcome that is not in the source. Do not place two numbers with different units or time periods next to each other as a comparison; keep both numbers and narrow the claim to what they support. How much else a text may add (reasoning, reactions, inner thoughts) is set by its voice family |
| 6 | Consistency | One concept, one name. One register for the whole text |
Voice families
Numeric limits are per language and type. They live only in languages/<lang>/profile.json. A type file may relax or tighten a rule. See "Who owns what" for which file wins.
plain (tech-blog, api-design, guide)
One voice: short, concrete, understood on first read.
- Sentence length:
sentenceinprofile.json. - Paragraph length:
paragraphinprofile.json, one idea. - Jargon (reader outside the field):
termsornon_tech_termsinprofile.json. Explain each term in one sentence, or replace it with an everyday word. - Examples and metaphors: One example or story per section, and a section is one main point.
- Evaluative adjectives ("great", "powerful", "beautiful"): Replace with a number or a visible detail.
- Length:
lengthinprofile.json, under the type's length policy. Never more than 10% over. - Nothing added beyond the source: keep human context, reasoning, and reactions grounded in the brief. In specs and guides, write
TBD: <specific question>or ask.
creative (essay)
- Sentence length:
sentenceinprofile.json. - Paragraph length:
paragraphinprofile.json, one idea. - Rhythm and imagery: Owned by
doc-types/essay.md. - Evaluative adjectives: None without a visible detail.
- Inner voice: the facts stay fixed (core rule 5), but the narrator may think, remember and doubt. Use the inner material the brief gives first. When the brief gives none,
doc-types/essay.mdsets how much you may add. Report each added thought outside the text (Workflow step 7).
Paragraph form: Write sentences continuously inside a paragraph—never split every sentence onto its own line (no trailing-space \n line breaks). Sentence rhythm is set by the type file.
When the reader is outside the field
Common failure: the AI "translates" every technical detail into plain words. The result is three times longer and still unclear. Do the opposite:
- Pick at most 3 ideas the reader needs.
- For each idea, say what the reader gets or can do. Drop the internal mechanism.
- Test each sentence: if you delete it, will the reader fail at something or misunderstand something? If not, delete it.
Cutting order for long drafts
- Sentences that repeat an earlier idea.
- Sentences that explain internal mechanism.
- The second and later examples.
- Adjectives and adverbs.
- Empty opening and closing.
For tech-blog and essay, keep human context, reasoning, and tension instead of cutting down to a bare fact list. In essay, also keep the narrator's inner thoughts and the sensory detail each scene needs.
When editing existing text
- Keep meaning, proper names, numbers, paths and code unchanged.
- Add no new information. List ambiguous spots at the end so the author can decide.
- Give a table "original → revised → reason" if the user wants to learn from the edit.
Final checklist
- The script reports no violations.
- One idea per paragraph, one idea per sentence.
- No banned phrase. No empty adjective.
- Jargon is within the limit. Each term is explained or replaced.
- The type file's checklist passes.
- Every number, event and outcome appears in the user's source. In
essay, every inner thought that the brief does not give is reported outside the text. - Register is consistent.
- Guesses are reported outside the generated document (or marked
TBD:inline in specs).
Check with the script
python3 scripts/check_style.py draft.md --lang en --type tech-blog
python3 scripts/check_style.py spec.md --lang ja --type api-design
python3 scripts/check_style.py guide.md --lang vi --type guide
python3 scripts/check_style.py post.md --lang en --type tech-blog --non-tech
--lang:vi,en,ja(optional ifdefault_langis set inPLAIN-WRITING.md).--type:tech-blog,essay,api-design,guide(user-guidealso works; defaults todefault_typeinPLAIN-WRITING.mdortech-blog).--config <path>: path to aPLAIN-WRITING.mdconfig file. By default, the script readsPLAIN-WRITING.mdfrom the current directory if present.- Units differ by language: Vietnamese counts syllables (tiếng), English counts words, Japanese counts characters (字). The unit is set in
profile.json. - The script checks sentence length, paragraph length, banned phrases, jargon count and text length. Text length outside the range is a warning, not a violation. It does not judge whether the voice is good.
- Edit
banned.txtandterms.txtin the language folder to fit your needs.
Extend the skill
Whenever the AI writes a sentence you dislike:
- Rewrite it the way you want.
- Add the pair "bad → good" to the section "Your own samples" in the matching
examples/<type>.mdof that language. - If one phrase keeps coming back, add it to that language's
banned.txtandbanned-guide.md.
Real samples written by you always outweigh samples written by AI.
Add a language: create languages/<code>/ with profile.md, profile.json, banned.txt, terms.txt, banned-guide.md and examples/. The script supports three units (syllable, word, char). No code change is needed.