18trees-AI-writing-skill

What it is

18trees-AI-writing-skill is a skill for cleaning up Chinese dictated drafts: it turns a draft the author has already thought through but spoken messily into an article that still reads unmistakably as their own.

What it deals with is everything voice input leaves behind — filler words, broken sentence breaks, wrong proper nouns, one solid block with no paragraph breaks — and the more troublesome step that usually follows. Hand that block straight to an AI and the article comes out clean but stops sounding like you: it elevates your conclusions for you, softens your points, stuffs in “not X, but Y”, splits the text into a pile of bullet lists and bolds until it glows.

So the skill goes the other way: cleanup before polish, fidelity before playing it safe. Facts and dictation noise can be fixed; the author’s judgement, tone and sharpness are left alone. It is built for people who draft their own writing by voice, and it lands in one of three ways: installed into Claude Code, installed into Codex, or pasted into any AI chat tool as the bound version. CONTRIBUTING.md states the boundary as well: bulk rewriting and laundering of other people’s content are not accepted uses.

How it is structured

The repository has a single main line: rules are written under skills/, a script binds them into one file, and the result is delivered to different tools. The group of nodes at the bottom of the diagram is not part of that flow — it is how the repository shows its work and constrains its own changes.

The rule source. Rules are maintained in exactly one place: skills/voice-preserving-essay-editor/. SKILL.md is the entry point, carrying the nature of the task, six ordered editing priorities, the boundary between fact and opinion, the AI-flavour red lines and the hard paragraph constraints. The detail is split by topic into six files under references/, read only when a rule needs them. Keeping the entry point lean is what lets the skill run well in both Claude Code and Codex; the folder also holds agents/openai.yaml, which supplies Codex UI metadata only.

The generated file. The split version and the single-file version cannot be maintained separately — copying rules by hand drifts. scripts/build-dist.sh reads version from SKILL.md, strips the frontmatter and the routing table (meaningless once everything is inlined), and binds the entry point and the six detail files into dist/voice-preserving-essay-editor.md: a single file holding every rule, depending on no external file, plugin or API. Rules are edited only under skills/; running the script regenerates the rest.

Delivery. The split version is installed whole: Claude Code takes it from the plugin marketplace, Codex takes a copy in its skills folder. Tools with no skill mechanism receive the bound file in full — paste it and nothing needs installing.

Showing its work. examples/ holds a real dictated transcript next to the cleaned final version: the draft is 620 characters and keeps its ASR errors, filler words and half-finished sentences, while the final version ties every change to the rule behind it. CONTRIBUTING.md states the repository’s core constraint — a cumulative skill that improves incrementally and never regresses — and lists ten rules that no change may weaken.

Design decisions worth noting

Cleanup > polish > rewrite. This ordering is written into the definition of the task: when “prettier” conflicts with “closer to the author’s original”, the original wins. In the six editing priorities around it, only the last one is “safe, neutral, more broadly acceptable”; the author is allowed to be aggressive, one-sided or blunt, and to state a judgement they may later overturn themselves.

Facts may be corrected; judgement is never neutralised. Names, titles, explicit figures and years, and proper-noun errors from speech recognition can all be looked up and fixed. Understandings of social structure, value calls and personal stands like “I think” are not downgraded to “possibly” or “maybe” just because evidence is thin. Research corrects facts; it does not take the author down a tone.

AI-flavour patterns are banned by name. “Not X, but Y” is listed as the highest-risk pattern: never manufacture it when the draft lacks it, still judge whether it is necessary when the draft already has it, and check every repeat of it within a section. Its relatives, turning the text into a pile of bullet lists, inflating conclusions and leaning on “firstly, secondly, in summary” all appear on the ban list. The default is to say what something is, directly.

Paragraph rhythm is a hard constraint, and the rules themselves can evolve. The unit of an essay is the complete paragraph, two to five sentences by default; standalone short lines are rationed to roughly one per four to six paragraphs; blank lines may not fake “sophistication” or “a cinematic feel”. The rules keep a version history too: v0.6 made paragraph integrity a hard constraint, and v0.7 moved the default to medium-length paragraphs — each generation refining the one before rather than replacing it.

Rules change in one place. skills/ is the only rule source and dist/ is generated, and the two must stay identical. AGENTS.md fixes the verification method as well: re-run the build script and git diff should produce no output.

Add, never remove. CONTRIBUTING.md’s core constraint is a single rule: a new rule may only add to, correct or refine the old ones, and a rule already shown to work may not be deleted. If an old rule seems wrong, the right move is to propose a new rule that narrows it. Ten of them are confirmed as non-negotiable.

What problems it solves

• Speech-to-text leftovers — ASR errors, typos, wrong proper nouns and factual errors — get fixed, while filler words, broken sentence breaks and half-finished sentences get removed.
• Claims stay sharp: a strong judgement is not turned into “maybe”, and no “not X, but Y” appears that the draft did not already contain.
• Layout is reworked — headings, bold, paragraph breaks — but how much structure the text gets is decided by the content, and a personal note is not turned into marketing copy or a consulting report.
• One set of rules runs in three tools: Claude Code and Codex take the split version, any AI chat tool takes the bound version pasted in, and the latter needs nothing installed.
• Every rule change verifies itself: re-run the build script and confirm git diff is empty, then walk the change against examples/ to confirm the sample still obeys the rules.
• The last self-check before output is a single question: am I cleaning up the author’s draft, or writing in their place?