avoid-ai-writing

avoid-ai-writing

Audit & rewrite content to remove AI writing patterns. A practical skill for any AI agent. Supports detect-only and edit-in-place modes, plus voice profiles.

A portable writing skill for Claude Code, Codex, OpenClaw, Hermes, and any other agentskills.io-compatible agent. Audits and rewrites content to remove AI writing patterns ("AI-isms").

The rules and bundled detector are calibrated for English. See community language adaptations for independently maintained versions in other languages.

Three modes:

• Rewrite (default) — flags AI patterns, applies up to two editing passes, verifies the result when possible, and returns one final version.
• Detect — flags AI patterns without rewriting. Shows which flags are real problems vs. judgment calls. Useful when patterns might be intentional, when auditing content you don't want altered, or when you just want a quick scan.
• Edit — edits a prose file in place (via the Edit tool) with minimal, targeted changes, preserving passages that are already human. Source code, configuration, and generated data are refused because prose rewrites can corrupt structured content. Returns an edits-made + verification report, not the full file.

Use --iterate 1|2 to set the editing-pass ceiling. --iterate 1 allows the initial rewrite only. --iterate 2 uses the default maximum of an initial rewrite plus one correction or preservation repair, and stops early when no justified in-scope edit remains. Checks do not consume a pass, but any change they prompt does. The skill reports how many editing passes it used and any intentional, protected, or unresolved finding.

An optional voice profile (casual / professional / technical / warm / blunt) sets how the prose should sound, independent of the audience context profile.

The glossary defines the terms these docs use: word tiers, severity tiers, modes, profiles, and detector options.

Table of contents

• Quick demo
• Why a skill, not just a prompt
• Installation & Usage
  • Install the complete skill directory
  • Claude Code
  • Claude Cowork — install as a plugin
  • OpenClaw
  • Cursor
  • Hermes
  • OpenAI Codex
  • Native ChatGPT and Codex plugin package
  • Other agents
  • Triggering the skill
• Pattern reference
  • Content Patterns
  • Language Patterns
  • Structure Patterns
  • Communication Patterns
  • Meta Patterns
  • Structural Detection (v3.4)
  • AI-tool fingerprints & later additions (v3.5–3.8)
  • Conversational-register patterns (v3.15)
  • Share-post framing (v3.20)
  • Narrated candor (v3.21)
  • Unnecessary hyphenation (v3.24)
• Full Example
• Run the detector
  • Score a file or piped text from the command line
  • Gate prose in GitHub Actions or pre-commit
  • Use the detector over MCP
• House style is a different job
• More from me
• Credits
• Community / Multilingual
• Official sources and sponsorship
• Disclaimer
• License

Quick demo

Input:

Certainly! Acme Analytics, a vibrant startup nestled in the heart of Boulder's thriving tech ecosystem, has secured $40M in Series B funding — marking a watershed moment for the observability landscape. The platform serves as a unified hub, featuring real-time dashboards, boasting sub-second queries, and presenting a seamless integration layer. Moreover, experts believe Acme is poised to disrupt the market. In conclusion, the future looks bright!

Final rewrite:

Acme Analytics, a Boulder-based startup, raised a $40M Series B. Its observability platform has real-time dashboards, runs queries in under a second, and includes an integration layer.

Verification: One editing pass. Review found no further justified in-scope edit; no deterministic preservation check ran in this prose-only demo.

What it caught: the chatbot opener ("Certainly!"), promotional modifiers, inflated significance, roundabout verbs, vague attribution, and the generic conclusion. The rewrite keeps the funding, location, and three product capabilities. It removes the unsupported market prediction without inventing an investor or an integration mechanism.

Why a skill, not just a prompt

A one-shot "make this sound human" prompt catches the obvious stuff. This skill is different:

• Single final rewrite — completes its audit, correction, and available verification before returning one full version. A short change summary follows when useful; a detailed audit remains available on request without adding a competing draft.
• Two-pass editing — review can catch patterns that survive the first edit, while one shared limit covers both corrective edits and preservation repairs.
• Surface-aware delivery — checks how the destination renders single newlines before returning prose, unwraps accidental hard-wrapped paragraphs only when those breaks would show, and preserves intentional structure such as lists, poetry, code, and addresses.
• 112-entry word replacement table across 3 tiers + 10 Tier 3 phrases — not vibes-based. Every flagged word has a specific, plainer alternative. "Leverage" → "use." "Commence" → "start." 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 itself splits into 1A frequency markers (delve, tapestry) and 1B clarity edits (in order to, utilize) — same fix, but only 1A is evidence about how a passage was produced, and 1B is weighted lower so a wordiness fix cannot push a document toward an AI classification. Tier 3 phrases (multi-word boilerplate like "the integration of," "decentralized compute") flag on per-phrase repetition or when 3+ distinct phrases stack in one piece — the LLM-self-varies-boilerplate shape.
• 74 pattern categories — representative examples below, each with before/after. Includes structural detection (hashtag stuffing, bare-NP bullet lists, hedge-stacked predictions), AI-tool fingerprints (placeholders, citation markup, UTM params), rhythm/uniformity checks, conversational-register tells, and writer-side tests. The full catalog lives in references/patterns.md; this count is enforced against it in CI.
• Detect mode — flag patterns without rewriting. See which flags are real problems vs. judgment calls. Useful when patterns might be intentional or you're auditing content you don't want altered.
• Works across platforms — a directory-based skill runs in Claude Code, Cowork (as a plugin), OpenClaw, Cursor (as a ported rule), and other directory-aware agents. See the install paths below.

Installation & Usage

Install the complete skill directory

Use the plugin install below or clone the repository into your agent's skills directory. Keep SKILL.md with references/patterns.md: the entry file loads the catalog before auditing. The bundled scripts/, detector/, and examples/ provide optional mechanical verification.

For a single-file rules field, use dist/avoid-ai-writing.md (about 138 KB). It includes every rule and profile, with manual fallbacks for commands unavailable outside the bundle. Some rules and instructions fields hold far less than that, so check the size limits under Other agents before pasting. Do not copy the slim entry file alone. Older installers that fetch only root SKILL.md omit its required reference; use a directory install instead.

Claude Code

Option 1: Clone into skills directory

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

Then invoke it with /avoid-ai-writing <your text>.

Option 2: Copy a self-contained file

Download dist/avoid-ai-writing.md and place it in any directory that Claude Code can read. Reference it in your CLAUDE.md:

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

Option 3: Use as a slash command

Optional alias. Claude Code names a command after its file, so use a different name from avoid-ai-writing. If you've done Option 1, the skill already answers to /avoid-ai-writing and a command file with the same name would collide with it. Create a command file (e.g., ~/.claude/commands/clean-ai-writing.md):

---
description: Audit and rewrite content to remove AI writing patterns
---

$ARGUMENTS

Read and follow the instructions in ~/.claude/skills/avoid-ai-writing/SKILL.md

Then use /clean-ai-writing <your text> in Claude Code.

Claude Cowork — install as a plugin

Cowork loads skills only from installed plugins — it doesn't scan ~/.claude/skills/, so a bare clone (the Claude Code steps above) won't be discovered there. This repo doubles as a single-plugin marketplace, so install it as a plugin instead:

/plugin marketplace add conorbronsdon/avoid-ai-writing
/plugin install avoid-ai-writing@conorbronsdon-skills
/reload-plugins   # or restart the session, to activate the skill

In the Cowork desktop app, do the same from Customize → Plugins → Add marketplace from GitHub (conorbronsdon/avoid-ai-writing), then install avoid-ai-writing. The skill auto-triggers from phrases like "remove AI-isms." New releases arrive when the plugin's version is bumped — run /plugin marketplace update to pull them.

The same plugin install works in Claude Code if you'd rather have a versioned, updatable plugin than the file clone above.