write-right-skill

A Claude Code skill for text you publish. It writes at a ninth-grade reading level and takes out the patterns that mark text as machine written.

npx write-right-skill

What this is

This is a Claude Code skill for text you are going to publish. It covers blog posts, landing pages, documentation, emails, any copy that goes out under your name. It writes at a reading level a fourteen year old can follow, and it takes out the patterns that mark text as machine written.

The skill works in four steps. A drafting agent writes the first version against the rule files. Then a Python script measures the draft and reports every failure with its line number. From there the session edits what the script flagged and measures once more. A rewrite can put a long sentence or a banned word straight back in.

The finished prose goes into the file you were already working in. It arrives in the form that file needs, markdown for a markdown file and plain text for plain text. Nothing else goes in with it.

The chat gets the scorecard: reading level, sentence numbers, every check with its hit count, any claim dropped for want of a source. None of that ever lands in the file.

Install

# every project
npx write-right-skill

# this project only
npx write-right-skill --project

# see what it would do, change nothing
npx write-right-skill --dry-run

It puts the skill in ~/.claude/skills/write-right-skill and the drafting agent in ~/.claude/agents/write-right-drafter.md. Restart your session once, because Claude Code loads agent definitions at startup.

Needs python3 on your path. The script uses the standard library, so there is nothing to pip install and no virtualenv to keep alive.

Why a script and not an instruction

An instruction like "do not use em dashes" is a suggestion. A model can talk itself out of a suggestion halfway down a long draft, and it cannot count either. Ask a model how many em dashes it wrote and you get a guess delivered in a confident tone.

A script counts. It reads its word lists out of references/banned.md at run time. The list the writing agent follows and the list the script enforces are one list, with no way to drift apart.

That also means the ban list is yours, and editing that one file changes what gets enforced straight away, with no code to touch.

Reading level

Each language gets its own formula. Flesch-Kincaid grade covers English, and Dutch runs on Flesch-Douma, where a higher number means easier reading and 60 sits in the B1 band. For German the skill uses the Wiener Sachtextformel, which gives you a school year directly.

Two things move any of these numbers, and nothing else does. One is how long your sentences are, and the other is how many syllables your words have. So a bad score has two fixes: cut a sentence in half, or swap a long word for a short one.

The level works as a target. Every run reports the number, and only a text that lands two full grades over the cap goes back for a rewrite. The formulas count syllables with a heuristic. Loanwords and brand names throw them off, and German compound nouns are the worst offenders. Mangling a good sentence to satisfy a rounding error makes the writing worse than the score suggests.

| Profile | English | Dutch | German | Max sentence | |---|---|---|---|---| | blog, article, ebook | grade 9 | Douma 60 | Wiener 9 | 25 words | | landing, email | grade 9 | Douma 60 | Wiener 9 | 22 words | | social | grade 11 | Douma 50 | Wiener 11 | none | | docs | grade 9 | Douma 60 | Wiener 9 | 25 words | | technical | grade 8 | n/a | n/a | 20 words |

Technical writing

Some text should not read like prose at all. Procedures and safety instructions belong in a different register, and so do equipment specifications and API documentation. For those the skill uses simplified technical English, based on ASD-STE100, the controlled-language standard written for aircraft maintenance manuals.

The rules there are strict and few. Each sentence carries one instruction and stops at twenty words in a procedure. The same thing keeps the same name all the way through. A retaining bolt in step two is still a retaining bolt in step nine. Conditions come before the instruction they apply to, and a warning comes before the step it protects you from.

That standard also has an approved dictionary of about nine hundred words, and the dictionary is copyrighted. It is not included here, so the skill implements the rules that work without it.

What it strips out

Em dashes go first, because they are the clearest single tell. After those come the filler intensifiers, the corporate verbs, the adjectives that claim importance without earning it. Then the throat-clearing opener, the filler transition, the vague attribution, the passive voice, the object handed a human verb so nobody gets named.

Structures come out as well. The script catches binary contrasts of the "not X, it's Y" shape. Negative parallelism goes. So does the rule of three, and so does the sentence dropped at the end of a paragraph to pin it shut. Around twenty more patterns sit in the same file. The lists cover English as well as Dutch and German.

Cutting is not the goal. A sentence still needs someone doing something, and a sentence that has lost its subject has been cut too far. A row of bare fragments passes every mechanical check and reads like the label on a box.

When two rules disagree

Rules collide. A short word can be the wrong word, and your own voice can want a sentence the ban list forbids. So the order is written down and settled once, instead of getting argued again on every piece of writing.

Orwell's sixth rule stays available. Break any of the others sooner than write something barbarous. The price is that the scorecard has to name the rule that was broken and say why, in one line.

Make it sound like you

The repo ships two empty templates. One holds measured facts about how you write: mean sentence length, the words you reach for more often than other people do. The other holds samples, ten to twenty passages you published, not drafts polished for the purpose. Fill neither of them and the skill still runs. The output comes out plainer, and the report says the profile was missing.

The profile does not get the last word. Where your habits disagree with the reading level or the ban list, the habits lose. The point of the skill is to write better than your habits. It keeps your vocabulary and your register, and drops the comma-chained clause stacking you fall into when you are tired.

~/.claude/skills/write-right-skill/voice/
├── style-dna.template.md       measured facts about your writing
└── voice-samples.template.md   10 to 20 things you published

Fill them in, drop .template from both names, and the drafter uses them.

Check any text yourself

The script runs on its own, and you do not need Claude to use it. Point it at any file.

python3 ~/.claude/skills/write-right-skill/scripts/lint.py FILE \
    --lang en --profile blog

  pass  banned words          0 hits
  FAIL  banned phrases        3 hits
  FAIL  no em dash            2 em dashes, 0 en dashes
  FAIL  no landing sentence   1 paragraphs end on 4 words or fewer

    line 12   banned phrase: at the end of the day
    line 30   banned phrase: it's worth noting
    landing sentence: Let that sink in.

Use --format json to pipe it into something else. It exits 1 when a hard check fails, so it drops into a pre-commit hook or CI without any glue.

It is not an SEO skill

The seven checks in references/blog-correct.md are about the writing itself:

• the opening, and whether it could belong to any article on the topic
• the heading structure
• whether the piece has anything of its own to say
• how naturally the keyword sits in a sentence
• reading signals, so the page is not a wall of text
• whether every claim carries a real source

The search work is a different job and it stays outside this skill. Keyword research, search intent, title tags, meta descriptions, schema markup, the real sitemap, what competing pages cover, answer engine visibility. None of that happens here.

For a page that has to rank, do the search planning first, write with this skill, then do the search finishing pass. This skill writes the words.

What it will not do

The skill stays out of commit messages and code comments. Internal notes and chat replies are none of its business either. That text is private, and it does not need any of this. It also does not pick the file, because your session already knows where the words belong. The skill asks you for a path and writes there.

It never invents a citation or a statistic, and it will not produce a study that does not exist. A claim with no source gets dropped from the draft and listed in the report, so you can decide what to do about it.

What is in the box

| Path | Holds | |---|---| | SKILL.md | the eight steps and the output format | | AGENT.md | the drafting agent | | references/banned.md | every banned word, phrase and structure, three languages | | references/precedence.md | which rule wins, and four rulings that are settled | | references/levels.md | the formulas and the cap per format | | references/ste100.md | simplified technical English | | references/blog-correct.md | seven content checks for a blog | | references/examples.md | thirteen before and after pairs | | scripts/lint.py | the measuring script, standard library only | | tests/run.sh | seven fixtures, three clean, three slop, one procedure | | voice/ | the two templates |

Run the tests after you edit references/banned.md:

bash tests/run.sh

A malformed <!-- lint: --> block gets skipped without a word, so a broken list looks the same as a clean text.

Credits

Parts of references/banned.md adapt the phrase and structure tables from stop-slop by Hardik Pandya, MIT licensed.

The catalogue of AI writing patterns was written from scratch. The idea of cataloguing them, and the observation that they cluster together, comes from the Wikipedia project on signs of AI writing.

The six rules come from George Orwell, "Politics and the English Language", 1946.

MIT licensed. The full text sits in LICENSE, with the attribution details in NOTICE.