avoid-ai-writing: A Rule-Based Auditor for LLM Prose, Not a One-Shot Prompt

The Problem: One-Shot "Sound Human" Prompts Do Not Show Their Work

The README frames the project against a specific failure: a single prompt asking a model to make text sound human catches obvious tells and hides its reasoning. This skill instead returns a structured audit in four discrete sections, with identified issues, quoted text, the rewrite, a change summary and a second-pass audit. The target user is someone who publishes prose and needs to see what changed and why, not someone who wants a black-box polish. It ships as a portable skill for Claude Code, OpenClaw, Hermes and other agentskills.io-compatible agents, so the same rule set travels across tools rather than being rewritten per editor. The bundled detector engine is shown in the repository's demo image flagging 13 AI-writing patterns by category in a sample paragraph and then scoring the clean rewrite 0/100. That score is a mechanical check, not a judgement about whether the prose is good.

How the Detection Actually Works: Tiers, Density and a Second Pass

The mechanism is a word replacement table with 112 entries across three tiers, plus 10 Tier 3 phrases. Tier 1 matches flag unless a listed exception applies. Tier 2 words flag when they cluster. Tier 3 words flag only at high density. Tier 1 splits further into 1A frequency markers such as delve and tapestry, and 1B clarity edits such as "in order to" and "utilize". The README is explicit about why that split matters: both get the same fix, but only 1A is evidence about how a passage was produced, so 1B is weighted lower and a wordiness fix cannot push a document toward an AI classification. Tier 3 phrases such as "the integration of" and "decentralized compute" flag on per-phrase repetition or when three or more distinct phrases stack in one piece. The stated shape being caught there is an LLM varying its own boilerplate. On top of the table sit 74 pattern categories covering structural detection, AI-tool fingerprints, rhythm and uniformity checks, conversational-register tells and writer-side tests. After a rewrite, a second pass re-reads the output and looks for recycled transitions, lingering inflation and copula swaps that survived the first edit. That second pass is the part a single prompt usually lacks.

Three Modes, and Why Detect Mode Is the One Worth Understanding

Rewrite is the default: flag patterns and rewrite the text, then run the second pass. Detect flags without rewriting and separates real problems from judgment calls. Edit modifies a prose file in place through the Edit tool with minimal targeted changes, preserving passages that are already human, and returns an edits-made plus verification report rather than the whole file. Detect mode is the mode that changes how you can use the tool. If a pattern is intentional, or you are auditing text you have no permission to alter, rewriting is the wrong operation. The README lists exactly those cases. There is also an optional voice profile with five settings (casual, professional, technical, warm, blunt) that controls how the prose should sound, independent of the audience context profile. Keeping voice separate from audience is a sensible split, and it is the kind of thing that is easy to conflate in a prompt-only approach.

Getting It Running: Clone, Single File, or Slash Command

The primary install is a directory clone into the agent's skills folder. For Claude Code the README gives: git clone https://github.com/conorbronsdon/avoid-ai-writing ~/.claude/skills/avoid-ai-writing. A second option is the self-contained dist/avoid-ai-writing.md, which includes every rule and profile with manual fallbacks for commands unavailable outside the bundle, referenced from CLAUDE.md with a line such as: Editing for AI patterns, read path/to/avoid-ai-writing.md. A third option is a slash command. Create a command file, for example ~/.claude/commands/clean-ai-writing.md, with front matter containing description: Audit and rewrite content to remove AI writing patterns, then $ARGUMENTS, then an instruction to read and follow ~/.claude/skills/avoid-ai-writing/SKILL.md. Invoke it as /clean-ai-writing <your text>. Claude Cowork is different: the README states Cowork loads skills only from installed plugins and does not scan ~/.claude/skills/, so a bare clone will not be discovered there and the plugin install path is required. The repository also bundles scripts/, detector/ and examples/ for optional mechanical verification.

The Install Footgun: SKILL.md Without references/patterns.md

The README carries an explicit warning that matters more than most install notes. Keep SKILL.md with references/patterns.md, because the entry file loads the catalog before auditing. Do not copy the slim entry file alone. Older installers that fetch only the root SKILL.md omit its required reference, and the README's instruction is to use a directory install instead. This is a real failure mode with a quiet symptom: the skill may appear installed and still audit against an incomplete rule set, and nothing in a truncated install necessarily announces that the catalog is missing. If you are wiring this into a team setup, the file count is part of the contract, not an implementation detail. The README also notes the 74-category count is enforced against references/patterns.md in CI, which means the catalog file is the source of truth and the number in the README is checked rather than asserted.

Where This Is the Wrong Tool: Structured Content and Judgement Calls

Edit mode refuses source code, configuration and generated data, on the stated grounds that prose rewrites can corrupt structured content. That refusal is correct and it is also a boundary: this skill is for prose, not for mixed repositories. The tiered design implies a second limitation. Tier 2 words flag when they cluster, and Tier 3 words flag only at high density. A short passage with one Tier 2 word will not trip the detector, so a genuinely AI-flavoured sentence can pass when it is short or when its tells are spread thinly across a document. The README acknowledges this class of problem by offering detect mode for separating real problems from judgment calls, which is an admission that some flags are not settled. The demo output is instructive here: the rewrite of the funding paragraph drops the promotional language and the vague attribution, but the README's own summary of what was caught counts over-polished uniformity among the tells. Uniformity is a property of a whole document, not a word, and no replacement table can fix it. A writer still has to make that call.

The Real Alternative: General Linters and Style Checkers

The closest comparison is a general prose linter in the Vale or textlint family. Those tools parse text against configurable style rules and report violations, and they run in CI without an agent in the loop. The difference in approach is the rule vocabulary and the repair step. A style checker enforces rules you write for your house style, and it will not tell you that "serves as" is copula avoidance or that "watershed moment" is significance inflation. This project ships an opinionated catalog of 74 AI-writing pattern categories and 112 word replacements, so the rules are the product rather than something you author. The trade is control: you cannot easily redefine what counts as an AI-ism, because the tiers and the weighting are built in. The second difference is that this skill rewrites and then re-audits its own output, while a linter only reports. If your need is deterministic enforcement of a house style in a build pipeline, a linter fits better. If your need is a second reader that names AI tells and offers a plain-language replacement, this is the narrower and more specific tool.

Maintenance, Versioning and the MIT Licence

The project is MIT licensed, which permits commercial use and modification, though the usual caveat applies that this is not legal advice and you should read the LICENSE file yourself. Versioning is active and granular. The three most recent releases are v3.33.0, v3.32.0 and v3.31.0, all dated 2026-09-05, with v3.31.0 landing at 18:59 UTC and v3.33.0 at 20:08 UTC the same day. Three minor bumps inside roughly seventy minutes suggests either rapid iteration or automated release tooling, and it also means the rule set can shift under you between sessions. For a skill whose output you might paste into published work, pin the version you audited against rather than tracking main. The upgrade cost is otherwise low: there is no service, no runtime dependency to patch and no data leaving your machine beyond whatever your agent already sends. The real maintenance burden is reviewing the pattern catalog when you upgrade, because a changed tier weighting can move a document's classification without any change to the document. The repository was last pushed on 2026-09-06 and is not archived, so the cadence is current as of that date.

Editorial conclusion

Adopt it if you already run Claude Code or another agentskills.io-compatible agent and you want an auditable, rule-based pass over prose you publish, with detect mode available for text you do not want altered. Do not adopt it for source code, configuration or generated data: the README states the Edit mode refuses those because prose rewrites can corrupt structured content. Before relying on it, verify that your install kept SKILL.md together with references/patterns.md, since the README warns that installers fetching only the root entry file omit a required reference.

Official sources

1. conorbronsdon/avoid-ai-writing on GitHub
2. License: MIT
3. Project website
4. README
5. Releases