avoid-ai-writing: a skill that strips AI tells from agent-written prose

The problem: model prose has a detectable house style

Ask a model to draft a paragraph and you get a recognisable set of habits. The README's own demo input is a compact catalogue of them: a chatbot opener ("Certainly!"), promotional adjectives ("nestled", "thriving"), significance inflation ("watershed moment"), copula avoidance ("serves as", "featuring", "boasting"), vague attribution ("experts believe"), a filler transition ("Moreover") and a generic sign-off ("the future looks bright"). The project calls these AI-isms and counts 15 or more in that single paragraph.

The audience is narrow and specific. This is for writers and engineers who run an AI agent over their own drafts and want the machine's fingerprints removed before publication, not for someone trying to classify a stranger's text. The README frames the tool as a portable skill for Claude Code, OpenClaw, Hermes and any other agentskills.io-compatible agent, which tells you the intended workflow: the agent you already use for editing is the one that runs the audit. The homepage points at chainofthought.show, and the repository carries a cursor-rules directory for Cursor users.

There is a second, quieter audience: people who want a mechanical check rather than a model's opinion. The package.json describes a deterministic detection engine for pattern and stylometric analysis, published on npm as avoid-ai-writing-detector with two binaries. That is a different proposition from a prompt file, and the project ships both.

How the skill audits: four sections, two passes, 112 word entries

The mechanism is a structured audit rather than a single rewrite instruction. According to the README, the skill returns identified issues with quoted text, the rewrite, a change summary, and a second-pass audit, in four discrete sections. The second pass re-reads the rewrite and looks for patterns that survived the first edit: recycled transitions, lingering inflation, copula swaps that slipped through. That two-pass loop is the main structural difference from a one-shot "make this sound human" prompt, because the failure mode of a single pass is exactly the pattern that got missed.

The vocabulary side is a 112-entry word replacement table split across three tiers, plus 10 Tier 3 phrases. The README gives the rule for each tier: Tier 1 matches flag unless a listed exception applies, Tier 2 words flag when they cluster, and Tier 3 words flag only at high density. Tier 1 itself splits into 1A frequency markers and 1B clarity edits such as "in order to" and "utilize". The README is explicit about why that split exists: only 1A is evidence about how a passage was produced, and 1B is weighted lower so that fixing wordiness cannot push a document toward an AI classification. That is a real design decision, and it is the kind of thing most prompt packs never bother to separate.

Tier 3 phrases are multi-word boilerplate such as "the integration of" or "decentralized compute". They flag on per-phrase repetition, or when three or more distinct phrases stack in one piece. The README describes that shape as the LLM-self-varies-boilerplate pattern, which is a fair description: a model avoiding one cliché often rotates through several.

The pattern catalogue holds 74 categories, and the README says the count is enforced against references/patterns.md in CI. Categories include structural detection (hashtag stuffing, bare-NP bullet lists, hedge-stacked predictions), AI-tool fingerprints (placeholders, citation markup, UTM parameters), rhythm and uniformity checks, conversational-register tells, and writer-side tests. You can disagree with individual categories, but you can check the list, which matters more than the number.

Installing the skill and running a first audit in Claude Code

The README warns that the entry file loads the pattern catalogue before auditing, so SKILL.md and references/patterns.md have to stay together. Clone the whole directory rather than fetching the root file alone, because older installers that pull only SKILL.md omit the reference it depends on.

The primary install is a clone into the Claude Code skills directory:

git clone https://github.com/conorbronsdon/avoid-ai-writing ~/.claude/skills/avoid-ai-writing

If you prefer a single file, the README points at dist/avoid-ai-writing.md, which contains every rule and profile with manual fallbacks for commands unavailable outside the bundle. Download it and reference it from CLAUDE.md:

- Editing for AI patterns → read `path/to/avoid-ai-writing.md`

The third route turns the skill into a slash command. Create a command file, for example at ~/.claude/commands/clean-ai-writing.md, whose body tells the agent to read the skill's SKILL.md. The README's example command file carries a description line and passes $ARGUMENTS through, so the text you type after the command name reaches the skill. Once that file exists you invoke it as /clean-ai-writing followed by your text.

For a mechanical check outside the agent, the repository publishes a Node package with two binaries, avoid-ai-writing and avoid-ai-writing-gate, and package.json sets the engine requirement at Node 18 or later. The gate binary is the interesting one for CI: a name like that suggests a pass/fail check rather than a report, though the README does not document its exit codes or thresholds, so treat that as something to verify in bin/avoid-ai-writing-gate.js before wiring it into a pipeline.

Three modes, and the one that refuses your source files

Rewrite is the default: it flags patterns and rewrites the text, then runs the second pass. Detect flags without rewriting and, per the README, shows which flags are real problems versus judgment calls. That distinction is worth taking seriously, because a word like "utilize" is a style problem and a word like "commence" is closer to a production fingerprint, and collapsing the two into one score is how these tools lose credibility.

Edit mode is the one with the sharpest constraint. It edits a prose file in place through the agent's Edit tool, making minimal targeted changes and preserving passages that are already human. It refuses source code, configuration and generated data, on the stated grounds that prose rewrites can corrupt structured content. It returns an edits-made and verification report rather than the full file, which keeps the agent's output small on long documents.

On top of the three modes there is an optional voice profile: casual, professional, technical, warm or blunt. The README describes it as setting how the prose should sound, independent of the audience context profile. That separation is sensible. Tone and audience are different axes, and a tool that conflates them produces rewrites that read as generically friendly regardless of who the piece is for.

One thing the README does not describe is how Edit mode behaves when a file is half prose and half code, which is common in READMEs and technical posts. The refusal rule is stated for whole files; the mixed case is left open.

Where it breaks down: detection is not classification

The honest limitation is in the framing. This is a writing skill that happens to ship a detector, not an AI-text classifier. The tier system is built to avoid false accusations: Tier 1B clarity edits are deliberately weighted lower so that fixing wordiness cannot move a document toward an AI classification, and Tier 2 words only flag when they cluster. Those are choices made by people who expect the output to be argued with.

That means it is the wrong tool for several jobs. If you need to decide whether a submitted essay, a freelance draft or a support ticket was machine-written, this will give you a list of stylistic observations, not a verdict, and the README's own language ("judgment calls") concedes as much. If you need a hosted service with an API and a dashboard, there is nothing here for you: the package is a Node module and two CLI binaries, and the skill runs inside an agent you supply. And if your text is intentionally stylised, the detect mode exists precisely because rewriting would destroy what you wanted; running rewrite mode on deliberately formal or promotional copy will sand off the voice along with the tells.

The repository also carries a corpus directory and scripts named fp-measure.js and rewrite-eval.js, which suggests the maintainers measure false positives and validate rewrites. The README does not publish those numbers, so the measurement infrastructure is visible while the results are not. Until you look at the scripts or run them yourself, treat the accuracy claims as unverified.

How it differs from a style linter or a general-purpose prompt

The closest comparison is a prose linter such as Vale, which applies rule files to text and reports violations. Vale is deterministic and fast, and it is excellent at enforcing a house style guide. It does not rewrite. The difference here is the second half of the loop: avoid-ai-writing proposes the replacement and then re-reads its own output for patterns the first pass missed. A linter tells you that you wrote "utilize"; this tells you it changed "utilize" to "use" and then checks whether the sentence around it still sounds generated.

The other comparison is the one-shot prompt. A generic "rewrite this to sound human" instruction produces a rewrite with no audit trail. The README's argument for the skill over the prompt is the four-section structure: issues with quoted text, the rewrite, a change summary, and the second-pass audit. Whether that structure is worth the install overhead depends on whether you review the changes. If you paste the output straight into a document without reading the change summary, you have paid the cost of the structure and taken none of the benefit.

There is also a portability argument. Because it is a directory-based skill, the README says it runs in Claude Code, Cowork as a plugin, OpenClaw, Cursor as a ported rule, and other directory-aware agents. Cowork is the exception worth noting: it loads skills only from installed plugins and does not scan ~/.claude/skills, so the bare clone above will not be discovered there. The repository ships a .claude-plugin directory for that path.

Maintenance, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-09-06. Releases are frequent and finely numbered: v3.31.0, v3.32.0 and v3.33.0 all landed on 2026-09-05, while package.json carries version 3.35.0. That cadence tells you two things. The rule catalogue is actively being tuned, and the version numbers in the README's release list and in package.json can drift apart between a release and the next commit. If you pin a version, pin the package version, not the tag you saw in the changelog.

Upgrade cost is mostly review cost. A new release can change how a tier behaves, and the 74-category count is enforced in CI against references/patterns.md, so the catalogue is a living document rather than a fixed spec. If you wire the gate binary into a pipeline, a rule change can turn a passing build red without any change to your prose. The repository ships a pre-commit hook configuration (.pre-commit-hooks.yaml) and a GitHub action definition (action.yml), which suggests the intended integration points, but the README does not document their behaviour.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The repository also carries a NOTICE.md and a PRIVACY.md. MIT says nothing about the accuracy of the output or the fitness of the detector for any particular purpose, and nothing in the licence review here should be read as legal advice; if you redistribute the skill inside a product, read NOTICE.md and the LICENSE file yourself.

Editorial conclusion

Adopt it if you already run Claude Code, OpenClaw or another agentskills.io-compatible agent and you edit prose that a model drafted, because the four-section audit output and the tiered word table give you something to review rather than trust. Skip it if you need a classifier for third-party text you cannot alter, or if you want a hosted writing assistant, since both detect and rewrite modes are built around editing your own drafts inside an agent. Before relying on it, clone the full directory rather than the root SKILL.md, run the bundled detector on a paragraph you know is human, and read references/patterns.md to see whether the 74 categories match the tells you actually care about.

Frequently asked questions

Official sources

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