avoid-ai-writing

avoid-ai-writing started as one Markdown file telling an agent how to strip AI-isms out of a draft. It is now a repository with a zero-dependency JavaScript detector, a preservation validator, an MCP server, a Cursor port, a community German translation, and a page that runs the detector on its own documentation and publishes the unflattering scores. 3,400 stars and a release most weeks.

conorbronsdon/avoid-ai-writing

Audit and rewrite content to remove AI writing patterns

https://github.com/conorbronsdon/avoid-ai-writing

What it is for

Removing the tells that mark text as machine-written. Not improving your prose generally, and not enforcing a style guide. The scope is deliberately narrow, which is why it works.

Three modes:

The second pass is the part most one-shot prompts miss. Rewriting introduces its own tells: recycled transitions, a fresh round of inflation, copula swaps that slipped through. Reading the rewrite again catches them.

An optional voice profile (casual, professional, technical, warm, blunt) sets how the output should sound, separately from the audience context.

The vocabulary system

The word list is not vibes. 112 entries across three tiers, plus 10 multi-word Tier 3 phrases, each with a specific plainer replacement. "Leverage" becomes "use". "Commence" becomes "start".

• Tier 1 always flags, and splits again. 1A covers frequency markers such as delve and tapestry, which are evidence about how a passage was produced. 1B covers clarity edits such as in order to and utilize, weighted lower so that fixing wordiness cannot by itself push a document toward an AI verdict.
• Tier 2 flags when the words cluster.
• Tier 3 flags only at high density, and Tier 3 phrases flag on repetition or when three or more stack in one piece, which is the shape a model produces when it varies its own boilerplate.

That 1A/1B split is the sharpest idea in the project. Most word blacklists conflate "this is bad writing" with "this smells like a machine", and the two need different weights.

Beyond vocabulary, 62 pattern categories cover structure (hashtag stuffing, bare noun-phrase bullets, hedge-stacked predictions), AI-tool fingerprints (leftover placeholders, citation markup, UTM parameters), rhythm and uniformity, conversational register, and unnecessary hyphenation. The count is enforced against SKILL.md in CI.

What language

The skill itself is Markdown, so there is nothing to run for the rewriting half. The detector is plain JavaScript with no dependencies and no build step, working in Node and the browser.

const AIDetector = require("./detector/patterns.js");
const { score, label, issues } = AIDetector.analyzeText("Your text here…");

The engine is the single source of the numeric score. The skill reports which patterns are present and how severe; the engine turns that into one 0 to 100 number, where 0 is clean. There is deliberately no second prose-estimated score, so the skill and the code cannot disagree.

A preservation validator ships alongside it. detector/validate.js compares a rewrite against the original and fails when the edit touched something it should not have: a code block, YAML frontmatter, a blockquote, a table cell, inline code, a URL, a file path, the heading structure, or when the rewrite ends with more flagged patterns than it started with.

node detector/validate.js before.md after.md   # exits 1 on a preservation error

The detector is also wrapped as a local MCP server exposing two read-only tools, score_text and audit_text. It calls no model and sends nothing over the network. There is no rewrite tool by design: rewriting stays in the skill where the editorial rules live.

claude mcp add avoid-ai-writing -- npx -y avoid-ai-writing-mcp@0.1.0

How to install

# Any agent, via the community skills CLI (needs Node >= 22.20.0)
npx skills@1.5.23 add conorbronsdon/avoid-ai-writing

# Claude Code, by hand
git clone https://github.com/conorbronsdon/avoid-ai-writing ~/.claude/skills/avoid-ai-writing

# Claude Code or Cowork, as a versioned plugin
/plugin marketplace add conorbronsdon/avoid-ai-writing
/plugin install avoid-ai-writing@conorbronsdon-skills

Worth knowing: the npx fast path installs only SKILL.md. Clone the repo when you want the detector, the validator and the tests. Cowork loads skills only from installed plugins and does not scan ~/.claude/skills/, so a bare clone is invisible there and the plugin route is the one that works.

There are also ClawHub for OpenClaw, a ported .mdc rule for Cursor, and drop-in paths for Hermes and Codex through the agentskills.io format.

The part I keep thinking about

PROOF.md runs the repo's own detector over the repo's own documentation and publishes the result, including the defects it found. Two score columns sit side by side. Raw counts every match, so SKILL.md scores 89 because a catalogue of banned words necessarily contains the words it bans. Exempt blanks quoted examples, code fences, tables and blockquotes, and scores 12. CI fails when any document drifts past its budget.

The reasoning is stated plainly: two columns are published because publishing only the flattering one is the behaviour the project exists to criticise. That is a higher bar than most tools in this category clear, and it is the reason I would trust the numbers.

The same discipline shows in what the project refuses to claim. Chicago, APA, MLA and AP are paywalled, so nothing in the repo could verify a rewrite complies with them. Passing one of those names bundles nothing, falls back to the model's own knowledge, and the skill is instructed to say so and claim no compliance.

House style is a different job

The author is explicit that this skill removes AI tells and does not enforce a style guide, and it ships none of its own. That matters for anyone who already has a voice defined, because the two compose rather than compete: this strips the machine tells, your own rules decide how the result should sound.

For style-guide enforcement in CI, the README points at Vale, whose package registry carries Google, Microsoft, Red Hat and Salesforce implementations plus ports of proselint and write-good. Vale gates a document one alert at a time; this rewrites whole passages while you draft.

The optional --style input takes a config you supply: a register list the model applies, and a mechanics object whose checkable rules a script verifies. Quote form and Latin abbreviations gate the exit code; heading case, em-dash rate and number spelling are advisory only.

Value

The pattern research is credited rather than invented, which is unusual and useful. It draws on Pangram Labs detection work, Wikipedia's Signs of AI writing page, and two earlier humanizer skills. Those sources are worth reading on their own.

A community multilingual port by Jürgen Kraus covers German, French, Italian, Romanian and Swedish, grounded in native-language research rather than translated from the English. Useful if you write in more than one language, because the tells do not translate: German AI prose has its own habits, and an English word list will not catch them.

Where it fits next to what I already run: my own guidelines set the voice and the mechanics, and this is the gate that checks the output. The tiered vocabulary and the copula-avoidance list are tighter than mine, and the 1A versus 1B distinction is worth copying outright.

De-Slopping AI Output: Ben AI's Skill vs My Guidelines

The New Em-Dash: 9 Tells of AI Writing

Caveats

• The skill file is now 95 KB. That is a lot of context to load for one editing pass, and it grows with every release.
• Version churn is fast. v3.26.0 on 24th August, several releases in the preceding fortnight. Pin a version if you depend on the behaviour.
• The detector is deterministic, not a classifier. It counts patterns you can name. It will miss machine text that avoids them and will flag a human who writes formally.
• Rewriting is still a model doing the rewriting. The validator catches structural damage, not a rewrite that quietly changes your meaning. Read the diff.

Further reading

• conorbronsdon/avoid-ai-writing
• The MCP server wrapper
• Multilingual port: German, French, Italian, Romanian, Swedish
• Wikipedia: Signs of AI writing
• skills, the installer CLI
• Conor Bronsdon's Chain of Thought podcast